@yemi33/minions 0.1.1773 → 0.1.1775

package/CHANGELOG.md

@@ -1,11 +1,20 @@
 # Changelog
 
-## 0.1.1773 (2026-05-07)
+## 0.1.1775 (2026-05-07)
+
+### Features
+-  Improve dashboard API route metadata
+- suppress stale doc-chat model errors
+
+### Fixes
+- yemi33/minions#2168
+-  honor central plan work item project
+-  restore canonical-home shared helpers
+- yemi33/minions#2170
+
+## 0.1.1772 (2026-05-07)
 
 ### Features
-- fix doc chat sticky scroll (#2176)
-- fix live output route and CLI docs (#2172)
-- make API project resolution strict (#2169)
 - fix copilot cc resume context (#2166)
 
 ## 0.1.1771 (2026-05-07)

package/bin/minions.js

@@ -39,6 +39,7 @@ const os = require('os');
 const { spawn, spawnSync, execSync } = require('child_process');
 
 const PKG_ROOT = path.resolve(__dirname, '..');
+const shared = require(path.join(PKG_ROOT, 'engine', 'shared'));
 const DASH_PORT = 7331;
 const DASHBOARD_BROWSER_PRESENCE_MAX_AGE_MS = 45000;
 
@@ -152,8 +153,6 @@ function spawnDashboard(suppressOpen) {
   return proc;
 }
 
-const DEFAULT_MINIONS_HOME = path.join(os.homedir(), '.minions');
-const ROOT_POINTER_PATH = path.join(os.homedir(), '.minions-root');
 const LEGACY_DEFAULT_SQUAD_HOME = path.join(os.homedir(), '.squad');
 const LEGACY_ROOT_POINTER_PATH = path.join(os.homedir(), '.squad-root');
 
@@ -171,13 +170,6 @@ function isLegacyInstalledRoot(dir) {
     fs.existsSync(path.join(dir, 'squad.js'));
 }
 
-function readRootPointer() {
-  try {
-    const p = fs.readFileSync(ROOT_POINTER_PATH, 'utf8').trim();
-    return p ? path.resolve(p) : null;
-  } catch { return null; }
-}
-
 function readLegacyRootPointer() {
   try {
     const p = fs.readFileSync(LEGACY_ROOT_POINTER_PATH, 'utf8').trim();
@@ -186,7 +178,7 @@ function readLegacyRootPointer() {
 }
 
 function saveRootPointer(root) {
-  try { fs.writeFileSync(ROOT_POINTER_PATH, root); } catch {}
+  shared.saveMinionsRootPointer(root);
 }
 
 function findLegacySquadRoot() {
@@ -254,17 +246,7 @@ function migrateLegacyInstallIfNeeded(targetHome) {
 }
 
 function resolveMinionsHome(forInit = false) {
-  const envHome = process.env.MINIONS_HOME ? path.resolve(process.env.MINIONS_HOME) : null;
-  if (envHome) return envHome;
-
-  if (forInit) return DEFAULT_MINIONS_HOME;
-
-  const pointerRoot = readRootPointer();
-  if (isInstalledRoot(pointerRoot)) return pointerRoot;
-
-  if (isInstalledRoot(DEFAULT_MINIONS_HOME)) return DEFAULT_MINIONS_HOME;
-
-  return DEFAULT_MINIONS_HOME;
+  return shared.resolveMinionsHome(forInit);
 }
 
 const [cmd, ...rest] = process.argv.slice(2);

package/dashboard.js

@@ -1334,13 +1334,116 @@ const PREAMBLE_TTL = 30000; // 30s — longer TTL since preamble is lightweight
 // captures no-op via the truthy guard.
 let _ccApiRoutesMeta = null;
 
+function _routePathForMeta(route) {
+  if (!route) return '';
+  if (typeof route.path === 'string') return route.path;
+  return route.template || route.pathTemplate || String(route.path);
+}
+
+function _parseRouteParamHint(paramHint, method) {
+  if (!paramHint || typeof paramHint !== 'string') return [];
+  const paramLocation = ['GET', 'HEAD', 'DELETE'].includes(String(method || '').toUpperCase()) ? 'query' : 'body';
+  const parts = [];
+  let current = '';
+  let parenDepth = 0;
+  for (const ch of paramHint) {
+    if (ch === '(') parenDepth++;
+    if (ch === ')' && parenDepth > 0) parenDepth--;
+    if (ch === ',' && parenDepth === 0) {
+      parts.push(current);
+      current = '';
+      continue;
+    }
+    current += ch;
+  }
+  if (current) parts.push(current);
+  return parts
+    .map(part => {
+      const raw = part.trim();
+      if (!raw) return null;
+      let text = raw;
+      let description = '';
+      text = text.replace(/\(([^)]*)\)/g, (_, desc) => {
+        description = desc.trim();
+        return '';
+      }).trim();
+      const required = !text.includes('?');
+      const array = text.includes('[]');
+      const name = text
+        .replace(/\?/g, '')
+        .replace(/\[\]/g, '')
+        .trim()
+        .split(/\s+/)[0];
+      if (!name) return null;
+      return {
+        name,
+        in: paramLocation,
+        required,
+        ...(description ? { description } : {}),
+        ...(array ? { type: 'array' } : {}),
+      };
+    })
+    .filter(Boolean);
+}
+
+function _routePathParams(pathTemplate) {
+  if (!pathTemplate || typeof pathTemplate !== 'string') return [];
+  const params = [];
+  for (const match of pathTemplate.matchAll(/:([A-Za-z][A-Za-z0-9_]*)/g)) {
+    params.push({ name: match[1], in: 'path', required: true });
+  }
+  return params;
+}
+
+function _routeParametersForMeta(route, pathTemplate) {
+  const seen = new Set();
+  const params = [..._routePathParams(pathTemplate), ..._parseRouteParamHint(route.params, route.method)];
+  return params.filter(param => {
+    const key = `${param.in}:${param.name}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function _routeReadOnly(route) {
+  if (typeof route.readOnly === 'boolean') return route.readOnly;
+  return ['GET', 'HEAD', 'OPTIONS'].includes(String(route.method || '').toUpperCase());
+}
+
+function _routeDestructive(route, pathTemplate, readOnly) {
+  if (typeof route.destructive === 'boolean') return route.destructive;
+  if (readOnly) return false;
+  if (String(route.method || '').toUpperCase() === 'DELETE') return true;
+  const haystack = `${pathTemplate || ''} ${route.desc || ''}`.toLowerCase();
+  return /\b(delete|remove|cancel|kill|reset|restart|archive|unarchive|abort|purge|reject|pause|unlink|clear)\b/.test(haystack);
+}
+
+function _routeGenericFallback(route, pathTemplate) {
+  if (typeof route.genericFallback === 'boolean') return route.genericFallback;
+  if (!pathTemplate || !pathTemplate.startsWith('/api/')) return false;
+  if (String(route.method || '').toUpperCase() !== 'POST') return false;
+  const haystack = `${pathTemplate} ${route.desc || ''}`.toLowerCase();
+  if (haystack.includes('sse') || /\bstreaming\b/.test(haystack) || /\/stream(?:$|[/?#])/.test(pathTemplate)) return false;
+  return true;
+}
+
 function _routesAsMeta(routes) {
-  return routes.map(r => ({
-    method: r.method,
-    path: typeof r.path === 'string' ? r.path : String(r.path),
-    desc: r.desc || '',
-    params: r.params || null,
-  }));
+  return routes.map(r => {
+    const pathTemplate = _routePathForMeta(r);
+    const readOnly = _routeReadOnly(r);
+    const destructive = _routeDestructive(r, pathTemplate, readOnly);
+    return {
+      method: r.method,
+      path: pathTemplate,
+      desc: r.desc || '',
+      params: r.params || null,
+      parameters: _routeParametersForMeta(r, pathTemplate),
+      readOnly,
+      destructive,
+      genericFallback: _routeGenericFallback(r, pathTemplate),
+    };
+  });
 }
 
 function _captureApiRoutesMeta(routes) {
@@ -1354,7 +1457,13 @@ function _formatCcApiRoutesIndex() {
     .filter(r => r.path.startsWith('/api/'))
     .map(r => {
       const params = r.params ? ` — params: ${r.params}` : '';
-      return `- \`${r.method} ${r.path}\` — ${r.desc}${params}`;
+      const flags = [
+        r.readOnly ? 'read-only' : null,
+        r.destructive ? 'destructive' : null,
+        r.genericFallback ? 'generic-fallback' : null,
+      ].filter(Boolean);
+      const flagText = flags.length ? ` — flags: ${flags.join(', ')}` : '';
+      return `- \`${r.method} ${r.path}\` — ${r.desc}${params}${flagText}`;
     })
     .join('\n');
 }
@@ -1405,7 +1514,7 @@ ${apiIndex || '(routes not yet captured — first request still pending)'}
 ### CLI Index (auto-generated from engine/cli.js CLI_COMMAND_DOCS — single source of truth)
 ${cliIndex || '(unavailable)'}
 
-For any \`/api/...\` endpoint not covered by a named CC action, use the generic fallback:
+For \`POST /api/...\` endpoints marked \`generic-fallback\` and not covered by a named CC action, use the generic fallback:
 \`{"type":"<descriptive>","endpoint":"/api/...","params":{...}}\`.` : '';
 
   const result = `### Agents
@@ -2721,23 +2830,19 @@ function _formatDocChatContext({ document, title, filePath, selection, canEdit,
   return context;
 }
 
-// Map errorClass codes from the runtime adapter to actionable user-facing messages.
+// Map runtime failures to user-facing messages.
 // sessionPreserved=true means ccCall preserved the session — user can retry immediately.
 // toolUses=[] from result.toolUses lets the message warn that tools may have already
 // modified files/state before the failure — the user shouldn't assume nothing happened.
-// errorMessage is the runtime adapter's own remediation string (from parseError) —
-// authoritative because it knows whether the runtime is Claude, Copilot, or another;
-// dashboard falls back to generic copy only when the adapter didn't supply one.
+// errorMessage is the runtime adapter's own text from parseError; when present it
+// is authoritative and is shown directly rather than replaced with dashboard copy.
 function _docChatErrorMessage(errorClass, sessionPreserved = false, toolUses = [], errorMessage = null) {
   const tools = Array.isArray(toolUses) ? toolUses : [];
   const toolHint = tools.length > 0
     ? ` (${tools.length} tool${tools.length === 1 ? '' : 's'} ran before the failure: ${tools.slice(0, 5).map(t => t.name).join(', ')}${tools.length > 5 ? '…' : ''} — files or state may have been modified.)`
     : '';
-  if (errorClass === 'auth-failure') return (errorMessage || 'Runtime authentication failed — check your CLI auth or API key, then try again.') + toolHint;
-  if (errorClass === 'context-limit') return 'Session context is too long. Click "Clear" to start a fresh conversation.' + toolHint;
-  if (errorClass === 'budget-exceeded') return (errorMessage || 'Runtime budget exceeded — check your account or quota.') + toolHint;
-  if (errorClass === 'crash') return (errorMessage || 'Runtime crashed unexpectedly. Try again.') + toolHint;
-  if (errorClass === 'unknown-model') return (errorMessage || 'Configured model is not valid for the active runtime. Update engine.ccModel or engine.defaultModel.') + toolHint;
+  const directError = typeof errorMessage === 'string' ? errorMessage.trim() : '';
+  if (directError) return directError + toolHint;
   if (sessionPreserved) return 'Temporary connection issue — your conversation is intact, send your message again.' + toolHint;
   if (tools.length > 0) return 'The agent stopped responding before producing a final answer.' + toolHint;
   return 'Failed to process request. Try again.';
@@ -2746,14 +2851,26 @@ function _docChatErrorMessage(errorClass, sessionPreserved = false, toolUses = [
 // Secondary note rendered alongside a recovered partial answer — distinct from the
 // hard-failure message because the answer/actions/document-edit DID land. The user
 // just needs to know the run wasn't clean.
-function _docChatPartialWarning(errorClass) {
-  if (errorClass === 'auth-failure') return 'Note: auth failed — answer recovered from partial output, but follow-up turns may not work.';
-  if (errorClass === 'context-limit') return 'Note: session context was too long — answer recovered. Click "Clear" before continuing.';
-  if (errorClass === 'budget-exceeded') return 'Note: runtime budget exceeded — answer recovered, but further calls may fail.';
-  if (errorClass === 'crash') return 'Note: runtime crashed before clean exit, but a complete response was recovered.';
+function _docChatPartialWarning(errorClass, errorMessage = null) {
+  const directError = typeof errorMessage === 'string' ? errorMessage.trim() : '';
+  if (directError) return `Note: ${directError}`;
   return 'Note: the agent exited unexpectedly. A complete response was recovered — verify any saved files or dispatched actions.';
 }
 
+function _docChatResultHasVisibleError(result) {
+  if (!result) return false;
+  if (result.errorClass) return true;
+  if (typeof result.errorMessage === 'string' && result.errorMessage.trim()) return true;
+  // stderr without a classified/runtime error is often CLI diagnostics; hard
+  // failures with no answer still surface stderr through _docChatFailureResponse.
+  return false;
+}
+
+function _docChatResultLooksSuccessful(result) {
+  if (!result || !result.text) return false;
+  return result.code === 0 || !_docChatResultHasVisibleError(result);
+}
+
 // Build the doc-chat extraContext for a single ccCall pass — refreshed on retry
 // so a fresh-session retry includes the full document instead of relying on the
 // dead session's prior turn for context.
@@ -2830,7 +2947,7 @@ function _recoverPartialDocChatResponse(result, sessionKey) {
   return {
     ...parsed,
     partial: true,
-    warning: _docChatPartialWarning(result.errorClass),
+    warning: _docChatPartialWarning(result.errorClass, result.errorMessage || result.stderr || null),
     toolUses: Array.isArray(result.toolUses) ? result.toolUses : [],
     // Recovery path still attaches the raw runtime failure — the answer landed
     // despite a non-zero exit; users still benefit from seeing why.
@@ -2838,6 +2955,41 @@ function _recoverPartialDocChatResponse(result, sessionKey) {
   };
 }
 
+function _shouldSuppressDocChatPostPatchError(ccError, finalize) {
+  if (!finalize || finalize.edited !== true) return false;
+  if (!ccError || ccError.errorClass !== 'unknown-model') return false;
+  return String(ccError.runtime || '').toLowerCase() === 'copilot';
+}
+
+function _buildDocChatResponsePayload({
+  answer,
+  actions,
+  actionResults,
+  actionParseError,
+  ccError,
+  partial,
+  warning,
+  toolUses,
+  finalize,
+} = {}) {
+  const final = finalize || { edited: false, content: null, answerSuffix: '' };
+  const suppressPostPatchError = _shouldSuppressDocChatPostPatchError(ccError, final);
+  const visibleAnswer = suppressPostPatchError && !partial ? 'Updated the document.' : answer;
+  const finalAnswer = final.answerSuffix ? visibleAnswer + final.answerSuffix : visibleAnswer;
+  return {
+    ok: !(ccError && !suppressPostPatchError),
+    answer: finalAnswer,
+    actions,
+    ...(actionResults ? { actionResults } : {}),
+    ...(actionParseError ? { actionParseError } : {}),
+    ...(ccError && !suppressPostPatchError ? { error: ccError } : {}),
+    ...(partial && !suppressPostPatchError ? { partial: true, warning } : {}),
+    ...(Array.isArray(toolUses) && toolUses.length ? { toolUses } : {}),
+    edited: final.edited,
+    ...(final.edited && final.content !== null ? { content: final.content } : {}),
+  };
+}
+
 
 // True when the file is a meeting JSON whose status forbids edits. Loaded
 // fresh on each call because meeting status can change while a doc-chat is
@@ -2990,7 +3142,7 @@ async function ccDocCall({ message, document, title, filePath, selection, canEdi
     // bleed into future interactions under the same key.
     docSessions.delete(sessionKey);
     schedulePersistDocSessions();
-  } else if (result.code === 0 && result.sessionId) {
+  } else if (_docChatResultLooksSuccessful(result) && result.sessionId) {
     // Store doc hash for next call's unchanged check
     const session = resolveSession('doc', sessionKey);
     if (session) session._docHash = initialPass.docHash;
@@ -3000,7 +3152,7 @@ async function ccDocCall({ message, document, title, filePath, selection, canEdi
     return { answer: result.text || result.stderr || 'Minions runtime is not installed or configured.', content: null, actions: [] };
   }
 
-  if (result.code !== 0 || !result.text) {
+  if (!_docChatResultLooksSuccessful(result)) {
     // Try to salvage a parseable answer / action / document edit before failing.
     const recovered = _recoverPartialDocChatResponse(result, sessionKey);
     if (recovered) return recovered;
@@ -3051,7 +3203,7 @@ async function ccDocCallStreaming({ message, document, title, filePath, selectio
   if (freshSession && sessionKey) {
     docSessions.delete(sessionKey);
     schedulePersistDocSessions();
-  } else if (result.code === 0 && result.sessionId) {
+  } else if (_docChatResultLooksSuccessful(result) && result.sessionId) {
     const session = resolveSession('doc', sessionKey);
     if (session) session._docHash = initialPass.docHash;
   }
@@ -3060,7 +3212,7 @@ async function ccDocCallStreaming({ message, document, title, filePath, selectio
     return { answer: result.text || result.stderr || 'Minions runtime is not installed or configured.', content: null, actions: [] };
   }
 
-  if (result.code !== 0 || !result.text) {
+  if (!_docChatResultLooksSuccessful(result)) {
     const recovered = _recoverPartialDocChatResponse(result, sessionKey);
     if (recovered) return recovered;
     const sessionPreserved = !!(resolveSession('doc', sessionKey)?.sessionId);
@@ -5201,20 +5353,11 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         filePath: body.filePath, fullPath, isJson, canEdit,
         originalContent: currentContent, delimiterContent: content,
       });
-      const finalAnswer = finalize.answerSuffix ? answer + finalize.answerSuffix : answer;
-      _docDone = true;
-      return jsonReply(res, 200, {
-        ok: !ccError,
-        answer: finalAnswer,
-        actions,
-        ...(actionResults ? { actionResults } : {}),
-        ...(actionParseError ? { actionParseError } : {}),
-        ...(ccError ? { error: ccError } : {}),
-        ...(partial ? { partial: true, warning } : {}),
-        ...(Array.isArray(toolUses) && toolUses.length ? { toolUses } : {}),
-        edited: finalize.edited,
-        ...(finalize.edited && finalize.content !== null ? { content: finalize.content } : {}),
+      const payload = _buildDocChatResponsePayload({
+        answer, actions, actionResults, actionParseError, ccError, partial, warning, toolUses, finalize,
       });
+      _docDone = true;
+      return jsonReply(res, 200, payload);
       } finally { _docAbort = null; _docDone = true; docChatInFlight.delete(docKey); }
     } catch (e) { return jsonReply(res, e.statusCode || 500, { error: e.message }); }
   }
@@ -5303,18 +5446,14 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           filePath: body.filePath, fullPath, isJson, canEdit,
           originalContent: currentContent, delimiterContent: content,
         });
-        const finalAnswer = finalize.answerSuffix ? answer + finalize.answerSuffix : answer;
+        const payload = _buildDocChatResponsePayload({
+          answer, actions, actionResults, actionParseError, ccError, partial, warning, toolUses, finalize,
+        });
+        const { answer: finalAnswer, ...donePayload } = payload;
         writeDocEvent({
           type: 'done',
           text: finalAnswer,
-          actions,
-          ...(actionResults ? { actionResults } : {}),
-          ...(actionParseError ? { actionParseError } : {}),
-          ...(ccError ? { error: ccError } : {}),
-          ...(partial ? { partial: true, warning } : {}),
-          ...(Array.isArray(toolUses) && toolUses.length ? { toolUses } : {}),
-          edited: finalize.edited,
-          ...(finalize.edited && finalize.content !== null ? { content: finalize.content } : {}),
+          ...donePayload,
         });
         _docStreamEnded = true;
         res.end();
@@ -7122,8 +7261,8 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     { method: 'POST', path: '/api/plans/unarchive', desc: 'Restore a plan/PRD from archive', params: 'file', handler: handlePlansUnarchive },
     { method: 'POST', path: '/api/plans/revise', desc: 'Request revision with feedback, dispatches agent to revise', params: 'file, feedback, requestedBy?', handler: handlePlansRevise },
     { method: 'POST', path: '/api/plans/discuss', desc: 'Generate a plan discussion session script for Claude CLI', params: 'file', handler: handlePlansDiscuss },
-    { method: 'GET', path: /^\/api\/plans\/archive\/([^?]+)$/, desc: 'Read an archived plan file', handler: handlePlansArchiveRead },
-    { method: 'GET', path: /^\/api\/plans\/([^?]+)$/, desc: 'Read a full plan (JSON from prd/ or markdown from plans/)', handler: handlePlansRead },
+    { method: 'GET', path: /^\/api\/plans\/archive\/([^?]+)$/, template: '/api/plans/archive/:file', desc: 'Read an archived plan file', handler: handlePlansArchiveRead },
+    { method: 'GET', path: /^\/api\/plans\/([^?]+)$/, template: '/api/plans/:file', desc: 'Read a full plan (JSON from prd/ or markdown from plans/)', handler: handlePlansRead },
 
     // PRD items
     { method: 'POST', path: '/api/prd-items', desc: 'Create a PRD item as a plan file in prd/ (auto-approved)', params: 'name, description?, priority?, estimated_complexity?, project?, id?', handler: handlePrdItemsCreate },
@@ -7295,13 +7434,13 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       });
     }},
     { method: 'POST', path: '/api/agents/cancel', desc: 'Cancel an active agent by ID or task substring', params: 'agent?, task?', handler: handleAgentsCancel },
-    { method: 'POST', path: /^\/api\/agent\/([\w-]+)\/kill$/, desc: 'Kill a running agent: stop process, clear dispatch, reset work items to pending', handler: handleAgentKill },
-    { method: 'GET', path: /^\/api\/agent\/([\w-]+)\/live-stream(?:\?.*)?$/, desc: 'SSE real-time live output streaming', handler: handleAgentLiveStream },
-    { method: 'GET', path: /^\/api\/agent\/([\w-]+)\/live(?:\?.*)?$/, desc: 'Tail live output for a working agent', params: 'tail? (bytes, default 8192)', handler: handleAgentLive },
-    { method: 'GET', path: /^\/api\/agent\/([\w-]+)\/live-output(?:\?.*)?$/, desc: 'Tail live output for a working agent (alias for /live)', params: 'tail? (bytes, default 8192)', handler: handleAgentLive },
-    { method: 'GET', path: /^\/api\/agent\/([\w-]+)\/output(?:\?.*)?$/, desc: 'Fetch final output.log for an agent', handler: handleAgentOutput },
-    { method: 'GET', path: /^\/api\/agent\/([\w-]+)$/, desc: 'Get detailed agent info', handler: handleAgentDetail },
-    { method: 'GET', path: /^\/api\/dispatch\/([\w.-]+)\/completion-report$/, desc: 'Read structured completion report for a dispatch', handler: (req, res, match) => {
+    { method: 'POST', path: /^\/api\/agent\/([\w-]+)\/kill$/, template: '/api/agent/:id/kill', desc: 'Kill a running agent: stop process, clear dispatch, reset work items to pending', handler: handleAgentKill },
+    { method: 'GET', path: /^\/api\/agent\/([\w-]+)\/live-stream(?:\?.*)?$/, template: '/api/agent/:id/live-stream', desc: 'SSE real-time live output streaming', handler: handleAgentLiveStream },
+    { method: 'GET', path: /^\/api\/agent\/([\w-]+)\/live(?:\?.*)?$/, template: '/api/agent/:id/live', desc: 'Tail live output for a working agent', params: 'tail? (bytes, default 8192)', handler: handleAgentLive },
+    { method: 'GET', path: /^\/api\/agent\/([\w-]+)\/live-output(?:\?.*)?$/, template: '/api/agent/:id/live-output', desc: 'Tail live output for a working agent (alias for /live)', params: 'tail? (bytes, default 8192)', handler: handleAgentLive },
+    { method: 'GET', path: /^\/api\/agent\/([\w-]+)\/output(?:\?.*)?$/, template: '/api/agent/:id/output', desc: 'Fetch final output.log for an agent', handler: handleAgentOutput },
+    { method: 'GET', path: /^\/api\/agent\/([\w-]+)$/, template: '/api/agent/:id', desc: 'Get detailed agent info', handler: handleAgentDetail },
+    { method: 'GET', path: /^\/api\/dispatch\/([\w.-]+)\/completion-report$/, template: '/api/dispatch/:id/completion-report', desc: 'Read structured completion report for a dispatch', handler: (req, res, match) => {
       const id = match && match[1];
       const payload = queries.getDispatchCompletionReport(id);
       if (!payload) return jsonReply(res, 404, { error: 'completion report not found' }, req);
@@ -7337,7 +7476,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     }},
     { method: 'POST', path: '/api/knowledge/sweep', desc: 'Trigger async KB sweep (returns 202)', handler: handleKnowledgeSweep },
     { method: 'GET', path: '/api/knowledge/sweep/status', desc: 'Poll KB sweep status', handler: handleKnowledgeSweepStatus },
-    { method: 'GET', path: /^\/api\/knowledge\/([^/]+)\/([^?]+)/, desc: 'Read a specific knowledge base entry', handler: handleKnowledgeRead },
+    { method: 'GET', path: /^\/api\/knowledge\/([^/]+)\/([^?]+)/, template: '/api/knowledge/:category/:file', desc: 'Read a specific knowledge base entry', handler: handleKnowledgeRead },
 
     // Doc chat
     { method: 'POST', path: '/api/doc-chat', desc: 'Minions-aware doc Q&A + editing via CC session', params: 'message, document, title?, filePath?, selection?, contentHash?', handler: handleDocChat },
@@ -7368,7 +7507,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     { method: 'POST', path: '/api/command-center', desc: 'Conversational command center with full minions context', params: 'message, sessionId?', handler: handleCommandCenter },
     { method: 'POST', path: '/api/command-center/stream', desc: 'Streaming CC — SSE with text chunks as they arrive', params: 'message, tabId?', handler: handleCommandCenterStream },
     { method: 'GET', path: '/api/cc-sessions', desc: 'List CC session metadata for all tabs', handler: handleCCSessionsList },
-    { method: 'DELETE', path: /^\/api\/cc-sessions\/([\w-]+)$/, desc: 'Delete a CC session by tab ID', handler: handleCCSessionDelete },
+    { method: 'DELETE', path: /^\/api\/cc-sessions\/([\w-]+)$/, template: '/api/cc-sessions/:id', desc: 'Delete a CC session by tab ID', handler: handleCCSessionDelete },
 
     // Schedules
     { method: 'POST', path: '/api/schedules/parse-natural', desc: 'Parse natural language schedule text into cron expression', params: 'text', handler: handleSchedulesParseNatural },
@@ -7514,7 +7653,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       return jsonReply(res, 200, { meetings: getMeetings() });
     }},
 
-    { method: 'GET', path: /^\/api\/meetings\/(MTG-[\w]+)$/, desc: 'Get meeting detail', handler: async (req, res, match) => {
+    { method: 'GET', path: /^\/api\/meetings\/(MTG-[\w]+)$/, template: '/api/meetings/:id', desc: 'Get meeting detail', handler: async (req, res, match) => {
       const { getMeeting } = require('./engine/meeting');
       const meeting = getMeeting(match[1]);
       if (!meeting) return jsonReply(res, 404, { error: 'Meeting not found' });
@@ -7589,7 +7728,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       const md = require('./engine/model-discovery');
       return jsonReply(res, 200, { runtimes: md.listAllRuntimes() }, req);
     }},
-    { method: 'POST', path: /^\/api\/runtimes\/([\w-]+)\/models\/refresh$/, desc: 'Invalidate the models cache for a runtime and re-fetch', handler: async (req, res, match) => {
+    { method: 'POST', path: /^\/api\/runtimes\/([\w-]+)\/models\/refresh$/, template: '/api/runtimes/:runtime/models/refresh', desc: 'Invalidate the models cache for a runtime and re-fetch', handler: async (req, res, match) => {
       const md = require('./engine/model-discovery');
       const name = match[1];
       try {
@@ -7608,7 +7747,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       }
       return jsonReply(res, 200, payload, req);
     }},
-    { method: 'GET', path: /^\/api\/runtimes\/([\w-]+)\/models$/, desc: 'Get cached or fresh model list for a runtime', handler: async (req, res, match) => {
+    { method: 'GET', path: /^\/api\/runtimes\/([\w-]+)\/models$/, template: '/api/runtimes/:runtime/models', desc: 'Get cached or fresh model list for a runtime', handler: async (req, res, match) => {
       const md = require('./engine/model-discovery');
       const name = match[1];
       let payload;
@@ -7753,6 +7892,10 @@ module.exports = {
   _docChatPartialWarning,
   _docChatFailureResponse,
   _recoverPartialDocChatResponse,
+  _docChatResultHasVisibleError,
+  _docChatResultLooksSuccessful,
+  _shouldSuppressDocChatPostPatchError,
+  _buildDocChatResponsePayload,
   _linkPullRequestForTracking: linkPullRequestForTracking,
   _resolveSkillReadPath,
   DOC_CHAT_DOCUMENT_DELIMITER,
@@ -7764,6 +7907,7 @@ module.exports = {
   _createPipelineFromAction: createPipelineFromAction,
   executeCCActions,
   buildCCStatePreamble,
+  _routesAsMeta,
   _buildTranscriptCarryover,
   _ccRuntimeNeedsResumeCarryover,
   _joinCcPromptParts,

package/engine/copilot-models.json

@@ -1,5 +1,5 @@
 {
   "runtime": "copilot",
   "models": null,
-  "cachedAt": "2026-05-07T17:23:11.001Z"
+  "cachedAt": "2026-05-07T21:35:37.002Z"
 }

package/engine/runtimes/copilot.js

@@ -634,25 +634,77 @@ function parseStreamChunk(line) {
 
 // ── Error Normalization ─────────────────────────────────────────────────────
 
-function parseError(rawOutput) {
+function _collectErrorSignal(rawOutput) {
   const text = rawOutput == null ? '' : String(rawOutput);
+  if (!text) return '';
+
+  const signals = [];
+  let sawJsonLine = false;
+  for (const rawLine of text.split('\n')) {
+    const line = rawLine.trim();
+    if (!line) continue;
+    if (!line.startsWith('{')) {
+      signals.push(line);
+      continue;
+    }
+
+    let obj;
+    try { obj = JSON.parse(line); } catch { continue; }
+    if (!obj || typeof obj !== 'object') continue;
+    sawJsonLine = true;
+
+    const type = String(obj.type || '');
+    const subtype = String(obj.subtype || '');
+    const eventType = String(obj.event?.type || '');
+    const isErrorEvent = type === 'error'
+      || eventType === 'error'
+      || subtype.startsWith('error')
+      || obj.is_error === true
+      || obj.error != null
+      || obj.data?.error != null;
+    if (!isErrorEvent) continue;
+
+    for (const value of [
+      obj.error,
+      obj.message,
+      obj.stderr,
+      obj.result,
+      obj.data?.error,
+      obj.data?.message,
+      obj.data?.stderr,
+      obj.event?.error,
+      obj.event?.message,
+      subtype,
+    ]) {
+      if (typeof value === 'string' && value.trim()) signals.push(value.trim());
+    }
+  }
+
+  if (signals.length > 0) return signals.join('\n');
+  return sawJsonLine ? '' : text;
+}
+
+function parseError(rawOutput) {
+  const text = _collectErrorSignal(rawOutput);
   if (!text) return { message: '', code: null, retriable: true };
   const lower = text.toLowerCase();
 
-  if (/not authenticated|copilot login|please.*log.*in|401|403 forbidden|unauthorized/i.test(text)) {
-    return { message: 'Copilot/GitHub authentication failed. Run `gh auth login` or provide GH_TOKEN/COPILOT_GITHUB_TOKEN with Copilot access.', code: 'auth-failure', retriable: false };
+  const hasExplicitAuthFailure = /not authenticated|copilot login|please.*log.*in|\bunauthorized\b/i.test(text);
+  const hasAuthStatusCode = /\b(?:http(?:\/\d(?:\.\d)?)?|status(?:\s+code)?|statuscode|response(?:\s+status)?|api(?:\s+(?:error|response|status))?)\s*[:=]?\s*(?:401|403)\b|\b(?:401\s+unauthorized|403\s+forbidden)\b/i.test(text);
+  if (hasExplicitAuthFailure || hasAuthStatusCode) {
+    return { message: text, code: 'auth-failure', retriable: false };
   }
   if (/rate limit|too many requests|\b429\b/i.test(text)) {
-    return { message: 'Copilot rate limit hit', code: 'rate-limit', retriable: true };
+    return { message: text, code: 'rate-limit', retriable: true };
   }
   if (/unknown model|model not found|model.*invalid|invalid model/i.test(text)) {
-    return { message: 'Copilot rejected the requested model', code: 'unknown-model', retriable: false };
+    return { message: text, code: 'unknown-model', retriable: false };
   }
   if (/budget.*exceed|premium.*limit.*reach|quota.*exceed/i.test(lower)) {
-    return { message: 'Copilot premium-request budget exceeded — check your GitHub Copilot quota.', code: 'budget-exceeded', retriable: false };
+    return { message: text, code: 'budget-exceeded', retriable: false };
   }
   if (/internal error|panic|uncaught|copilot.*crashed|fatal: copilot/i.test(lower)) {
-    return { message: 'Copilot CLI crashed unexpectedly. Try again.', code: 'crash', retriable: true };
+    return { message: text, code: 'crash', retriable: true };
   }
   return { message: '', code: null, retriable: true };
 }

package/engine/shared.js

@@ -5,9 +5,58 @@
 
 const fs = require('fs');
 const path = require('path');
+const os = require('os');
 const crypto = require('crypto');
 
-const MINIONS_DIR = process.env.MINIONS_TEST_DIR || (process.env.MINIONS_HOME ? path.resolve(process.env.MINIONS_HOME) : path.resolve(__dirname, '..'));
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+const DEFAULT_MINIONS_HOME = path.join(os.homedir(), '.minions');
+const ROOT_POINTER_PATH = path.join(os.homedir(), '.minions-root');
+
+function isInstalledRoot(dir) {
+  if (!dir) return false;
+  return fs.existsSync(path.join(dir, 'engine.js')) &&
+    fs.existsSync(path.join(dir, 'dashboard.js')) &&
+    fs.existsSync(path.join(dir, 'minions.js'));
+}
+
+function isSourceCheckoutRoot(dir) {
+  return !!dir && fs.existsSync(path.join(dir, '.git'));
+}
+
+function readMinionsRootPointer() {
+  try {
+    const p = fs.readFileSync(ROOT_POINTER_PATH, 'utf8').trim();
+    return p ? path.resolve(p) : null;
+  } catch { return null; }
+}
+
+function saveMinionsRootPointer(root) {
+  try { fs.writeFileSync(ROOT_POINTER_PATH, path.resolve(root)); } catch {}
+}
+
+function resolveMinionsHome(forInit = false, options = {}) {
+  const envHome = process.env.MINIONS_HOME ? path.resolve(process.env.MINIONS_HOME) : null;
+  if (envHome) return envHome;
+
+  if (forInit) return DEFAULT_MINIONS_HOME;
+
+  const packageRoot = options.packageRoot ? path.resolve(options.packageRoot) : PACKAGE_ROOT;
+  if (options.preferSourceCheckout && isSourceCheckoutRoot(packageRoot)) return packageRoot;
+
+  const pointerRoot = readMinionsRootPointer();
+  if (isInstalledRoot(pointerRoot)) return pointerRoot;
+
+  if (isInstalledRoot(DEFAULT_MINIONS_HOME)) return DEFAULT_MINIONS_HOME;
+
+  if (options.allowPackageRootFallback && isInstalledRoot(packageRoot)) return packageRoot;
+
+  return DEFAULT_MINIONS_HOME;
+}
+
+const MINIONS_DIR = process.env.MINIONS_TEST_DIR || resolveMinionsHome(false, {
+  allowPackageRootFallback: true,
+  preferSourceCheckout: true,
+});
 const ENGINE_DIR = path.join(MINIONS_DIR, 'engine');
 const CONTROL_PATH = path.join(ENGINE_DIR, 'control.json');
 const COOLDOWNS_PATH = path.join(ENGINE_DIR, 'cooldowns.json');
@@ -3055,6 +3104,8 @@ module.exports = {
   safeJson, safeJsonObj, safeJsonArr, safeJsonNoRestore,
   safeWrite,
   safeUnlink,
+  resolveMinionsHome,
+  saveMinionsRootPointer,
   neutralizeJsonBackupSidecar,
   PROMPT_CONTEXTS_DIR,
   dispatchPromptSidecarPath,

package/engine.js

@@ -3543,6 +3543,7 @@ function discoverCentralWorkItems(config) {
   const items = safeJson(centralPath) || [];
   const projects = getProjects(config);
   const dispatchProjects = getCentralDispatchProjects(projects);
+  const projectsByName = new Map(dispatchProjects.map(p => [p.name, p]));
   const newWork = [];
   // Collect mutations to apply atomically inside lock callback (avoids TOCTOU)
   const mutations = new Map(); // item.id → { field: value, ... }
@@ -3673,6 +3674,8 @@ function discoverCentralWorkItems(config) {
       const agentName = config.agents[agentId]?.name || agentId;
       const agentRole = config.agents[agentId]?.role || 'Agent';
       const firstProject = dispatchProjects[0];
+      const requestedProjectName = typeof item.project === 'string' ? item.project : item.project?.name;
+      const targetProject = (requestedProjectName && projectsByName.get(requestedProjectName)) || firstProject;
 
       // Branch mutex: skip if target branch is locked by an active dispatch
       const centralBranch = item.branch || item.featureBranch || `work/${item.id}`;
@@ -3683,7 +3686,7 @@ function discoverCentralWorkItems(config) {
       }
 
       const vars = {
-        ...buildBaseVars(agentId, config, firstProject),
+        ...buildBaseVars(agentId, config, targetProject),
         item_id: item.id,
         item_name: item.title || item.id,
         item_priority: item.priority || 'medium',
@@ -3694,11 +3697,11 @@ function discoverCentralWorkItems(config) {
         work_type: workType,
         additional_context: item.prompt ? `## Additional Context\n\n${item.prompt}` : '',
         scope_section: buildProjectContext(dispatchProjects, null, false, agentName, agentRole),
-        project_path: firstProject?.localPath || '',
+        project_path: targetProject?.localPath || '',
         branch_name: centralBranch,
       };
-      const centralWtPath = firstProject?.localPath
-        ? path.resolve(firstProject.localPath, config.engine?.worktreeRoot || '../worktrees', centralBranch)
+      const centralWtPath = targetProject?.localPath
+        ? path.resolve(targetProject.localPath, config.engine?.worktreeRoot || '../worktrees', centralBranch)
         : '';
       const cpResult = buildWorkItemDispatchVars(item, vars, config, {
         worktreePath: centralWtPath || undefined,
@@ -3749,7 +3752,7 @@ function discoverCentralWorkItems(config) {
         }
         vars.plan_summary = (item.title || item.planFile).substring(0, 80);
         vars.plan_file = item.planFile || '';
-        vars.project_name_lower = (firstProject?.name || 'project').toLowerCase();
+        vars.project_name_lower = (targetProject?.name || 'project').toLowerCase();
         // Default empty string so the {{existing_prd_json}} token always resolves —
         // playbook treats empty as "no existing PRD, fresh run". Without this default
         // the renderPlaybook pass logs an "unresolved template variables" warning
@@ -3804,7 +3807,7 @@ function discoverCentralWorkItems(config) {
         agentRole,
         task: item.title || item.description?.slice(0, 80) || item.id,
         prompt,
-        meta: { dispatchKey: key, source: 'central-work-item', item: { ...item, ...mutations.get(item.id) }, planFileName: item.planFile || mutations.get(item.id)?._planFileName || null, branch: item.branch || item.featureBranch || `work/${item.id}`, project: { name: firstProject.name, localPath: firstProject.localPath } }
+        meta: { dispatchKey: key, source: 'central-work-item', item: { ...item, ...mutations.get(item.id) }, planFileName: item.planFile || mutations.get(item.id)?._planFileName || null, branch: item.branch || item.featureBranch || `work/${item.id}`, project: { name: targetProject.name, localPath: targetProject.localPath } }
       });
 
       setCooldown(key);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.1773",
+  "version": "0.1.1775",
   "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/prompts/cc-system.md

@@ -159,8 +159,8 @@ Terms like schedules, pipelines, agents, inbox, work items, plans, PRD, PRs, dis
 ## API & CLI Index (auto-injected)
 Your state preamble (delivered alongside this prompt at session start) carries an auto-generated **API Index** rendered from `dashboard.js` `ROUTES` and a **CLI Index** rendered from `engine/cli.js` `CLI_COMMAND_DOCS`. Both are single-source-of-truth — adding a new HTTP endpoint or CLI command auto-surfaces it in your preamble; do not memorize the named action shorthand list above as exhaustive.
 
-For any `/api/...` endpoint that doesn't have a matching named action above, emit the generic fallback shape:
+For a `POST /api/...` endpoint marked `generic-fallback` in the API Index that doesn't have a matching named action above, emit the generic fallback shape:
 `{"type":"<short-descriptor>","endpoint":"/api/...","params":{...}}`
-The action runner accepts any local `/api/` path and POSTs `params` as JSON.
+The action runner POSTs `params` as JSON; do not use the fallback for read-only GET routes, DELETE routes, or endpoints not marked generic-fallback.
 
 For CLI commands (`minions <cmd>`), use Bash to invoke them when delegating would be heavier than just running the command.