@yemi33/minions 0.1.1752 → 0.1.1754

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 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
+- refactor(doc-chat): drop brittle regex action gate in favour of sysprompt
+
 ## 0.1.1752 (2026-05-06)
 
 ### Features

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

@@ -184,6 +184,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 +256,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;
 }
@@ -544,17 +571,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);
+          if (rawErrorHtml) tmp.insertAdjacentHTML('beforeend', 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);
@@ -710,18 +767,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

@@ -1510,34 +1510,6 @@ function stripCCActionSyntax(text) {
   return displayText.replace(/`{3,}\s*action\s*\r?\n[\s\S]*?`{3,}\n?/g, '').trim();
 }
 
-function _messageRequestsOrchestration(message) {
-  const text = String(message || '').toLowerCase();
-  if (!text.trim()) return false;
-
-  const docTarget = '\\b(document|doc|text|selection|selected text|selected paragraph|selected section|paragraph|section|wording|copy|markdown|plan)\\b';
-  const docEditVerb = '\\b(edit|rewrite|revise|update|change|rephrase|polish|format|shorten|expand|summarize|correct|add|write)\\b';
-  const explicitDocEdit = new RegExp(`${docEditVerb}[\\s\\S]{0,120}${docTarget}|${docTarget}[\\s\\S]{0,120}${docEditVerb}`).test(text)
-    || /\bfix\b[\s\S]{0,80}\b(typo|typos|grammar|spelling|wording|copy|markdown)\b[\s\S]{0,80}\b(document|doc|text|selection|paragraph|section|plan)\b/.test(text);
-  const actionTerm = '\\b(dispatch|delegate|assign|orchestrate|hand off|handoff|work item|ticket|agent|minions|watch|monitor|schedule|pipeline|meeting)\\b';
-  const untrustedActionMention = new RegExp(
-    `${docTarget}[\\s\\S]{0,120}\\b(says|contains|mentions|includes|reads|states|instructs|asks|tells|literal|literally)\\b[\\s\\S]{0,160}${actionTerm}`
-  ).test(text)
-    || new RegExp(`\\b(summarize|explain|quote|describe|analyze|extract)\\b[\\s\\S]{0,160}${docTarget}[\\s\\S]{0,160}${actionTerm}`).test(text);
-  const explicitFollowupAction = /\b(and|then|also)\b[\s\S]{0,80}\b(dispatch|delegate|assign|orchestrate|hand off|handoff|work item|ticket|agent|minions|watch|monitor|schedule|pipeline|meeting)\b/.test(text);
-  if (untrustedActionMention && !explicitFollowupAction) return false;
-
-  const dispatchAction = /\b(dispatch|delegate|assign|orchestrate|hand off|handoff)\b[\s\S]{0,120}\b(agent|dallas|ripley|lambert|rebecca|ralph|work item|task|fix|implement|explore|investigate|audit|review|test|verify|build)\b/.test(text);
-  const workItemAction = /\b(create|open|file|add)\b[\s\S]{0,80}\b(work item|task|ticket)\b/.test(text);
-  const stateAction = /\b(create|add|set up|start)\b[\s\S]{0,80}\b(watch|monitor|schedule|pipeline|meeting)\b/.test(text)
-    || /\b(watch|monitor|keep an eye on)\b[\s\S]{0,100}\b(pr|pull request|work item|build)\b/.test(text)
-    || /\b(cancel|retry|reopen|archive|pause|approve|reject|execute|resume|steer)\b[\s\S]{0,100}\b(plan|work item|agent|pr|pull request|schedule|pipeline)\b/.test(text);
-  const agentEngineeringAction = /\b(minions|agent|dallas|ripley|lambert|rebecca|ralph)\b[\s\S]{0,120}\b(fix|debug|repair|investigate|audit|review|test|verify|build|refactor|implement)\b/.test(text)
-    || /\b(fix|debug|repair|investigate|audit|review|test|verify|build|refactor|implement)\b[\s\S]{0,120}\b(minions|agent|dallas|ripley|lambert|rebecca|ralph)\b/.test(text);
-  const explicitActionIntent = dispatchAction || workItemAction || stateAction || agentEngineeringAction;
-  if (explicitDocEdit && !explicitActionIntent) return false;
-  return explicitActionIntent;
-}
-
 function _escapeRegExp(str) {
   return String(str).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
@@ -2517,13 +2489,11 @@ function contentFingerprint(str) {
   return str.length + ':' + str.charCodeAt(0) + ':' + str.charCodeAt(mid) + ':' + str.charCodeAt(str.length - 1);
 }
 
-function _parseDocChatResultText(text, { allowActions = false } = {}) {
+function _parseDocChatResultText(text) {
   const docDelimiter = findDocChatDocumentDelimiter(text);
   if (docDelimiter) {
     const answerPart = text.slice(0, docDelimiter.index).trim();
-    const parsedActions = allowActions
-      ? parseCCActions(answerPart)
-      : { text: stripCCActionSyntax(answerPart), actions: [] };
+    const parsedActions = parseCCActions(answerPart);
     const { text: answer, actions } = parsedActions;
     let content = text.slice(docDelimiter.index + docDelimiter.length).trim();
     content = content.replace(/^```\w*\n?/, '').replace(/\n?```$/, '').trim();
@@ -2534,9 +2504,7 @@ function _parseDocChatResultText(text, { allowActions = false } = {}) {
       ...(parsedActions._actionParseError ? { actionParseError: parsedActions._actionParseError } : {}),
     };
   }
-  const parsedActions = allowActions
-    ? parseCCActions(text)
-    : { text: stripCCActionSyntax(text), actions: [] };
+  const parsedActions = parseCCActions(text);
   const { text: stripped, actions } = parsedActions;
   return {
     answer: stripped,
@@ -2546,8 +2514,8 @@ function _parseDocChatResultText(text, { allowActions = false } = {}) {
   };
 }
 
-function _docChatDisplayText(text, opts) {
-  return _parseDocChatResultText(text, opts).answer;
+function _docChatDisplayText(text) {
+  return _parseDocChatResultText(text).answer;
 }
 
 function _formatDocChatContext({ document, title, filePath, selection, canEdit, isJson, docUnchanged }) {
@@ -2570,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.
@@ -2612,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),
   };
 }
 
@@ -2643,8 +2666,6 @@ async function ccDocCall({ message, document, title, filePath, selection, canEdi
     // Skip persistDocSessions() here — the post-call cleanup below handles persistence.
   }
 
-  const allowActions = _messageRequestsOrchestration(message);
-
   const runOnce = async () => {
     const { extraContext } = _buildDocChatPass({
       docSlice, title, filePath, selection, canEdit, isJson, sessionKey, freshSession,
@@ -2687,11 +2708,14 @@ 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);
   }
 
-  return _parseDocChatResultText(result.text, { allowActions });
+  return _parseDocChatResultText(result.text);
 }
 
 async function ccDocCallStreaming({ message, document, title, filePath, selection, canEdit, isJson, model, freshSession, onAbortReady, onChunk, onToolUse, onRetry }) {
@@ -2702,8 +2726,6 @@ async function ccDocCallStreaming({ message, document, title, filePath, selectio
     docSessions.delete(sessionKey);
   }
 
-  const allowActions = _messageRequestsOrchestration(message);
-
   const runOnce = async () => {
     const { extraContext } = _buildDocChatPass({
       docSlice, title, filePath, selection, canEdit, isJson, sessionKey, freshSession,
@@ -2720,7 +2742,7 @@ async function ccDocCallStreaming({ message, document, title, filePath, selectio
       systemPrompt: DOC_CHAT_SYSTEM_PROMPT,
       ...(model ? { model } : {}),
       onAbortReady,
-      onChunk: (text) => { if (onChunk) onChunk(_docChatDisplayText(text, { allowActions })); },
+      onChunk: (text) => { if (onChunk) onChunk(_docChatDisplayText(text)); },
       onToolUse,
       onRetry,
     });
@@ -2745,11 +2767,13 @@ 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);
   }
 
-  return _parseDocChatResultText(result.text, { allowActions });
+  return _parseDocChatResultText(result.text);
 }
 
 // -- POST helpers --
@@ -4858,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,
@@ -4873,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,
       });
 
@@ -4974,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,
@@ -4992,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,
         });
 
@@ -7435,8 +7463,11 @@ module.exports = {
   _meetingParticipantsFromAction: meetingParticipantsFromAction,
   parsePinnedEntries,
   _parseDocChatResultText,
-  _messageRequestsOrchestration,
   _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-06T20:30:44.726Z"
+  "cachedAt": "2026-05-06T21:43:07.445Z"
 }

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.1752",
+  "version": "0.1.1754",
   "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"