@yemi33/minions 0.1.1579 → 0.1.1581

package/CHANGELOG.md

@@ -1,10 +1,14 @@
 # Changelog
 
-## 0.1.1579 (2026-04-28)
+## 0.1.1581 (2026-04-28)
 
 ### Features
+-  stream doc chat progress
 - hash-dedup, compress+normalize pass, dynamic stale-guard, rich result
 
+### Fixes
+- prohibit grep-filtered Monitor for long builds (#1794) (#1797)
+
 ### Other
 - Keep CC streams reconnectable
 

package/dashboard/js/modal-qa.js

@@ -191,9 +191,36 @@ function _qaBuildAssistantHtml(text, opts) {
   const pad = opts?.isError ? '' : 'padding-right:24px;';
   return '<div class="modal-qa-a" style="' + style + '">' +
     (opts?.isError ? '' : llmCopyBtn()) +
-    body +
-    '<div style="font-size:9px;color:var(--muted);margin-top:4px;text-align:right;' + pad + '">' + opts.elapsed + 's</div>' +
+     body +
+     '<div style="font-size:9px;color:var(--muted);margin-top:4px;text-align:right;' + pad + '">' + opts.elapsed + 's</div>' +
+     '</div>';
+}
+
+function _qaBuildLiveProgressHtml(loadingId, label, elapsedSeconds, streamedText, toolsUsed, queueCount) {
+  const qaQueueBadge = queueCount > 0 ? ' <span style="font-size:9px;color:var(--muted);background:var(--surface);padding:1px 5px;border-radius:8px;border:1px solid var(--border)">+' + queueCount + ' queued</span>' : '';
+  let html = '';
+  if (toolsUsed && toolsUsed.length > 0) {
+    html += '<div style="margin-bottom:6px">';
+    toolsUsed.forEach(function(t) {
+      const name = typeof t === 'string' ? t : t.name;
+      const input = typeof t === 'string' ? {} : (t.input || {});
+      html += '<div style="color:var(--muted);font-size:10px;font-family:monospace"><span style="flex-shrink:0">&#9679;</span> ' + formatToolSummary(name, input) + '</div>';
+    });
+    html += '</div>';
+  }
+  if (streamedText) html += '<div style="margin-bottom:6px">' + renderMd(streamedText) + '</div>';
+  html += '<div style="display:flex;flex-direction:column;align-items:flex-start;gap:6px">' +
+    '<div style="display:flex;align-items:center;gap:6px;flex-wrap:wrap">' +
+      '<span class="dot-pulse"><span></span><span></span><span></span></span> ' +
+      '<span id="' + loadingId + '-text">' + escHtml(label) + '</span>' +
+    '</div>' +
+    '<div style="display:flex;align-items:center;gap:6px;flex-wrap:wrap">' +
+      '<span id="' + loadingId + '-time" style="font-size:10px;color:var(--muted)">' + elapsedSeconds + 's</span>' +
+      '<button onclick="qaAbort()" style="font-size:9px;padding:2px 8px;background:var(--surface2);border:1px solid var(--border);border-radius:4px;color:var(--red);cursor:pointer">Stop</button>' +
+      qaQueueBadge +
+    '</div>' +
     '</div>';
+  return html;
 }
 
 function _qaMutateThreadHtml(key, mutate) {
@@ -401,23 +428,49 @@ async function _processQaMessage(message, selection, opts) {
   const qaPhases = isPlanEdit
     ? [[0,'Reading plan...'],[3000,'Analyzing structure...'],[8000,'Researching context...'],[15000,'Drafting revisions...'],[30000,'Writing updated plan...'],[60000,'Still working (large document)...'],[120000,'Deep edit in progress...'],[300000,'Almost there...']]
     : [[0,'Thinking...'],[3000,'Reading document...'],[8000,'Analyzing...'],[20000,'Still working...'],[60000,'Taking a while...']];
-  const qaTimer = setInterval(() => {
-    const elapsed = Date.now() - qaStartTime;
-    const timeEl = _qaIsActiveSession(sessionKey) ? document.getElementById(loadingId + '-time') : null;
-    const textEl = _qaIsActiveSession(sessionKey) ? document.getElementById(loadingId + '-text') : null;
-    if (timeEl) timeEl.textContent = Math.floor(elapsed / 1000) + 's';
-    if (textEl) {
-      for (let i = qaPhases.length - 1; i >= 0; i--) {
-        if (elapsed >= qaPhases[i][0]) {
-          textEl.textContent = qaPhases[i][1];
-          break;
-        }
+  let streamedText = '';
+  let toolsUsed = [];
+  function _qaProgressLabel(elapsed) {
+    let label = qaPhases[0][1];
+    for (let i = qaPhases.length - 1; i >= 0; i--) {
+      if (elapsed >= qaPhases[i][0]) {
+        label = qaPhases[i][1];
+        break;
       }
     }
+    return label;
+  }
+  function _qaRenderProgress(persist) {
+    const elapsed = Date.now() - qaStartTime;
+    const updatedThreadHtml = _qaMutateThreadHtml(sessionKey, tmp => {
+      const loadingEl = tmp.querySelector('#' + loadingId);
+      if (!loadingEl) return;
+      loadingEl.innerHTML = _qaBuildLiveProgressHtml(
+        loadingId,
+        _qaProgressLabel(elapsed),
+        Math.floor(elapsed / 1000),
+        streamedText,
+        toolsUsed,
+        runtime.queue.length
+      );
+    });
+    if (persist) {
+      _qaPersistSession(sessionKey, {
+        threadHtml: updatedThreadHtml,
+        docContext: capturedDocContext,
+        filePath: capturedFilePath,
+        history: runtime.history,
+        queue: runtime.queue,
+      });
+    }
+  }
+  const qaTimer = setInterval(() => {
+    _qaRenderProgress(false);
   }, 500);
+  _qaRenderProgress(false);
 
   try {
-    const res = await fetch('/api/doc-chat', {
+    const res = await fetch('/api/doc-chat/stream', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       signal: abortController.signal,
@@ -431,76 +484,118 @@ async function _processQaMessage(message, selection, opts) {
         contentHash: capturedDocContext.content ? capturedDocContext.content.length + ':' + capturedDocContext.content.charCodeAt(0) + ':' + capturedDocContext.content.charCodeAt(capturedDocContext.content.length - 1) : undefined,
       }),
     });
-    const data = await res.json();
-    clearInterval(qaTimer);
-    const qaElapsed = Math.round((Date.now() - qaStartTime) / 1000);
     let sessionDocContext = { ...capturedDocContext };
+    if (!res.ok) {
+      const errText = await res.text();
+      let errMsg = errText || 'Failed';
+      try {
+        const parsed = JSON.parse(errText);
+        errMsg = parsed.error || errMsg;
+      } catch { /* text/plain fallback */ }
+      throw new Error(errMsg);
+    }
 
-    if (data.ok) {
-      const borderColor = data.edited ? 'var(--green)' : 'var(--blue)';
-      const suffix = data.edited ? '\n\n\u2713 Document saved.' : '';
-      const answerHtml = _qaBuildAssistantHtml(data.answer + suffix, { borderColor, elapsed: qaElapsed });
-      const updatedThreadHtml = _qaMutateThreadHtml(sessionKey, tmp => {
-        const loadingEl = tmp.querySelector('#' + loadingId);
-        if (loadingEl) loadingEl.remove();
-        tmp.insertAdjacentHTML('beforeend', answerHtml);
-      });
-
-      runtime.history.push({ role: 'user', text: message });
-      runtime.history.push({ role: 'assistant', text: data.answer });
-      if (_qaIsActiveSession(sessionKey)) _qaHistory = runtime.history.slice();
-
-      _qaNotifySidebar(capturedFilePath);
-      if (data.actions && data.actions.length > 0) {
-        for (const action of data.actions) await ccExecuteAction(action);
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buf = '';
+    let terminalEventSeen = false;
+
+    async function _qaHandleStreamEvent(evt) {
+      if (!evt || !evt.type) return;
+      if (evt.type === 'heartbeat') return;
+      if (evt.type === 'chunk') {
+        streamedText = evt.text || '';
+        _qaRenderProgress(true);
+        return;
+      }
+      if (evt.type === 'tool') {
+        toolsUsed.push({ name: evt.name, input: evt.input || {} });
+        _qaRenderProgress(true);
+        return;
       }
+      if (evt.type === 'done') {
+        terminalEventSeen = true;
+        clearInterval(qaTimer);
+        const qaElapsed = Math.round((Date.now() - qaStartTime) / 1000);
+        const borderColor = evt.edited ? 'var(--green)' : 'var(--blue)';
+        const suffix = evt.edited ? '\n\n\u2713 Document saved.' : '';
+        const answerHtml = _qaBuildAssistantHtml((evt.text || '') + suffix, { borderColor, elapsed: qaElapsed });
+        const updatedThreadHtml = _qaMutateThreadHtml(sessionKey, tmp => {
+          const loadingEl = tmp.querySelector('#' + loadingId);
+          if (loadingEl) loadingEl.remove();
+          tmp.insertAdjacentHTML('beforeend', answerHtml);
+        });
+
+        runtime.history.push({ role: 'user', text: message });
+        runtime.history.push({ role: 'assistant', text: evt.text || '' });
+        if (_qaIsActiveSession(sessionKey)) _qaHistory = runtime.history.slice();
+
+        _qaNotifySidebar(capturedFilePath);
+        if (evt.actions && evt.actions.length > 0) {
+          for (const action of evt.actions) await ccExecuteAction(action);
+        }
 
-      if (data.edited && data.content) {
-        const display = data.content.replace(/^---[\s\S]*?---\n*/m, '');
-        const isJson = capturedFilePath && capturedFilePath.endsWith('.json');
-        sessionDocContext.content = display;
-        sessionDocContext.selection = '';
-        if (_qaIsActiveSession(sessionKey)) {
-          const body = document.getElementById('modal-body');
-          if (isJson) {
-            body.textContent = display;
-          } else {
-            body.innerHTML = renderMd(display);
-            body.style.fontFamily = "'Segoe UI', system-ui, sans-serif";
-            body.style.whiteSpace = 'normal';
+        if (evt.edited && evt.content) {
+          const display = evt.content.replace(/^---[\s\S]*?---\n*/m, '');
+          const isJson = capturedFilePath && capturedFilePath.endsWith('.json');
+          sessionDocContext.content = display;
+          sessionDocContext.selection = '';
+          if (_qaIsActiveSession(sessionKey)) {
+            const body = document.getElementById('modal-body');
+            if (isJson) {
+              body.textContent = display;
+            } else {
+              body.innerHTML = renderMd(display);
+              body.style.fontFamily = "'Segoe UI', system-ui, sans-serif";
+              body.style.whiteSpace = 'normal';
+            }
+            _modalDocContext.content = display;
           }
-          _modalDocContext.content = display;
         }
+
+        _qaPersistSession(sessionKey, {
+          threadHtml: updatedThreadHtml,
+          docContext: sessionDocContext,
+          filePath: capturedFilePath,
+          history: runtime.history,
+          queue: runtime.queue,
+        });
+        return;
       }
+      if (evt.type === 'error') throw new Error(evt.error || 'Failed');
+    }
 
-      _qaPersistSession(sessionKey, {
-        threadHtml: updatedThreadHtml,
-        docContext: sessionDocContext,
-        filePath: capturedFilePath,
-        history: runtime.history,
-        queue: runtime.queue,
-      });
-    } else {
-      const errorHtml = _qaBuildAssistantHtml('Error: ' + (data.error || 'Failed'), { color: 'var(--red)', isError: true, elapsed: qaElapsed });
-      const updatedThreadHtml = _qaMutateThreadHtml(sessionKey, tmp => {
-        const loadingEl = tmp.querySelector('#' + loadingId);
-        if (loadingEl) loadingEl.remove();
-        tmp.insertAdjacentHTML('beforeend', errorHtml);
-      });
-      _qaPersistSession(sessionKey, {
-        threadHtml: updatedThreadHtml,
-        docContext: sessionDocContext,
-        filePath: capturedFilePath,
-        history: runtime.history,
-        queue: runtime.queue,
-      });
+    while (true) {
+      const readResult = await reader.read();
+      if (readResult.done) break;
+      buf += decoder.decode(readResult.value, { stream: true });
+      const lines = buf.split('\n');
+      buf = lines.pop();
+      for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (!line.startsWith('data: ')) continue;
+        await _qaHandleStreamEvent(JSON.parse(line.slice(6)));
+      }
+    }
+    if (buf.trim()) {
+      const trailing = buf.split('\n');
+      for (let i = 0; i < trailing.length; i++) {
+        const line = trailing[i];
+        if (!line.startsWith('data: ')) continue;
+        await _qaHandleStreamEvent(JSON.parse(line.slice(6)));
+      }
     }
+    if (!terminalEventSeen) throw new Error('The response stream ended before completion.');
   } catch (e) {
     clearInterval(qaTimer);
     const qaElapsedExc = Math.round((Date.now() - qaStartTime) / 1000);
     const messageHtml = e.name === 'AbortError'
-      ? _qaBuildAssistantHtml('Stopped', { color: 'var(--muted)', isError: true, elapsed: qaElapsedExc })
-      : _qaBuildAssistantHtml('Error: ' + e.message, { color: 'var(--red)', isError: true, elapsed: qaElapsedExc });
+      ? (streamedText
+          ? _qaBuildAssistantHtml(streamedText + '\n\n_Stopped._', { borderColor: 'var(--muted)', elapsed: qaElapsedExc })
+          : _qaBuildAssistantHtml('Stopped', { color: 'var(--muted)', isError: true, elapsed: qaElapsedExc }))
+      : (streamedText
+          ? _qaBuildAssistantHtml(streamedText + '\n\nError: ' + e.message, { borderColor: 'var(--red)', elapsed: qaElapsedExc })
+          : _qaBuildAssistantHtml('Error: ' + e.message, { color: 'var(--red)', isError: true, elapsed: qaElapsedExc }));
     const updatedThreadHtml = _qaMutateThreadHtml(sessionKey, tmp => {
       const loadingEl = tmp.querySelector('#' + loadingId);
       if (loadingEl) loadingEl.remove();

package/dashboard.js

@@ -1291,12 +1291,111 @@ async function ccCall(message, { store = 'cc', sessionKey, extraContext, label =
   return result;
 }
 
+async function ccCallStreaming(message, { store = 'cc', sessionKey, extraContext, label = 'command-center', timeout = 900000, maxTurns, allowedTools = 'Bash,Read,Write,Edit,Glob,Grep,WebFetch,WebSearch', skipStatePreamble = false, model, onAbortReady, onChunk, onToolUse } = {}) {
+  if (!maxTurns) maxTurns = CONFIG.engine?.ccMaxTurns || shared.ENGINE_DEFAULTS.ccMaxTurns;
+  if (!model) model = CONFIG.engine?.ccModel || shared.ENGINE_DEFAULTS.ccModel;
+  const ccEffort = CONFIG.engine?.ccEffort || shared.ENGINE_DEFAULTS.ccEffort;
+  const existing = resolveSession(store, sessionKey);
+  let sessionId = existing ? existing.sessionId : null;
+
+  function buildPrompt({ includePreamble = true } = {}) {
+    const parts = (!skipStatePreamble && includePreamble) ? [`## Current Minions State (${new Date().toISOString().slice(0, 16)})\n\n${buildCCStatePreamble()}`] : [];
+    if (extraContext) parts.push(extraContext);
+    parts.push(message);
+    return parts.join('\n\n---\n\n');
+  }
+
+  let result;
+
+  if (sessionId && maxTurns > 1) {
+    const p1 = llm.callLLMStreaming(buildPrompt({ includePreamble: false }), '', {
+      timeout, label, model, maxTurns, allowedTools, sessionId, effort: ccEffort, direct: true,
+      onChunk,
+      onToolUse,
+    });
+    if (onAbortReady) onAbortReady(p1.abort);
+    result = await p1;
+    llm.trackEngineUsage(label, result.usage);
+
+    if (result.text) {
+      updateSession(store, sessionKey, result.sessionId || sessionId, true);
+      return result;
+    }
+
+    const sessionStillValid = llm.isResumeSessionStillValid(result);
+    if (sessionStillValid) {
+      console.log(`[${label}] Resume call failed (code=${result.code}, empty=${!result.text}) but session is still valid — preserving session for retry`);
+      updateSession(store, sessionKey, result.sessionId || sessionId, true);
+      return result;
+    }
+
+    console.log(`[${label}] Resume failed — session appears dead (code=${result.code}, empty=${!result.text}), retrying fresh...`);
+    sessionId = null;
+    if (store === 'cc') {
+      ccSession = { sessionId: null, createdAt: null, lastActiveAt: null, turnCount: 0 };
+      safeWrite(path.join(ENGINE_DIR, 'cc-session.json'), ccSession);
+    } else if (sessionKey) {
+      docSessions.delete(sessionKey);
+      schedulePersistDocSessions();
+    }
+  }
+
+  const freshPrompt = buildPrompt();
+  const p2 = llm.callLLMStreaming(freshPrompt, CC_STATIC_SYSTEM_PROMPT, {
+    timeout, label, model, maxTurns, allowedTools, effort: ccEffort, direct: true,
+    onChunk,
+    onToolUse,
+  });
+  if (onAbortReady) onAbortReady(p2.abort);
+  result = await p2;
+  llm.trackEngineUsage(label, result.usage);
+
+  if (result.text) {
+    updateSession(store, sessionKey, result.sessionId, false);
+    return result;
+  }
+
+  if (maxTurns <= 1) return result;
+  console.log(`[${label}] Fresh call also failed (code=${result.code}, empty=${!result.text}), retrying once more...`);
+  await new Promise(r => setTimeout(r, 2000));
+  const p3 = llm.callLLMStreaming(freshPrompt, CC_STATIC_SYSTEM_PROMPT, {
+    timeout, label, model, maxTurns, allowedTools, effort: ccEffort, direct: true,
+    onChunk,
+    onToolUse,
+  });
+  if (onAbortReady) onAbortReady(p3.abort);
+  result = await p3;
+  llm.trackEngineUsage(label, result.usage);
+
+  if (result.text) {
+    updateSession(store, sessionKey, result.sessionId, false);
+  }
+  return result;
+}
+
 // Lightweight content fingerprint — same algorithm used browser-side (no crypto needed)
 function contentFingerprint(str) {
   if (!str) return '';
   return str.length + ':' + str.charCodeAt(0) + ':' + str.charCodeAt(str.length - 1);
 }
 
+function _parseDocChatResultText(text) {
+  const delimIdx = text.indexOf('---DOCUMENT---');
+  if (delimIdx >= 0) {
+    const answerPart = text.slice(0, delimIdx).trim();
+    const { text: answer, actions } = parseCCActions(answerPart);
+    let content = text.slice(delimIdx + '---DOCUMENT---'.length).trim();
+    content = content.replace(/^```\w*\n?/, '').replace(/\n?```$/, '').trim();
+    return { answer, content, actions };
+  }
+  const { text: stripped, actions } = parseCCActions(text);
+  return { answer: stripped, content: null, actions };
+}
+
+function _docChatDisplayText(text) {
+  return _parseDocChatResultText(text).answer;
+}
+
 // Doc-specific wrapper — adds document context, parses ---DOCUMENT---
 async function ccDocCall({ message, document, title, filePath, selection, canEdit, isJson, model, freshSession, onAbortReady }) {
   const sessionKey = filePath || title;
@@ -1349,18 +1448,54 @@ async function ccDocCall({ message, document, title, filePath, selection, canEdi
     return { answer: 'Failed to process request. Try again.', content: null, actions: [] };
   }
 
-  // Parse ---DOCUMENT--- BEFORE actions — document content may contain ===ACTIONS=== literally
-  const delimIdx = result.text.indexOf('---DOCUMENT---');
-  if (delimIdx >= 0) {
-    const answerPart = result.text.slice(0, delimIdx).trim();
-    const { text: answer, actions } = parseCCActions(answerPart);
-    let content = result.text.slice(delimIdx + '---DOCUMENT---'.length).trim();
-    content = content.replace(/^```\w*\n?/, '').replace(/\n?```$/, '').trim();
-    return { answer, content, actions };
+  return _parseDocChatResultText(result.text);
+}
+
+async function ccDocCallStreaming({ message, document, title, filePath, selection, canEdit, isJson, model, freshSession, onAbortReady, onChunk, onToolUse }) {
+  const sessionKey = filePath || title;
+  const docSlice = document.slice(0, 20000);
+
+  if (freshSession && sessionKey) {
+    docSessions.delete(sessionKey);
   }
 
-  const { text: stripped, actions } = parseCCActions(result.text);
-  return { answer: stripped, content: null, actions };
+  const docHash = require('crypto').createHash('md5').update(docSlice).digest('hex').slice(0, 8);
+  const existing = freshSession ? null : resolveSession('doc', sessionKey);
+  const docUnchanged = existing?.sessionId && existing._docHash === docHash;
+
+  let docContext;
+  if (docUnchanged) {
+    docContext = `## Document: ${title || 'Document'}${filePath ? ' (`' + filePath + '`)' : ''}${selection ? '\n**Selected text:**\n> ' + selection.slice(0, 1500) : ''}${canEdit ? '\nIf editing: respond with your explanation, then \`---DOCUMENT---\` on its own line, then the COMPLETE updated file.' : ''}`;
+  } else {
+    docContext = `## Document Context\n**${title || 'Document'}**${filePath ? ' (`' + filePath + '`)' : ''}${isJson ? ' (JSON)' : ''}\n${selection ? '\n**Selected text:**\n> ' + selection.slice(0, 1500) + '\n' : ''}\n\`\`\`\n${docSlice}\n\`\`\`\n${canEdit ? '\nIf editing: respond with your explanation, then \`---DOCUMENT---\` on its own line, then the COMPLETE updated file.' : '\n(Read-only — answer questions only.)'}`;
+  }
+
+  const result = await ccCallStreaming(message, {
+    store: 'doc', sessionKey,
+    extraContext: docContext, label: 'doc-chat',
+    allowedTools: canEdit ? 'Read,Write,Edit,Glob,Grep' : 'Read,Glob,Grep',
+    maxTurns: canEdit ? 25 : 10,
+    skipStatePreamble: true,
+    ...(model ? { model } : {}),
+    onAbortReady,
+    onChunk: (text) => { if (onChunk) onChunk(_docChatDisplayText(text)); },
+    onToolUse,
+  });
+
+  if (freshSession && sessionKey) {
+    docSessions.delete(sessionKey);
+    schedulePersistDocSessions();
+  } else if (result.code === 0 && result.sessionId) {
+    const session = resolveSession('doc', sessionKey);
+    if (session) session._docHash = docHash;
+  }
+
+  if (result.code !== 0 || !result.text) {
+    console.error(`[doc-chat-stream] Failed: code=${result.code}, empty=${!result.text}, filePath=${filePath}, stderr=${(result.stderr || '').slice(0, 200)}`);
+    return { answer: 'Failed to process request. Try again.', content: null, actions: [] };
+  }
+
+  return _parseDocChatResultText(result.text);
 }
 
 // -- POST helpers --
@@ -3429,7 +3564,8 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       docChatInFlight.add(docKey);
       // Kill LLM process + release guard if client disconnects (abort/navigation)
       let _docAbort = null;
-      req.on('close', () => { docChatInFlight.delete(docKey); if (_docAbort) _docAbort(); });
+      let _docDone = false;
+      req.on('close', () => { if (!_docDone) { docChatInFlight.delete(docKey); if (_docAbort) _docAbort(); } });
 
       try {
       const canEdit = !!body.filePath;
@@ -3478,13 +3614,152 @@ What would you like to discuss or change? When you're happy, say "approve" and I
 
         safeWrite(fullPath, content);
 
+        _docDone = true;
         return jsonReply(res, 200, { ok: true, answer, edited: true, content, actions });
       }
+      _docDone = true;
       return jsonReply(res, 200, { ok: true, answer: answer + '\n\n(Read-only — changes not saved)', edited: false, actions });
-      } finally { _docAbort = null; docChatInFlight.delete(docKey); }
+      } finally { _docAbort = null; _docDone = true; docChatInFlight.delete(docKey); }
     } catch (e) { return jsonReply(res, e.statusCode || 500, { error: e.message }); }
   }
 
+  async function handleDocChatStream(req, res) {
+    let docKey = null;
+    let _docAbort = null;
+    let _docStreamEnded = false;
+    let _docHeartbeatTimer = null;
+    const writeDocEvent = (payload) => {
+      try {
+        res.write('data: ' + JSON.stringify(payload) + '\n\n');
+        return true;
+      } catch {
+        return false;
+      }
+    };
+    const stopDocHeartbeat = () => {
+      if (_docHeartbeatTimer) {
+        clearInterval(_docHeartbeatTimer);
+        _docHeartbeatTimer = null;
+      }
+    };
+    try {
+      const body = await readBody(req);
+      if (!body.message) { res.statusCode = 400; res.setHeader('Content-Type', 'application/json'); res.end(JSON.stringify({ error: 'message required' })); return; }
+      if (!body.document) { res.statusCode = 400; res.setHeader('Content-Type', 'application/json'); res.end(JSON.stringify({ error: 'document required' })); return; }
+
+      docKey = body.filePath || body.title || 'default';
+      if (docChatInFlight.has(docKey)) {
+        res.statusCode = 429;
+        res.setHeader('Content-Type', 'application/json');
+        res.end(JSON.stringify({ error: 'This document is already being processed — wait for the current response.' }));
+        return;
+      }
+      docChatInFlight.add(docKey);
+
+      const canEdit = !!body.filePath;
+      const isJson = body.filePath?.endsWith('.json');
+      let currentContent = body.document;
+      let fullPath = null;
+      if (canEdit) {
+        try { shared.sanitizePath(body.filePath, MINIONS_DIR); }
+        catch { docChatInFlight.delete(docKey); res.statusCode = 400; res.setHeader('Content-Type', 'application/json'); res.end(JSON.stringify({ error: 'path must be under minions directory' })); return; }
+        fullPath = path.resolve(MINIONS_DIR, body.filePath);
+        const diskContent = safeRead(fullPath);
+        if (diskContent !== null) {
+          if (!(body.contentHash && contentFingerprint(diskContent) === body.contentHash)) {
+            currentContent = diskContent;
+          }
+        }
+      }
+
+      res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', 'Connection': 'keep-alive' });
+      writeDocEvent({ type: 'heartbeat' });
+      _docHeartbeatTimer = setInterval(() => {
+        if (_docStreamEnded) {
+          stopDocHeartbeat();
+          return;
+        }
+        if (!writeDocEvent({ type: 'heartbeat' })) stopDocHeartbeat();
+      }, CC_STREAM_HEARTBEAT_MS);
+
+      req.on('close', () => {
+        if (!_docStreamEnded) {
+          stopDocHeartbeat();
+          docChatInFlight.delete(docKey);
+          if (_docAbort) _docAbort();
+        }
+      });
+
+      try {
+
+        const { answer, content, actions } = await ccDocCallStreaming({
+          message: body.message, document: currentContent, title: body.title,
+          filePath: body.filePath, selection: body.selection, canEdit, isJson,
+          model: body.model || undefined,
+          freshSession: !!body.freshSession,
+          onAbortReady: (abort) => { _docAbort = abort; },
+          onChunk: (text) => { writeDocEvent({ type: 'chunk', text }); },
+          onToolUse: (name, input) => { writeDocEvent({ type: 'tool', name, input: _lightToolInput(input) }); },
+        });
+
+        if (!content) {
+          writeDocEvent({ type: 'done', text: answer, edited: false, actions });
+          _docStreamEnded = true;
+          res.end();
+          return;
+        }
+
+        if (isJson) {
+          try { JSON.parse(content); } catch (e) {
+            writeDocEvent({ type: 'done', text: answer + '\n\n(JSON invalid — not saved: ' + e.message + ')', edited: false, actions });
+            _docStreamEnded = true;
+            res.end();
+            return;
+          }
+        }
+
+        if (canEdit && fullPath) {
+          if (body.filePath && /^meetings\//.test(body.filePath) && isJson) {
+            try {
+              const mtg = safeJson(fullPath);
+              if (mtg && (mtg.status === 'completed' || mtg.status === 'archived')) {
+                writeDocEvent({ type: 'done', text: answer, edited: false, actions });
+                _docStreamEnded = true;
+                res.end();
+                return;
+              }
+            } catch { /* proceed with write if can't read */ }
+          }
+
+          safeWrite(fullPath, content);
+          writeDocEvent({ type: 'done', text: answer, edited: true, content, actions });
+          _docStreamEnded = true;
+          res.end();
+          return;
+        }
+
+        writeDocEvent({ type: 'done', text: answer + '\n\n(Read-only — changes not saved)', edited: false, actions });
+        _docStreamEnded = true;
+        res.end();
+      } finally {
+        stopDocHeartbeat();
+        docChatInFlight.delete(docKey);
+      }
+    } catch (e) {
+      stopDocHeartbeat();
+      if (docKey) docChatInFlight.delete(docKey);
+      if (!res.headersSent) {
+        res.statusCode = e.statusCode || 500;
+        res.setHeader('Content-Type', 'application/json');
+        try { res.end(JSON.stringify({ error: e.message })); } catch {}
+      } else {
+        writeDocEvent({ type: 'error', error: e.message });
+        _docStreamEnded = true;
+        try { res.end(); } catch {}
+      }
+    }
+  }
+
   async function handleInboxPersist(req, res) {
     try {
       const body = await readBody(req);
@@ -4206,6 +4481,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         }
         if (!writeCcEvent({ type: 'heartbeat' })) stopCcHeartbeat();
       }, CC_STREAM_HEARTBEAT_MS);
+      // Kill LLM process immediately if client disconnects mid-stream.
       // Keep the LLM alive briefly after disconnect so the UI can reattach to the same in-flight turn.
       req.on('close', () => {
         if (!_ccStreamEnded) {
@@ -5229,6 +5505,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
 
     // 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 },
+    { method: 'POST', path: '/api/doc-chat/stream', desc: 'Streaming doc chat — SSE with text chunks and tool progress', params: 'message, document, title?, filePath?, selection?, contentHash?', handler: handleDocChatStream },
 
     // Inbox
     { method: 'POST', path: '/api/inbox/persist', desc: 'Promote an inbox item to team notes', params: 'name', handler: handleInboxPersist },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.1579",
+  "version": "0.1.1581",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"

package/playbooks/shared-rules.md

@@ -64,6 +64,8 @@ The engine kills agents that produce no stdout for `heartbeatTimeout` (default *
 
 Why: each line that the build emits arrives as a notification, which resets the heartbeat. You see live progress in the dashboard. The Monitor call itself is recognised by the engine as a blocking tool (heartbeat extended ~30 min).
 
+> ⚠️ **Never use `Monitor({ command: "tail -F <file> | grep ..." })` for long builds.** It looks tidy — only the lines you care about — but it is a heartbeat trap. Cold Gradle / MSBuild / `cargo build` spend 3–8 minutes in a startup + dependency-resolution phase that produces output that **does not match** typical filter terms (`BUILD SUCCESSFUL`, `BUILD FAILED`, `error:`). The grep filter swallows every line, Monitor emits zero notifications, the heartbeat fires at 300s, and the engine kills the agent mid-build. Always pass `bash_id` directly — every output line resets the heartbeat, and noisy output is the *whole point* of the pattern.
+
 ### Pattern B — Single Bash call with explicit `timeout`
 
 ```
@@ -75,6 +77,7 @@ The engine reads `input.timeout` from the tool call and extends the heartbeat to
 ### What NOT to do
 
 - Do NOT run `./gradlew`, `mvn`, `dotnet test`, or any cold-cache build as a default `Bash` call (no `timeout`, no `run_in_background`). It will hit the 120s Bash default, then the 300s heartbeat, and the engine will kill you.
+- Do NOT use `Monitor({ command: "tail | grep ..." })` for any build that has a silent startup phase (cold Gradle, MSBuild, fresh `npm install`, `cargo build`). The grep filter suppresses Gradle's startup output, Monitor emits nothing, heartbeat fires at 300s, agent is killed. Use `Monitor({ bash_id })` instead — noisy output is better than a dead agent.
 - Do NOT loop `sleep` to "wait it out" — sleep produces no stdout and looks identical to a hang.
 - Do NOT pipe through `tee` thinking that helps — heartbeat reads agent stdout, not the underlying file.