@yemi33/minions 0.1.1753 → 0.1.1755

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.1.1755 (2026-05-06)
+
+### Fixes
+- keep queued strips pinned below progress UX and answers
+
+## 0.1.1754 (2026-05-06)
+
+### Fixes
+- canonical .minions home wins over nearest copied tree
+- recover partial responses instead of always returning "Failed"
+- surface adapter-supplied error messages instead of hardcoding Claude
+
+### Other
+- refactor(doc-chat): dedupe error envelope shape into _buildDocChatErrorEnvelope
+
 ## 0.1.1753 (2026-05-06)
 
 ### Other

package/bin/minions.js

@@ -191,12 +191,14 @@ function resolveMinionsHome(forInit = false) {
 
   if (forInit) return path.join(process.cwd(), '.minions');
 
-  const localRoot = findNearestLocalMinionsRoot(process.cwd());
-  if (localRoot) return localRoot;
-
   const pointerRoot = readRootPointer();
   if (isInstalledRoot(pointerRoot)) return pointerRoot;
 
+  if (isInstalledRoot(DEFAULT_MINIONS_HOME)) return DEFAULT_MINIONS_HOME;
+
+  const localRoot = findNearestLocalMinionsRoot(process.cwd());
+  if (localRoot) return localRoot;
+
   return DEFAULT_MINIONS_HOME;
 }
 
@@ -205,6 +207,7 @@ let force = rest.includes('--force');
 const skipScan = rest.includes('--skip-scan');
 const skipStart = rest.includes('--skip-start') || rest.includes('--no-start');
 const MINIONS_HOME = resolveMinionsHome(cmd === 'init');
+process.env.MINIONS_HOME = MINIONS_HOME;
 const POST_UPDATE_INIT_TIMEOUT_MS = 120000;
 const POST_UPDATE_RESTART_TIMEOUT_MS = 60000;
 
@@ -542,6 +545,7 @@ function delegate(script, args) {
   const child = spawn(process.execPath, [path.join(MINIONS_HOME, script), ...args], {
     stdio: 'inherit',
     cwd: MINIONS_HOME,
+    env: { ...process.env, MINIONS_HOME },
   });
   child.on('exit', code => process.exit(code || 0));
 }

package/dashboard/js/modal-qa.js

@@ -30,13 +30,23 @@ const QA_QUEUE_CAP = 10; // max queued messages
 const QA_STREAM_STALL_MS = 6 * 60 * 1000; // allow the full doc-chat timeout before treating heartbeat-only streams as stalled
 let _qaSessionKey = ''; // key for current conversation (title or filePath)
 
+// Insert html at the bottom of the thread but above any pending "Queued: ..."
+// strips, so queued messages always remain visually below the active progress
+// UX / answer / errors.
+function _qaInsertBeforeQueued(container, html) {
+  if (!container) return;
+  const firstQueued = container.querySelector && container.querySelector('.qa-queued-item');
+  if (firstQueued) firstQueued.insertAdjacentHTML('beforebegin', html);
+  else container.insertAdjacentHTML('beforeend', html);
+}
+
 function _renderQaUserMessage(thread, message, selection) {
   let qHtml = '<div class="modal-qa-q">' + escHtml(message);
   if (selection) {
     qHtml += '<span class="selection-ref">Re: "' + escHtml(selection.slice(0, 100)) + ((selection.length > 100) ? '...' : '') + '"</span>';
   }
   qHtml += '</div>';
-  thread.insertAdjacentHTML('beforeend', qHtml);
+  _qaInsertBeforeQueued(thread, qHtml);
   thread.scrollTop = thread.scrollHeight;
   _showThreadWrap();
 }
@@ -184,6 +194,31 @@ function _qaBuildLoadingHtml(loadingId, queueCount) {
     qaQueueBadge + '</div>';
 }
 
+// Render the raw error envelope (stderr + metadata) returned by ccDocCallStreaming
+// when the runtime fails. Always shown — collapsed by default — so the user can
+// inspect the actual CLI output instead of relying on the friendly summary.
+function _qaBuildRawErrorHtml(err) {
+  if (!err) return '';
+  const meta = [];
+  if (err.runtime) meta.push('runtime: ' + escHtml(String(err.runtime)));
+  if (err.errorClass) meta.push('class: ' + escHtml(String(err.errorClass)));
+  if (err.code !== null && err.code !== undefined) meta.push('exit: ' + escHtml(String(err.code)));
+  const metaLine = meta.length
+    ? '<div style="font-size:10px;color:var(--muted);margin-bottom:4px">' + meta.join(' · ') + '</div>'
+    : '';
+  const adapterMessage = err.errorMessage
+    ? '<div style="font-size:11px;color:var(--text);margin-bottom:6px;white-space:pre-wrap">' + escHtml(String(err.errorMessage)) + '</div>'
+    : '';
+  const stderrText = err.stderr ? String(err.stderr) : '';
+  const stderrBlock = stderrText
+    ? '<pre style="margin:0;padding:6px 8px;background:var(--surface2);border:1px solid var(--border);border-radius:4px;font-size:11px;white-space:pre-wrap;word-break:break-word;max-height:240px;overflow:auto">' + escHtml(stderrText) + '</pre>'
+    : '<div style="font-size:11px;color:var(--muted)">(no stderr captured)</div>';
+  return '<details class="modal-qa-raw-error" style="margin:6px 0 12px;padding:6px 8px;border:1px solid var(--red);border-radius:4px;background:var(--surface)">' +
+    '<summary style="cursor:pointer;font-size:11px;color:var(--red)">Raw error output</summary>' +
+    '<div style="margin-top:6px">' + metaLine + adapterMessage + stderrBlock + '</div>' +
+    '</details>';
+}
+
 function _qaBuildAssistantHtml(text, opts) {
   const body = opts?.isError ? escHtml(text) : renderMd(text);
   const style = opts?.isError
@@ -231,12 +266,14 @@ function _qaMutateThreadHtml(key, mutate) {
   mutate(tmp);
   const html = tmp.innerHTML;
   if (_qaIsActiveSession(key)) {
+    const wasCollapsed = _qaIsThreadCollapsed();
     const thread = _qaThreadEl();
     if (thread) {
       thread.innerHTML = html;
       thread.scrollTop = thread.scrollHeight;
     }
-    _showThreadWrap();
+    if (wasCollapsed) _setQaThreadCollapsed(true);
+    else _showThreadWrap();
   }
   return html;
 }
@@ -415,7 +452,7 @@ async function _processQaMessage(message, selection, opts) {
   const loadingId = 'chat-loading-' + Date.now();
   const loadingHtml = _qaBuildLoadingHtml(loadingId, runtime.queue.length);
   const startThreadHtml = _qaMutateThreadHtml(sessionKey, tmp => {
-    tmp.insertAdjacentHTML('beforeend', loadingHtml);
+    _qaInsertBeforeQueued(tmp, loadingHtml);
   });
   _qaPersistSession(sessionKey, {
     threadHtml: startThreadHtml,
@@ -544,17 +581,47 @@ async function _processQaMessage(message, selection, opts) {
         clearInterval(qaTimer);
         _clearQaStreamWatchdog();
         const qaElapsed = Math.round((Date.now() - qaStartTime) / 1000);
-        const borderColor = evt.edited ? 'var(--green)' : 'var(--blue)';
+        // Pick the border that best reflects what actually happened:
+        //  - partial recovery (work landed despite a non-zero exit) \u2192 orange
+        //    (checked first because partial responses now also carry an error
+        //    envelope so the raw stderr can be surfaced)
+        //  - hard error (no recoverable answer) \u2192 red
+        //  - successful edit \u2192 green
+        //  - normal answer \u2192 blue
+        const borderColor = evt.partial
+          ? 'var(--orange)'
+          : evt.error
+            ? 'var(--red)'
+            : evt.edited ? 'var(--green)' : 'var(--blue)';
         const suffix = evt.edited ? '\n\n\u2713 Document saved.' : '';
-        const answerHtml = _qaBuildAssistantHtml((evt.text || '') + suffix, { borderColor, elapsed: qaElapsed });
+        // Fall back to the live-streamed text when the backend produced no final
+        // answer \u2014 covers the "stream had visible chunks then returned empty" case.
+        const finalText = (evt.text && evt.text.trim()) ? evt.text : (streamedText || '');
+        let bodyText = finalText + suffix;
+        if (evt.partial && evt.warning) {
+          bodyText += '\n\n_' + evt.warning + '_';
+        }
+        // On hard failures, surface tool side-effects so the user knows what
+        // landed before the runtime gave up \u2014 silent destruction was the worst
+        // class of "Failed to process request" UX.
+        if (evt.error && Array.isArray(evt.toolUses) && evt.toolUses.length > 0) {
+          const names = evt.toolUses.slice(0, 8).map(t => t.name).join(', ');
+          const more = evt.toolUses.length > 8 ? '\u2026' : '';
+          bodyText += '\n\n_Tools that ran before the failure: ' + names + more + ' \u2014 files or state may have been modified._';
+        }
+        const answerHtml = _qaBuildAssistantHtml(bodyText, { borderColor, elapsed: qaElapsed });
+        // On any runtime failure, surface the raw error so users can debug it
+        // directly instead of guessing what the friendly summary was hiding.
+        const rawErrorHtml = evt.error ? _qaBuildRawErrorHtml(evt.error) : '';
         let updatedThreadHtml = _qaMutateThreadHtml(sessionKey, tmp => {
           const loadingEl = tmp.querySelector('#' + loadingId);
           if (loadingEl) loadingEl.remove();
-          tmp.insertAdjacentHTML('beforeend', answerHtml);
+          _qaInsertBeforeQueued(tmp, answerHtml);
+          if (rawErrorHtml) _qaInsertBeforeQueued(tmp, rawErrorHtml);
         });
 
         runtime.history.push({ role: 'user', text: message });
-        runtime.history.push({ role: 'assistant', text: evt.text || '' });
+        runtime.history.push({ role: 'assistant', text: finalText || '' });
         if (_qaIsActiveSession(sessionKey)) _qaHistory = runtime.history.slice();
 
         _qaNotifySidebar(capturedFilePath);
@@ -564,7 +631,7 @@ async function _processQaMessage(message, selection, opts) {
         } else if (evt.actionParseError) {
           const warning = '<div class="modal-qa-a" style="color:var(--red)">Actions block emitted but JSON could not be parsed — no actions were executed. Resend or rephrase. (' + escHtml(String(evt.actionParseError).slice(0, 200)) + ')</div>';
           updatedThreadHtml = _qaMutateThreadHtml(sessionKey, tmp => {
-            tmp.insertAdjacentHTML('beforeend', warning);
+            _qaInsertBeforeQueued(tmp, warning);
           });
         }
 
@@ -641,7 +708,7 @@ async function _processQaMessage(message, selection, opts) {
     const updatedThreadHtml = _qaMutateThreadHtml(sessionKey, tmp => {
       const loadingEl = tmp.querySelector('#' + loadingId);
       if (loadingEl) loadingEl.remove();
-      tmp.insertAdjacentHTML('beforeend', messageHtml);
+      _qaInsertBeforeQueued(tmp, messageHtml);
     });
     _qaPersistSession(sessionKey, {
       threadHtml: updatedThreadHtml,
@@ -676,7 +743,7 @@ async function _processQaMessage(message, selection, opts) {
     const nextThreadHtml = _qaMutateThreadHtml(sessionKey, tmp => {
       const queuedEl = tmp.querySelector('.qa-queued-item');
       if (queuedEl) queuedEl.remove();
-      tmp.insertAdjacentHTML('beforeend', _qaBuildUserMessageHtml(next.message, next.selection));
+      _qaInsertBeforeQueued(tmp, _qaBuildUserMessageHtml(next.message, next.selection));
     });
     _qaPersistSession(sessionKey, {
       threadHtml: nextThreadHtml,
@@ -710,18 +777,26 @@ function qaAbort() {
 
 function toggleDocChat() {
   var wrap = document.getElementById('modal-qa-thread-wrap');
-  var expandBar = document.getElementById('qa-expand-bar');
   if (!wrap) return;
   var visible = wrap.style.display !== 'none';
-  wrap.style.display = visible ? 'none' : '';
-  if (expandBar) expandBar.style.display = visible ? '' : 'none';
+  _setQaThreadCollapsed(visible);
 }
 
-function _showThreadWrap() {
+function _qaIsThreadCollapsed() {
   var wrap = document.getElementById('modal-qa-thread-wrap');
   var expandBar = document.getElementById('qa-expand-bar');
-  if (wrap) wrap.style.display = '';
-  if (expandBar) expandBar.style.display = 'none';
+  return !!(wrap && wrap.style.display === 'none' && expandBar && expandBar.style.display !== 'none');
+}
+
+function _setQaThreadCollapsed(collapsed) {
+  var wrap = document.getElementById('modal-qa-thread-wrap');
+  var expandBar = document.getElementById('qa-expand-bar');
+  if (wrap) wrap.style.display = collapsed ? 'none' : '';
+  if (expandBar) expandBar.style.display = collapsed ? '' : 'none';
+}
+
+function _showThreadWrap() {
+  _setQaThreadCollapsed(false);
 }
 
 // ── Drag-to-resize doc chat thread ──────────────────────────────────────────

package/dashboard.js

@@ -2538,15 +2538,36 @@ function _formatDocChatContext({ document, title, filePath, selection, canEdit,
 
 // Map errorClass codes from the runtime adapter to actionable user-facing messages.
 // sessionPreserved=true means ccCall preserved the session — user can retry immediately.
-function _docChatErrorMessage(errorClass, sessionPreserved = false) {
-  if (errorClass === 'auth-failure') return 'Claude authentication failed — run `claude auth` or check your API key, then try again.';
-  if (errorClass === 'context-limit') return 'Session context is too long. Click "Clear" to start a fresh conversation.';
-  if (errorClass === 'budget-exceeded') return 'API budget exceeded — check your Claude account spending limit.';
-  if (errorClass === 'crash') return 'Claude runtime crashed unexpectedly. Try again.';
-  if (sessionPreserved) return 'Temporary connection issue — your conversation is intact, send your message again.';
+// 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.
+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 (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.';
 }
 
+// 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.';
+  return 'Note: the agent exited unexpectedly. A complete response was recovered — verify any saved files or dispatched actions.';
+}
+
 // 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.
@@ -2580,20 +2601,54 @@ async function _retryDocChatAfterResumeFailure({ result, initialPass, freshSessi
 // Build the {error} envelope returned to the dashboard when doc-chat ultimately
 // fails. Surfaces an actionable user-facing message (via _docChatErrorMessage)
 // plus the runtime's real stderr / exit code / errorClass so the UI can render
-// the cause and so future failures are debuggable from logs.
+// the cause and so future failures are debuggable from logs. toolUses lets the
+// client surface what side-effects already landed despite the failure.
+// Shape the per-failure debug envelope (raw stderr + classification metadata)
+// shared by hard failures and partial recoveries — keeps the wire shape in lockstep.
+function _buildDocChatErrorEnvelope(result) {
+  return {
+    code: result.code ?? null,
+    stderr: (result.stderr || '').slice(-2048),
+    errorClass: result.errorClass || null,
+    errorMessage: result.errorMessage || null,
+    runtime: result.runtime || null,
+  };
+}
+
 function _docChatFailureResponse(label, filePath, result, sessionPreserved = false) {
-  const stderrTail = (result.stderr || '').slice(-2048);
-  console.error(`[${label}] Failed: code=${result.code}, errorClass=${result.errorClass || 'null'}, sessionPreserved=${sessionPreserved}, empty=${!result.text}, filePath=${filePath}, stderr=${stderrTail.slice(0, 200)}`);
+  const envelope = _buildDocChatErrorEnvelope(result);
+  const toolUses = Array.isArray(result.toolUses) ? result.toolUses : [];
+  console.error(`[${label}] Failed: code=${result.code}, errorClass=${result.errorClass || 'null'}, sessionPreserved=${sessionPreserved}, empty=${!result.text}, tools=${toolUses.length}, filePath=${filePath}, stderr=${envelope.stderr.slice(0, 200)}`);
   return {
-    answer: _docChatErrorMessage(result.errorClass, sessionPreserved),
+    answer: _docChatErrorMessage(result.errorClass, sessionPreserved, toolUses, result.errorMessage || null),
     content: null,
     actions: [],
-    error: {
-      code: result.code ?? null,
-      stderr: stderrTail,
-      errorClass: result.errorClass || null,
-      runtime: result.runtime || null,
-    },
+    toolUses,
+    error: envelope,
+  };
+}
+
+// Try to salvage useful work from a non-zero / empty-text result before falling
+// through to the failure response. Even when the runtime exits non-zero, the
+// model often produced a complete answer / action JSON / document edit in
+// result.text — discarding it just to show "Failed to process request" wastes
+// successful work and confuses users who watched tools run during streaming.
+// Returns null when there's nothing parseable; caller falls through to failure.
+function _recoverPartialDocChatResponse(result, sessionKey) {
+  if (!result || !result.text || !result.text.trim()) return null;
+  const parsed = _parseDocChatResultText(result.text);
+  const hasActions = Array.isArray(parsed.actions) && parsed.actions.length > 0;
+  const hasAnswer = typeof parsed.answer === 'string' && !!parsed.answer.trim();
+  const hasContent = typeof parsed.content === 'string' && !!parsed.content.trim();
+  if (!hasAnswer && !hasContent && !hasActions) return null;
+  return {
+    ...parsed,
+    partial: true,
+    warning: _docChatPartialWarning(result.errorClass),
+    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.
+    error: _buildDocChatErrorEnvelope(result),
   };
 }
 
@@ -2653,6 +2708,9 @@ async function ccDocCall({ message, document, title, filePath, selection, canEdi
   }
 
   if (result.code !== 0 || !result.text) {
+    // Try to salvage a parseable answer / action / document edit before failing.
+    const recovered = _recoverPartialDocChatResponse(result, sessionKey);
+    if (recovered) return recovered;
     const sessionPreserved = !!(resolveSession('doc', sessionKey)?.sessionId);
     return _docChatFailureResponse('doc-chat', filePath, result, sessionPreserved);
   }
@@ -2709,6 +2767,8 @@ async function ccDocCallStreaming({ message, document, title, filePath, selectio
   }
 
   if (result.code !== 0 || !result.text) {
+    const recovered = _recoverPartialDocChatResponse(result, sessionKey);
+    if (recovered) return recovered;
     const sessionPreserved = !!(resolveSession('doc', sessionKey)?.sessionId);
     return _docChatFailureResponse('doc-chat-stream', filePath, result, sessionPreserved);
   }
@@ -4822,7 +4882,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         }
       }
 
-      const { answer, content, actions, actionParseError, error: ccError } = await ccDocCall({
+      const { answer, content, actions, actionParseError, partial, warning, toolUses, error: ccError } = await ccDocCall({
         message: body.message, document: currentContent, title: body.title,
         filePath: body.filePath, selection: body.selection, canEdit, isJson,
         model: body.model || undefined,
@@ -4837,6 +4897,8 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         ...(actionResults ? { actionResults } : {}),
         ...(actionParseError ? { actionParseError } : {}),
         ...(ccError ? { error: ccError } : {}),
+        ...(partial ? { partial: true, warning } : {}),
+        ...(Array.isArray(toolUses) && toolUses.length ? { toolUses } : {}),
         ...extra,
       });
 
@@ -4938,7 +5000,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
 
       try {
 
-        const { answer, content, actions, actionParseError, error: ccError } = await ccDocCallStreaming({
+        const { answer, content, actions, actionParseError, partial, warning, toolUses, error: ccError } = await ccDocCallStreaming({
           message: body.message, document: currentContent, title: body.title,
           filePath: body.filePath, selection: body.selection, canEdit, isJson,
           model: body.model || undefined,
@@ -4956,6 +5018,8 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           ...(actionResults ? { actionResults } : {}),
           ...(actionParseError ? { actionParseError } : {}),
           ...(ccError ? { error: ccError } : {}),
+          ...(partial ? { partial: true, warning } : {}),
+          ...(Array.isArray(toolUses) && toolUses.length ? { toolUses } : {}),
           ...extra,
         });
 
@@ -7400,6 +7464,10 @@ module.exports = {
   parsePinnedEntries,
   _parseDocChatResultText,
   _formatDocChatContext,
+  _docChatErrorMessage,
+  _docChatPartialWarning,
+  _docChatFailureResponse,
+  _recoverPartialDocChatResponse,
   _linkPullRequestForTracking: linkPullRequestForTracking,
   _resolveSkillReadPath,
   DOC_CHAT_DOCUMENT_DELIMITER,

package/engine/copilot-models.json

@@ -1,5 +1,5 @@
 {
   "runtime": "copilot",
   "models": null,
-  "cachedAt": "2026-05-06T21:07:27.809Z"
+  "cachedAt": "2026-05-06T22:01:51.910Z"
 }

package/engine/llm.js

@@ -232,6 +232,7 @@ function _missingRuntimeResult(runtimeName, runtime, reason) {
     toolUses: [],
     runtime: runtime?.name || runtimeName || null,
     errorClass: shared.FAILURE_CLASS.CONFIG_ERROR,
+    errorMessage: message,
     missingRuntime: true,
   };
 }
@@ -689,6 +690,7 @@ function callLLM(promptText, sysPromptText, opts = {}) {
         toolUses: parsed.toolUses,
         runtime: runtime.name,
         errorClass: errInfo.code,
+        errorMessage: errInfo.message || null,
       });
     };
 
@@ -711,7 +713,7 @@ function callLLM(promptText, sysPromptText, opts = {}) {
       resolve({
         text: '', usage: null, sessionId: null, code: 1,
         stderr: err.message, raw: '', toolUses: [],
-        runtime: runtime.name, errorClass: null,
+        runtime: runtime.name, errorClass: null, errorMessage: null,
       });
     });
   });
@@ -814,6 +816,7 @@ function callLLMStreaming(promptText, sysPromptText, opts = {}) {
         toolUses: parsed.toolUses,
         runtime: runtime.name,
         errorClass: errInfo.code,
+        errorMessage: errInfo.message || null,
       });
     };
 
@@ -836,7 +839,7 @@ function callLLMStreaming(promptText, sysPromptText, opts = {}) {
       resolve({
         text: '', usage: null, sessionId: null, code: 1,
         stderr: err.message, raw: '', toolUses: [],
-        runtime: runtime.name, errorClass: null,
+        runtime: runtime.name, errorClass: null, errorMessage: null,
       });
     });
   });

package/engine/runtimes/claude.js

@@ -493,16 +493,16 @@ function parseError(rawOutput) {
   const hasExplicitAuthFailure = /invalid api key|api key.*invalid|authentication.*fail|\bunauthorized\b|please.*log.*in|claude\.ai\/login/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: 'Claude authentication failed', code: 'auth-failure', retriable: false };
+    return { message: 'Claude authentication failed — run `claude auth` or check your API key, then try again.', code: 'auth-failure', retriable: false };
   }
   if (/prompt is too long|context window|context.*length.*exceeded|token limit|conversation.*too long/i.test(text)) {
     return { message: 'Claude context window exhausted', code: 'context-limit', retriable: false };
   }
   if (/budget.*exceed|max.budget.usd.*reach|cost.*limit.*exceed/i.test(lower)) {
-    return { message: 'Claude budget cap exceeded', code: 'budget-exceeded', retriable: false };
+    return { message: 'Claude budget cap exceeded — check your Claude account spending limit.', code: 'budget-exceeded', retriable: false };
   }
   if (/internal error|panic|segmentation fault|claude.*crashed|fatal: claude/i.test(lower)) {
-    return { message: 'Claude CLI crashed', code: 'crash', retriable: true };
+    return { message: 'Claude CLI crashed unexpectedly. Try again.', code: 'crash', retriable: true };
   }
   return { message: '', code: null, retriable: true };
 }

package/engine/runtimes/copilot.js

@@ -576,10 +576,10 @@ function parseError(rawOutput) {
     return { message: 'Copilot rejected the requested model', code: 'unknown-model', retriable: false };
   }
   if (/budget.*exceed|premium.*limit.*reach|quota.*exceed/i.test(lower)) {
-    return { message: 'Copilot premium-request budget exceeded', code: 'budget-exceeded', retriable: false };
+    return { message: 'Copilot premium-request budget exceeded — check your GitHub Copilot quota.', code: 'budget-exceeded', retriable: false };
   }
   if (/internal error|panic|uncaught|copilot.*crashed|fatal: copilot/i.test(lower)) {
-    return { message: 'Copilot CLI crashed', code: 'crash', retriable: true };
+    return { message: 'Copilot CLI crashed unexpectedly. Try again.', code: 'crash', retriable: true };
   }
   return { message: '', code: null, retriable: true };
 }

package/engine/shared.js

@@ -7,7 +7,7 @@ const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
 
-const MINIONS_DIR = process.env.MINIONS_TEST_DIR || path.resolve(__dirname, '..');
+const MINIONS_DIR = process.env.MINIONS_TEST_DIR || (process.env.MINIONS_HOME ? path.resolve(process.env.MINIONS_HOME) : path.resolve(__dirname, '..'));
 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');

package/minions.js

@@ -19,7 +19,7 @@ const { execSync } = require('child_process');
 const { ENGINE_DEFAULTS, DEFAULT_AGENTS, DEFAULT_CLAUDE } = require('./engine/shared');
 const projectDiscovery = require('./engine/project-discovery');
 
-const MINIONS_HOME = __dirname;
+const MINIONS_HOME = process.env.MINIONS_HOME ? path.resolve(process.env.MINIONS_HOME) : __dirname;
 const CONFIG_PATH = path.join(MINIONS_HOME, 'config.json');
 
 function loadConfig() {

package/package.json

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