@yemi33/minions 0.1.2436 → 0.1.2438

package/dashboard/js/command-center.js

@@ -1300,6 +1300,14 @@ async function _ccDoSend(message, skipUserMsg, forceTabId, intentMetadata) {
     var pendingEventName = '';
 
     async function _handleEvent(evt) {
+      // W-ms4z164i01fo438d — terminal frames are idempotent per connection.
+      // A failed turn used to put two `event: error` frames on the wire and
+      // render two identical error bubbles; the backend now emits one, and
+      // this guard keeps the UI correct against any future double-emit or a
+      // terminal frame that arrives twice. `terminalEventSeen` is scoped to
+      // one _ccConsumeStream call, so a reconnect that replays donePayload
+      // still renders it exactly once on the new connection.
+      if (terminalEventSeen && evt && (evt.type === 'done' || evt.type === 'error')) return;
       // First event after a reconnect: the server replays the full accumulated
       // snapshot (all prior tools, then the whole text as one chunk — see the
       // reconnect branch in dashboard.js). Swap the pre-reconnect segments out

package/dashboard/js/render-kb.js

@@ -205,17 +205,32 @@ async function kbSweep() {
 }
 
 let _memorySearchUiLoading = false;
+// Lazily loads /assets/memory-search.js, then opens the modal.
+//
+// Both failure paths matter (W-ms5dlone012i457a-c):
+//   - script.onerror  -> the network/404 case
+//   - script.onload but window.MinionsMemorySearch still undefined -> the
+//     script was served but did not register (e.g. a truncated/empty body, or
+//     it threw while evaluating). Dereferencing .open() here used to raise an
+//     uncaught TypeError.
+// In every path the loading latch must be cleared, otherwise the early-return
+// below permanently and silently bricks the button for the rest of the session.
 function openMemorySearchModal() {
   if (window.MinionsMemorySearch) return window.MinionsMemorySearch.open();
   if (_memorySearchUiLoading) return;
   _memorySearchUiLoading = true;
   const script = document.createElement('script');
   script.src = '/assets/memory-search.js';
-  script.onload = () => window.MinionsMemorySearch.open();
-  script.onerror = () => {
+  const fail = () => {
     _memorySearchUiLoading = false;
     showToast('kb-sweep-toast', 'Memory search UI failed to load', false);
   };
+  script.onload = () => {
+    _memorySearchUiLoading = false;
+    if (!window.MinionsMemorySearch) return fail();
+    window.MinionsMemorySearch.open();
+  };
+  script.onerror = fail;
   document.head.appendChild(script);
 }
 
@@ -262,7 +277,24 @@ async function submitKbEntry(e) {
 
 async function kbOpenItem(category, file) {
   try {
-    const content = await fetch('/api/knowledge/' + category + '/' + encodeURIComponent(file)).then(r => r.text());
+    const res = await fetch('/api/knowledge/' + category + '/' + encodeURIComponent(file));
+    // Without this check a 404/500 body was rendered as if it were the entry,
+    // and a 200-with-empty-body opened a completely blank modal with no error
+    // (W-ms5dlone012i457a-c). Surface the failure instead of rendering nothing.
+    if (!res.ok) {
+      document.getElementById('modal-title').textContent = file;
+      const failBody = document.getElementById('modal-body');
+      failBody.replaceChildren();
+      const msg = document.createElement('p');
+      msg.className = 'empty';
+      msg.textContent = res.status === 404
+        ? 'This knowledge entry no longer exists on disk (404). It may have been renamed or swept.'
+        : 'Could not load this knowledge entry (HTTP ' + res.status + ').';
+      failBody.appendChild(msg);
+      document.getElementById('modal').classList.add('open');
+      return;
+    }
+    const content = await res.text();
     const display = content.replace(/^---[\s\S]*?---\n*/m, '');
     document.getElementById('modal-title').textContent = file;
     const modalBody = document.getElementById('modal-body');

package/dashboard-build.js

@@ -10,6 +10,54 @@ const { safeRead } = shared;
 const MINIONS_DIR = __dirname;
 const DASHBOARD_SHARED_JS = ['pr-merge-state', 'pr-filters', 'cc-suggestions', 'model-display', 'watches-source', 'project-git-summary', 'welcome-popup'];
 
+// ── Canonical classic-dashboard assembly manifest ──────────────────────────
+// Single source of truth, consumed by BOTH assemblers: buildDashboardHtml()
+// below and dashboard.js#buildDashboardHtml() (the one the real server ships).
+// These used to be duplicated array literals inside each function; they drifted
+// (dashboard.js lost 'memory-panel' and never gained sub-fragment substitution
+// at all), which silently shipped an /engine page with no Memory panel and no
+// working "Capture heap snapshot" button. Keep them here and import them —
+// never re-declare a local copy. Pinned by test/unit/dashboard-assembly-parity.test.js.
+const DASHBOARD_PAGES = ['home', 'work', 'prs', 'plans', 'inbox', 'tools', 'schedule', 'watches', 'pipelines', 'meetings', 'qa', 'engine'];
+
+// Sub-fragments substituted into a parent page at assembly time via
+// <!-- __MARKER__ --> tokens. Lets large panels live in their own
+// fragment file without inflating the parent page. P-d4e5f6a7 introduced
+// engine-memory-panel.html as the first such sub-fragment; add more here
+// by mapping page -> { marker -> fragment basename }.
+const DASHBOARD_PAGE_SUB_FRAGMENTS = {
+  engine: { '<!-- __ENGINE_MEMORY_PANEL__ -->': 'engine-memory-panel' },
+};
+
+// JS module bundle (order matters: utils → state → renderers → commands → refresh).
+// Every dashboard/js/*.js file belongs here unless it is lazy-loaded through a
+// dedicated route (only memory-search.js today, served at /assets/memory-search.js).
+const DASHBOARD_JS_FILES = [
+  'utils', 'state', 'features-client', 'render-utils', 'charter-editor', 'detail-panel', 'live-stream',
+  'render-agents', 'render-dispatch', 'render-work-items', 'render-prd',
+  'render-prs', 'render-plans', 'render-inbox', 'render-kb', 'render-skills',
+  'render-other', 'render-managed', 'memory-panel', 'render-schedules', 'render-watches', 'render-pipelines', 'render-meetings', 'render-pinned',
+  'command-parser', 'command-input', 'command-center', 'command-history',
+  'confirm-dialog', 'modal', 'modal-qa', 'settings', 'qa', 'fre', 'refresh',
+];
+
+/**
+ * Read a page fragment and substitute any sub-fragment markers declared for it.
+ * Shared by both assemblers so a sub-fragment can never be wired into one only.
+ */
+function readPageFragment(dashDir, page) {
+  let content = safeRead(path.join(dashDir, 'pages', page + '.html'));
+  const subs = DASHBOARD_PAGE_SUB_FRAGMENTS[page];
+  if (subs) {
+    for (const [marker, basename] of Object.entries(subs)) {
+      const fragment = safeRead(path.join(dashDir, 'pages', basename + '.html'));
+      // Function replacer: fragment text may contain `$&`/`$1` patterns.
+      content = content.replace(marker, () => fragment);
+    }
+  }
+  return content;
+}
+
 function buildDashboardHtml() {
   const dashDir = path.join(MINIONS_DIR, 'dashboard');
   const layoutPath = path.join(dashDir, 'layout.html');
@@ -21,37 +69,15 @@ function buildDashboardHtml() {
   const layout = safeRead(layoutPath);
   const css = safeRead(path.join(dashDir, 'styles.css'));
 
-  const pages = ['home', 'work', 'prs', 'plans', 'inbox', 'tools', 'schedule', 'watches', 'pipelines', 'meetings', 'qa', 'engine'];
-  // Sub-fragments substituted into a parent page at assembly time via
-  // <!-- __MARKER__ --> tokens. Lets large panels live in their own
-  // fragment file without inflating the parent page. P-d4e5f6a7 introduced
-  // engine-memory-panel.html as the first such sub-fragment; add more here
-  // by mapping marker -> fragment basename.
-  const pageSubFragments = {
-    engine: { '<!-- __ENGINE_MEMORY_PANEL__ -->': 'engine-memory-panel' },
-  };
+  const pages = DASHBOARD_PAGES;
   let pageHtml = '';
   for (const p of pages) {
-    let content = safeRead(path.join(dashDir, 'pages', p + '.html'));
-    const subs = pageSubFragments[p];
-    if (subs) {
-      for (const [marker, basename] of Object.entries(subs)) {
-        const fragment = safeRead(path.join(dashDir, 'pages', basename + '.html'));
-        content = content.replace(marker, () => fragment);
-      }
-    }
+    const content = readPageFragment(dashDir, p);
     const activeClass = p === 'home' ? ' active' : '';
     pageHtml += `    <div class="page${activeClass}" id="page-${p}">\n${content}\n    </div>\n\n`;
   }
 
-  const jsFiles = [
-    'utils', 'state', 'features-client', 'render-utils', 'charter-editor', 'detail-panel', 'live-stream',
-    'render-agents', 'render-dispatch', 'render-work-items', 'render-prd',
-    'render-prs', 'render-plans', 'render-inbox', 'render-kb', 'render-skills',
-    'render-other', 'render-managed', 'memory-panel', 'render-schedules', 'render-watches', 'render-pipelines', 'render-meetings', 'render-pinned',
-    'command-parser', 'command-input', 'command-center', 'command-history',
-    'confirm-dialog', 'modal', 'modal-qa', 'settings', 'qa', 'fre', 'refresh'
-  ];
+  const jsFiles = DASHBOARD_JS_FILES;
   let jsHtml = '';
   for (const f of DASHBOARD_SHARED_JS) {
     const content = safeRead(path.join(dashDir, 'shared', f + '.js'));
@@ -175,6 +201,10 @@ module.exports = {
   buildDashboardHtml,
   buildSlimHtml,
   DASHBOARD_SHARED_JS,
+  DASHBOARD_PAGES,
+  DASHBOARD_PAGE_SUB_FRAGMENTS,
+  DASHBOARD_JS_FILES,
+  readPageFragment,
   SLIM_JS_ORDER,
   _resetSlimPartsCacheForTest,
 };

package/dashboard.js

@@ -68,7 +68,12 @@ const prFixTarget = require('./engine/pr-fix-target');
 const prTrack = require('./engine/pr-track');
 const resolveArea = require('./engine/resolve-area');
 const features = require('./engine/features');
-const { DASHBOARD_SHARED_JS } = require('./dashboard-build');
+const {
+  DASHBOARD_SHARED_JS,
+  DASHBOARD_PAGES,
+  DASHBOARD_JS_FILES,
+  readPageFragment,
+} = require('./dashboard-build');
 const { normalizeExecutionModel } = require('./engine/execution-model');
 const ccWorkerPool = require('./engine/cc-worker-pool');
 const diagnosticsMemory = require('./engine/diagnostics-memory');
@@ -1920,30 +1925,23 @@ function buildDashboardHtml() {
   // Assemble page fragments. Each wrapper gets a `.page-toast` inline slot at
   // the top — showToast('cmd-toast', …) auto-routes here when a page is active,
   // so feedback lands near the action instead of the floating top-right toast.
-  const pages = ['home', 'work', 'prs', 'plans', 'inbox', 'tools', 'schedule', 'watches', 'pipelines', 'meetings', 'qa', 'engine'];
+  // Page list, sub-fragment map and fragment reader all come from
+  // dashboard-build.js so this assembler cannot drift from the standalone one.
   const pageToast = '      <div class="cmd-toast cmd-toast-inline page-toast" style="margin:6px 16px"></div>\n';
   let pageHtml = '';
-  for (const p of pages) {
-    const content = safeRead(path.join(dashDir, 'pages', p + '.html'));
+  for (const p of DASHBOARD_PAGES) {
+    const content = readPageFragment(dashDir, p);
     const activeClass = p === 'home' ? ' active' : '';
     pageHtml += `    <div class="page${activeClass}" id="page-${p}">\n${pageToast}${content}\n    </div>\n\n`;
   }
 
   // Assemble JS modules (order matters: utils → state → renderers → commands → refresh)
-  const jsFiles = [
-    'utils', 'state', 'features-client', 'render-utils', 'charter-editor', 'detail-panel', 'live-stream',
-    'render-agents', 'render-dispatch', 'render-work-items', 'render-prd',
-    'render-prs', 'render-plans', 'render-inbox', 'render-kb', 'render-skills',
-    'render-other', 'render-managed', 'render-schedules', 'render-watches', 'render-pipelines', 'render-meetings', 'render-pinned',
-    'command-parser', 'command-input', 'command-center', 'command-history',
-    'confirm-dialog', 'modal', 'modal-qa', 'settings', 'qa', 'fre', 'refresh'
-  ];
   let jsHtml = '';
   for (const f of DASHBOARD_SHARED_JS) {
     const content = safeRead(path.join(dashDir, 'shared', f + '.js'));
     jsHtml += `\n// ─── shared/${f}.js ────────────────────────────────────────\n${content}\n`;
   }
-  for (const f of jsFiles) {
+  for (const f of DASHBOARD_JS_FILES) {
     const content = safeRead(path.join(dashDir, 'js', f + '.js'));
     jsHtml += `\n// ─── ${f}.js ────────────────────────────────────────\n${content}\n`;
   }
@@ -3800,6 +3798,49 @@ const CC_ERROR_CODES = Object.freeze([
   // surfaces this typed code via _buildCcErrorEnvelope, never a 500.
   'invalid-image',
 ]);
+// W-ms4z164i01fo438d — a `done` or `error` frame is the LAST thing a CC or
+// doc-chat SSE consumer will ever see, so neither writer may shed one under
+// backpressure. Shared by writeCcEvent and writeDocEvent so the rule lives in
+// one place instead of being restated per stream.
+function _isTerminalSseFrameType(type) {
+  return type === 'done' || type === 'error';
+}
+
+// W-mpmwxni2000c25c7-d / W-ms4z164i01fo438d — render exactly ONE SSE frame.
+// Terminal error frames get a named `event: error` line so consumers using
+// addEventListener('error', …) (and tests matching the raw wire) can target
+// them; the JSON payload still carries `type: 'error'` so data-line-only
+// parsers keep working. Shared by writeCcEvent and writeDocEvent.
+//
+// One call == one frame. A caller that emits a terminal error through a writer
+// AND raw-writes its own `event: error` frame puts two frames on the wire, and
+// the CC client backfills `type` from the `event:` line — so both render as
+// error bubbles. That was the duplicate-error-bubble bug; keep this the single
+// wire-rendering seam.
+function _sseFrame(payload) {
+  const eventLine = (payload && payload.type === 'error') ? 'event: error\n' : '';
+  return eventLine + 'data: ' + JSON.stringify(payload) + '\n\n';
+}
+
+// W-ms4z164i01fo438d — canonical terminal-error payload for a failed CC stream
+// turn. Stored on `liveState.donePayload` (so the reconnect branch replays the
+// exact same terminal frame to a reattaching client) and handed to the writer
+// once. `message` is the canonical envelope field; `error` is kept as a legacy
+// alias for clients predating the typed envelope. `stderr` carries the tail
+// that used to ride only on the now-removed raw frame.
+function _buildCcTerminalErrorPayload(envelope, stderrTail) {
+  const message = (envelope && envelope.message) || 'Command Center reported an unknown error.';
+  return {
+    type: 'error',
+    message,
+    error: message,
+    code: (envelope && envelope.code) || 'crash',
+    retriable: !!(envelope && envelope.retriable),
+    sessionId: null,
+    ...(stderrTail ? { stderr: String(stderrTail).slice(0, 500) } : {}),
+  };
+}
+
 function _buildCcErrorEnvelope({ message, code, retryable, ...extra } = {}) {
   const normalizedCode = CC_ERROR_CODES.includes(code) ? code : 'crash';
   return {
@@ -9039,7 +9080,11 @@ const server = http.createServer(async (req, res) => {
       MINIONS_DIR,
     );
     const kbCatDir = path.join(MINIONS_DIR, 'knowledge', cat);
-    const content = safeRead(path.join(kbCatDir, file));
+    // safeReadOrNull (not safeRead): safeRead collapses ENOENT to '', which
+    // made this 404 guard dead code and served a missing entry as 200 with an
+    // empty body — render-kb.js#kbOpenItem then opened a blank modal with no
+    // error. Present-but-empty still reads as '' and correctly returns 200.
+    const content = safeReadOrNull(path.join(kbCatDir, file));
     if (content === null) return jsonReply(res, 404, { error: 'not found', code: 'not-found' });
     res.setHeader('Content-Type', 'text/plain; charset=utf-8');
     res.end(content);
@@ -10318,7 +10363,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     } catch { /* listener registration is best-effort */ }
     const writeDocEvent = (payload) => {
       const type = payload && payload.type;
-      const isTerminal = type === 'done' || type === 'error';
+      const isTerminal = _isTerminalSseFrameType(type);
       const _logFail = (reason) => {
         try {
           shared.log('warn', `[doc-sse-fail] ${JSON.stringify({ doc: docKey || 'unknown', type, reason, destroyed: !!res.destroyed, writableEnded: !!res.writableEnded, streamEnded: _docStreamEnded })}`);
@@ -10330,14 +10375,12 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       }
       let wire;
       try {
-        // W-mpmwxni2000c25c7-d / W-mqevl09s000i9989 — terminal error frames go
-        // out as a named SSE `event: error` frame so consumers using
-        // addEventListener('error', …) can target them, mirroring the
-        // handleCommandCenterStream contract. The JSON payload still carries
-        // `type: 'error'` for the data-line parser in modal-qa.js.
-        wire = (type === 'error')
-          ? `event: error\ndata: ${JSON.stringify(payload)}\n\n`
-          : `data: ${JSON.stringify(payload)}\n\n`;
+        // W-mpmwxni2000c25c7-d / W-mqevl09s000i9989 — one frame per call via
+        // the shared _sseFrame renderer (mirrors handleCommandCenterStream):
+        // terminal errors go out as a named `event: error` frame, and the JSON
+        // payload still carries `type: 'error'` for the data-line parser in
+        // modal-qa.js.
+        wire = _sseFrame(payload);
       } catch {
         _logFail('json-serialize-failed');
         return false;
@@ -11629,6 +11672,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     const writeCcEvent = (payload) => {
       const type = payload && payload.type;
       const isUserFacing = type === 'chunk' || type === 'done' || type === 'tool' || type === 'tool-update' || type === 'error';
+      const isTerminal = _isTerminalSseFrameType(type);
       const _logFail = (reason, extra) => {
         if (!isUserFacing) return;
         try {
@@ -11651,14 +11695,12 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       }
       let wire;
       try {
-        // W-mpmwxni2000c25c7-d — terminal error frames go out as `event: error`
-        // so SSE consumers using addEventListener('error', …) and tests
-        // matching the raw wire format can target them directly. The JSON
-        // payload still carries `type: 'error'` so the existing
-        // data-line parser (and any client code that only reads `data:`
-        // lines) keeps working.
-        const eventLine = (type === 'error') ? 'event: error\n' : '';
-        wire = eventLine + 'data: ' + JSON.stringify(payload) + '\n\n';
+        // W-mpmwxni2000c25c7-d / W-ms4z164i01fo438d — one frame per call via
+        // the shared _sseFrame renderer. This is the ONLY place a CC terminal
+        // error reaches the wire: callers must not also `res.write` their own
+        // `event: error` frame, because the client backfills `type` from the
+        // `event:` line and would render a second error bubble.
+        wire = _sseFrame(payload);
       }
       catch (err) {
         _logFail('json-serialize-failed', { error: String((err && err.message) || err).slice(0, 200) });
@@ -11676,7 +11718,11 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       // bump _ccTelemetry counters so the [cc-stream] outcome log line stays
       // truthful about what the orchestrator produced — only the wire was
       // shed, the work happened.
-      if (_queuedBytes > SSE_MAX_QUEUE_BYTES) {
+      // W-ms4z164i01fo438d — terminal `done` / `error` frames are NEVER shed
+      // (mirrors writeDocEvent). The terminal error used to also go out via a
+      // raw res.write that bypassed this cap entirely; now that the writer is
+      // the single emitter, shedding it would drop the failure off the wire.
+      if (!isTerminal && _queuedBytes > SSE_MAX_QUEUE_BYTES) {
         try {
           shared.log('warn', `[cc-sse-shed] tab=${tabId || _ccTelemetry.tabId || 'unknown'} type=${type} queuedBytes=${_queuedBytes} wireBytes=${wire.length}`);
         } catch { /* telemetry is best-effort */ }
@@ -12117,12 +12163,17 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           trackErr('command-center', envelope.code);
           const stderrTail = (result.stderr || '').trim().split('\n').filter(Boolean).slice(-3).join(' | ');
           console.error(`[CC-stream] Failed code=${envelope.code} retriable=${envelope.retriable}: ${(result.stderr || '').slice(0, 500)}; stdout_tail=${(result.raw || '').slice(-500)}`);
-          // Emit `event: error` (named SSE frame), then a `done`-style frame
-          // for clients that only handle the default message channel, then
-          // close cleanly so the EventSource exits its read loop without
-          // throwing a connection-reset.
-          try { res.write(`event: error\ndata: ${JSON.stringify({ message: envelope.message, code: envelope.code, retriable: !!envelope.retriable, ...(stderrTail ? { stderr: stderrTail.slice(0, 500) } : {}) })}\n\n`); } catch {}
-          liveState.donePayload = { type: 'error', error: envelope.message, code: envelope.code, retriable: !!envelope.retriable, sessionId: null };
+          // W-ms4z164i01fo438d — emit exactly ONE terminal frame. writeCcEvent
+          // prefixes `event: error\n` for `type: 'error'`, so this single call
+          // satisfies both the named-SSE-frame contract and the `data:`-only
+          // parser. This block previously ALSO did a raw
+          // `res.write('event: error\ndata: …')` before calling the writer,
+          // which put two `event: error` frames on the wire and rendered two
+          // identical error bubbles (each with its own Retry / New Session
+          // controls) in the Command Center. donePayload keeps carrying the
+          // canonical envelope so the reconnect branch above replays the same
+          // single terminal frame to a reattaching client.
+          liveState.donePayload = _buildCcTerminalErrorPayload(envelope, stderrTail);
           if (liveState.writer) liveState.writer(liveState.donePayload);
           if (liveState.endResponse) liveState.endResponse();
           _scheduleCcLiveCleanup(tabId);
@@ -15778,7 +15829,9 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       catch { return jsonReply(res, 400, { error: 'invalid path' }); }
       const agentsDir = path.join(MINIONS_DIR, 'agents');
       if (!safePath.startsWith(agentsDir + path.sep)) return jsonReply(res, 400, { error: 'path must be within agents/' });
-      const content = _agentApiCall('readOutputFile', safeRead, safePath);
+      // safeReadOrNull (not safeRead) so a missing log 404s instead of being
+      // served as 200 with an empty body — see the KB read above.
+      const content = _agentApiCall('readOutputFile', safeReadOrNull, safePath);
       if (content === null) return jsonReply(res, 404, { error: 'not found' });
       res.setHeader('Content-Type', 'text/plain; charset=utf-8');
       res.setHeader('Cache-Control', 'no-cache');
@@ -15787,7 +15840,11 @@ What would you like to discuss or change? When you're happy, say "approve" and I
 
     // Knowledge base
     { method: 'GET', path: '/assets/memory-search.js', desc: 'Serve the lazy-loaded structured memory search UI', handler: (req, res) => {
-      const content = safeRead(path.join(MINIONS_DIR, 'dashboard', 'js', 'memory-search.js'));
+      // safeReadOrNull (not safeRead): a 200 with an empty body still fires
+      // the loader's script.onload, leaving window.MinionsMemorySearch
+      // undefined so openMemorySearchModal() throws. 404 lets script.onerror
+      // surface the intended "failed to load" toast instead.
+      const content = safeReadOrNull(path.join(MINIONS_DIR, 'dashboard', 'js', 'memory-search.js'));
       if (content == null) { res.statusCode = 404; return res.end('not found'); }
       res.setHeader('Content-Type', 'application/javascript; charset=utf-8');
       res.setHeader('Cache-Control', 'no-cache');
@@ -16340,6 +16397,9 @@ function _installCrashHandlers() {
 // Production entry points use the closures directly; tests import via require('./dashboard').
 module.exports = {
   getMcpServers,
+  // W-ms5dlone012i457a-d — lets tests assert the HTML the SERVER actually ships,
+  // not just dashboard-build.js's standalone copy (the two silently drifted).
+  _buildDashboardHtmlForTest: buildDashboardHtml,
   _setPrRefVerifierForTest, // issue #246 — inject a fake loose-PR-ref verifier in handler tests
   _prRefVerifyCache,        // W-mqtzrix100060c9f — test seam for cache size inspection
   _PR_REF_VERIFY_TTL_MS,    // W-mqtzrix100060c9f — exported for test assertions
@@ -16390,6 +16450,11 @@ module.exports = {
   // P-9c5f1a83 — CC image-attachment validation surface (test seams)
   _validateCcImages,
   _buildCcErrorEnvelope,
+  // W-ms4z164i01fo438d — SSE terminal-frame seam (exported for testing).
+  // See test/unit/cc-error-envelopes.test.js.
+  _sseFrame,
+  _isTerminalSseFrameType,
+  _buildCcTerminalErrorPayload,
   CC_ERROR_CODES,
   CC_IMAGE_MAX_COUNT,
   CC_IMAGE_MAX_DECODED_BYTES,

package/engine/kb-sweep.js

@@ -27,6 +27,16 @@ const AUTO_SWEEP_INTERVAL_MS = 4 * 60 * 60 * 1000;
 const AUTO_SWEEP_FAILURE_RETRY_MS = 15 * 60 * 1000;
 const KB_SWEPT_PATH = path.join(ENGINE_DIR, 'kb-swept.json');
 const COMPRESS_THRESHOLD_BYTES = 5000;
+// Hard input ceiling for the per-entry LLM rewrite pass (W-ms25l4pr000kb9db).
+// The rewrite pass sends an entry's FULL body to the LLM; a pathological entry
+// (e.g. a live-checkout dirty alert that embedded a whole `git status` dump —
+// observed at 10 MB each) can OOM/timeout/hang the call and, without per-pass
+// isolation, abort the entire sweep before the cheap age-expiry pass reclaims
+// space. Entries whose on-disk size exceeds this ceiling are skipped from the
+// rewrite (left for age-expiry / structural consolidation to reclaim) so one
+// giant entry can never choke the sweep. 20x the compress threshold (~100 KB)
+// is far above every normal entry yet well below the multi-MB monsters.
+const REWRITE_MAX_INPUT_BYTES = COMPRESS_THRESHOLD_BYTES * 20;
 const LLM_BATCH_SIZE = 30;
 const NORMALIZE_CONCURRENCY = 5;
 const SWEPT_FLAG_KEY = '_swept'; // frontmatter key — entries with this skip the rewrite pass
@@ -610,6 +620,13 @@ ${body}`;
     const fp = path.join(KB_DIR, e.category, e.file);
     const content = safeRead(fp);
     if (content == null) continue;
+    // Oversized-entry guard (W-ms25l4pr000kb9db): never send a multi-MB entry to
+    // the LLM — it risks OOM/timeout/hang. Skip it; age-expiry / consolidation
+    // reclaim it instead.
+    if (content.length > REWRITE_MAX_INPUT_BYTES) {
+      log('warn', `[kb-sweep] rewrite skip ${e.category}/${e.file}: ${content.length} bytes exceeds ${REWRITE_MAX_INPUT_BYTES}B ceiling — left for age-expiry/consolidation`);
+      continue;
+    }
     const { fm, body } = _parseFrontmatter(content);
     // Skip already-processed unless the file was modified after the sweep flag was set
     if (fm[SWEPT_FLAG_KEY]) {
@@ -984,9 +1001,19 @@ async function _runKbSweepImpl(opts = {}) {
   }
   if (manifest.length < 2) { summary.summary = 'nothing to sweep (< 2 unpinned entries)'; summary.durationMs = Date.now() - t0; return summary; }
 
+  // Every pass below is wrapped in its own try/catch (W-ms25l4pr000kb9db). A
+  // throw/OOM/hang in one pass must NOT abort the whole sweep and starve the
+  // later reclaimers — in particular the cheap age-expiry pass and
+  // _pruneOldSwept must always get to run. Each pass degrades to "no-op on this
+  // pass, carry the prior survivors forward".
+
   // 1. Hash-based dedup (cheap, catches cross-batch duplicates)
-  const { survivors: afterHash, archived: hashArchived } = _hashDedup(manifest, opts);
-  summary.hashDuplicatesArchived = hashArchived;
+  let afterHash = manifest;
+  try {
+    const { survivors, archived } = _hashDedup(manifest, opts);
+    afterHash = survivors;
+    summary.hashDuplicatesArchived = archived;
+  } catch (e) { log('warn', `[kb-sweep] hash-dedup pass failed: ${e && e.message}`); }
 
   // 1.5. Structural consolidation (W-mr973knu) — PRIMARY balloon fix. Collapse
   // large groups of near-identical boilerplate notes (agent-failure dumps, no-op
@@ -994,47 +1021,70 @@ async function _runKbSweepImpl(opts = {}) {
   // week). Runs on recent entries too, so it shrinks the KB continuously rather
   // than merely aging files out. Downstream passes operate on the survivors so
   // the LLM/rewrite passes no longer waste calls on the collapsed notes.
-  const consolidateResult = _structuralConsolidate(afterHash, opts);
-  summary.notesConsolidated = consolidateResult.consolidated;
-  summary.consolidationGroups = consolidateResult.groupsCollapsed;
-  summary.digestsWritten = consolidateResult.digestsWritten;
-  const afterConsolidate = consolidateResult.survivors.filter(
-    e => e._digest || fs.existsSync(path.join(KB_DIR, e.category, e.file)),
-  );
-
-  // 2. LLM batch sweep — within-batch dupes + reclassify + remove stale
-  // Only runs against survivors, but we need indices that match the LIST sent to the LLM
-  const llmManifest = afterConsolidate;
-  const { plan, scannedIdx: llmScannedIdx } = await _llmBatchSweep(llmManifest, callLLM, trackEngineUsage, opts);
-  const llmActions = _applyLlmPlan(plan, llmManifest, llmScannedIdx, opts);
-  summary.llmDuplicatesArchived = llmActions.merged;
-  summary.staleRemoved = llmActions.removed;
-  summary.reclassified = llmActions.reclassified;
-
-  // 2.5. Age-based TTL expiry (W-mr48yth5) — SECONDARY safety net. Archives
-  // transient-category entries older than their per-category TTL to
-  // knowledge/_swept/. Structural consolidation above is the primary reducer;
-  // this catches genuinely stale one-offs that never clustered into a digest.
-  // Durable categories (no TTL) are untouched.
-  const survivingAfterLlm = afterConsolidate.filter(e => fs.existsSync(path.join(KB_DIR, e.category, e.file)));
-  const ageResult = _expireByAge(survivingAfterLlm, opts);
-  summary.ageExpired = ageResult.expired;
-
-  // 3. Per-entry rewrite (compress + normalize)
-  // Filter to entries that survived hash + consolidation + LLM + age passes (still on disk)
-  const stillOnDisk = afterConsolidate.filter(e => fs.existsSync(path.join(KB_DIR, e.category, e.file)));
-  const rewriteResult = await _rewritePass(stillOnDisk, callLLM, trackEngineUsage, opts);
-  summary.rewritten = rewriteResult.processed;
-  summary.rewriteBytesBefore = rewriteResult.bytesBefore;
-  summary.rewriteBytesAfter = rewriteResult.bytesAfter;
+  let afterConsolidate = afterHash;
+  try {
+    const consolidateResult = _structuralConsolidate(afterHash, opts);
+    summary.notesConsolidated = consolidateResult.consolidated;
+    summary.consolidationGroups = consolidateResult.groupsCollapsed;
+    summary.digestsWritten = consolidateResult.digestsWritten;
+    afterConsolidate = consolidateResult.survivors.filter(
+      e => e._digest || fs.existsSync(path.join(KB_DIR, e.category, e.file)),
+    );
+  } catch (e) { log('warn', `[kb-sweep] structural-consolidation pass failed: ${e && e.message}`); }
+
+  // 2. Age-based TTL expiry (W-mr48yth5) — MOVED AHEAD of the LLM passes
+  // (W-ms25l4pr000kb9db). This is the cheapest reducer AND the one that reclaims
+  // the most space from oversized transient entries, so it MUST run before the
+  // LLM batch sweep + rewrite pass — either of which can choke on a multi-MB
+  // entry. Running pure aging first guarantees stale entries are reclaimed even
+  // if a later LLM/rewrite pass throws or hangs. Archives transient-category
+  // entries older than their per-category TTL to knowledge/_swept/; durable
+  // categories (no TTL) and consolidation digests are untouched.
+  let afterAge = afterConsolidate;
+  try {
+    const survivingForAge = afterConsolidate.filter(
+      e => e._digest || fs.existsSync(path.join(KB_DIR, e.category, e.file)),
+    );
+    const ageResult = _expireByAge(survivingForAge, opts);
+    summary.ageExpired = ageResult.expired;
+    afterAge = ageResult.survivors;
+  } catch (e) { log('warn', `[kb-sweep] age-expiry pass failed: ${e && e.message}`); }
+
+  // 3. LLM batch sweep — within-batch dupes + reclassify + remove stale.
+  // Only runs against survivors, but we need indices that match the LIST sent to
+  // the LLM. Deferred LLM_SCAN_FLAG_KEY stamping (below) needs llmManifest +
+  // llmScannedIdx in scope, so declare them outside the try.
+  let llmManifest = afterAge.filter(e => e._digest || fs.existsSync(path.join(KB_DIR, e.category, e.file)));
+  let llmScannedIdx = [];
+  try {
+    const { plan, scannedIdx } = await _llmBatchSweep(llmManifest, callLLM, trackEngineUsage, opts);
+    llmScannedIdx = scannedIdx;
+    const llmActions = _applyLlmPlan(plan, llmManifest, llmScannedIdx, opts);
+    summary.llmDuplicatesArchived = llmActions.merged;
+    summary.staleRemoved = llmActions.removed;
+    summary.reclassified = llmActions.reclassified;
+  } catch (e) { log('warn', `[kb-sweep] LLM batch-sweep pass failed: ${e && e.message}`); }
+
+  // 4. Per-entry rewrite (compress + normalize). Filter to entries that survived
+  // the earlier passes (still on disk). Oversized entries are skipped inside
+  // _rewritePass (REWRITE_MAX_INPUT_BYTES) so they never choke the LLM.
+  try {
+    const stillOnDisk = afterAge.filter(e => fs.existsSync(path.join(KB_DIR, e.category, e.file)));
+    const rewriteResult = await _rewritePass(stillOnDisk, callLLM, trackEngineUsage, opts);
+    summary.rewritten = rewriteResult.processed;
+    summary.rewriteBytesBefore = rewriteResult.bytesBefore;
+    summary.rewriteBytesAfter = rewriteResult.bytesAfter;
+  } catch (e) { log('warn', `[kb-sweep] rewrite pass failed: ${e && e.message}`); }
 
   // Stamp LLM_SCAN_FLAG_KEY on entries analyzed by _llmBatchSweep this run —
   // deferred until after the rewrite pass so its content/mtime update doesn't
   // race the freshness marker we're about to write (see _markLlmScanned doc).
-  _markLlmScanned(llmManifest, llmScannedIdx, opts);
+  try { _markLlmScanned(llmManifest, llmScannedIdx, opts); }
+  catch (e) { log('warn', `[kb-sweep] mark-llm-scanned failed: ${e && e.message}`); }
 
-  // 4. Prune old swept files (>30 days)
-  summary.sweptArchivePruned = _pruneOldSwept();
+  // 5. Prune old swept files (>30 days)
+  try { summary.sweptArchivePruned = _pruneOldSwept(); }
+  catch (e) { log('warn', `[kb-sweep] prune-old-swept failed: ${e && e.message}`); }
 
   // Final tallies — re-walk surviving entries for accurate bytesAfter
   const finalEntries = await queries.getKnowledgeBaseEntries();
@@ -1318,5 +1368,7 @@ module.exports = {
   LLM_SCAN_FLAG_KEY,
   CONSOLIDATION_DIGEST_PREFIX,
   COMPRESS_THRESHOLD_BYTES,
+  REWRITE_MAX_INPUT_BYTES,
   SWEPT_FLAG_KEY,
+  _rewritePass,
 };

package/engine/live-checkout.js

@@ -287,12 +287,32 @@ function _collectAutoCleanablePaths(dirtyFiles) {
 // alert stays human-scannable and bounded. Pure/deterministic — exported for
 // unit testing.
 const DIRTY_ALERT_MAX_LINES = 200;
-function capDirtyFileLines(dirtyFiles, maxLines = DIRTY_ALERT_MAX_LINES) {
+// Companion byte budget for the embedded dirty-file block. The line cap alone
+// still leaves a hole: 200 arbitrarily-long paths (deeply-nested Windows paths,
+// rename `->` pairs, quoted UTF-8 escapes) could each be hundreds of bytes, so
+// bound the total bytes too. Belt-and-suspenders so a single alert body can
+// never embed a multi-MB git-status dump under any input. 16 KiB is far above a
+// realistic ≤200-file sample yet keeps the whole note human-scannable.
+const DIRTY_ALERT_MAX_BYTES = 16 * 1024;
+function capDirtyFileLines(dirtyFiles, maxLines = DIRTY_ALERT_MAX_LINES, maxBytes = DIRTY_ALERT_MAX_BYTES) {
   const lines = Array.isArray(dirtyFiles) ? dirtyFiles : [];
-  const cap = Number.isInteger(maxLines) && maxLines > 0 ? maxLines : DIRTY_ALERT_MAX_LINES;
-  if (lines.length <= cap) return lines.slice();
-  const kept = lines.slice(0, cap);
-  kept.push(`... and ${lines.length - cap} more (run \`git status --porcelain=v1 -b\` locally for the full list)`);
+  const lineCap = Number.isInteger(maxLines) && maxLines > 0 ? maxLines : DIRTY_ALERT_MAX_LINES;
+  const byteCap = Number.isInteger(maxBytes) && maxBytes > 0 ? maxBytes : DIRTY_ALERT_MAX_BYTES;
+  // First cap by line count, then enforce the byte budget over the kept lines
+  // (each line plus its joining newline). Either cap can trigger the notice.
+  const byLine = lines.slice(0, lineCap);
+  const kept = [];
+  let bytes = 0;
+  let byteLimited = false;
+  for (const line of byLine) {
+    const lineBytes = Buffer.byteLength(String(line), 'utf8') + 1;
+    if (bytes + lineBytes > byteCap) { byteLimited = true; break; }
+    bytes += lineBytes;
+    kept.push(line);
+  }
+  const omitted = lines.length - kept.length;
+  if (omitted <= 0 && !byteLimited) return lines.slice();
+  kept.push(`... and ${omitted} more (run \`git status --porcelain=v1 -b\` locally for the full list)`);
   return kept;
 }
 
@@ -920,6 +940,10 @@ async function prepareLiveCheckout(opts = {}) {
           if (autoResetAttempt.recheckSucceeded) {
             verifyOutcome = stillDirty.length === 0 ? 'clean' : `${stillDirty.length} dirty path(s) remain`;
           }
+          // The audit note embeds TWO dumps (before + after), so they share ONE
+          // body budget: capping each at the full DIRTY_ALERT_MAX_BYTES would let
+          // this note reach 2x the ceiling every other live-checkout alert obeys.
+          const blockMaxBytes = Math.floor(DIRTY_ALERT_MAX_BYTES / 2);
           const body = [
             `# Live-checkout auto-reset ${recoveryVerified ? 'completed' : 'incomplete'} before '${branchName}'`,
             '',
@@ -938,7 +962,7 @@ async function prepareLiveCheckout(opts = {}) {
             '## Changes present before the attempt',
             '',
             '```',
-            ...dirtyFiles,
+            ...capDirtyFileLines(dirtyFiles, DIRTY_ALERT_MAX_LINES, blockMaxBytes),
             '```',
             ...(autoResetAttempt.recheckSucceeded
               ? [
@@ -946,7 +970,9 @@ async function prepareLiveCheckout(opts = {}) {
                 '## Changes remaining after the attempt',
                 '',
                 '```',
-                ...(stillDirty.length > 0 ? stillDirty : ['(clean)']),
+                ...(stillDirty.length > 0
+                  ? capDirtyFileLines(stillDirty, DIRTY_ALERT_MAX_LINES, blockMaxBytes)
+                  : ['(clean)']),
                 '```',
               ]
               : []),
@@ -2093,5 +2119,6 @@ module.exports = {
   _maybeAutoFreshenLocalMain,
   capDirtyFileLines,
   DIRTY_ALERT_MAX_LINES,
+  DIRTY_ALERT_MAX_BYTES,
   LIVE_CHECKOUT_AUTO_CLEAN_PATTERNS,
 };

package/package.json

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

@@ -57,15 +57,15 @@ You are primarily a dispatcher. Agents have full Claude Code + worktrees + MCP t
 
 ### Step 1 — Estimate difficulty before responding
 State the size in 3-4 words to yourself, then act:
-- **Small** (≤3 tool calls, 1-2 files, no cross-module reasoning): you MAY do it yourself.
-- **Medium** (4-10 tool calls, 3+ files, multi-file reasoning, real refactor): you MUST delegate.
+- **Small** (≤3 tool calls, 1-2 files, no cross-module reasoning): you MAY do it yourself. A bounded read-only lookup or investigation may also be handled directly even when confirming the answer takes a few additional `GET`, search, or file-read calls.
+- **Medium** (4-10 tool calls for mutating/open-ended work, 3+ files, multi-file reasoning, or a real refactor; excludes bounded read-only confirmation): you MUST delegate.
 - **Large** (10+ tool calls, cross-cutting, multi-stage): you MUST delegate, consider a plan with decomposition.
 - **Direct-handling override**: if the human explicitly says to answer directly, handle it here, do it yourself, not dispatch/delegate, or not create a work item, do it yourself within the normal safety/protected-path rules.
 
 ### Step 2 — Delegate when ≥ Medium (the hard stop)
 Always delegate these to an agent — do not attempt them yourself even if they look small at first:
 - Code changes, fixes, refactors, new features → `POST /api/work-items` with `type: "implement"` (use `"fix"` only when the work targets a specific tracked PR — see the type-selection note under "Calling the Minions API" below)
-- Exploration, investigation, research, audits → `POST /api/work-items` with `type: "explore"`
+- Substantial exploration, investigation, research, or audits that require broad repository traversal, prolonged execution, or durable follow-up → `POST /api/work-items` with `type: "explore"`
 - Code reviews → `POST /api/work-items` with `type: "review"`
 - Testing → `POST /api/work-items` with `type: "test"`
 - Architecture analysis → `POST /api/work-items` with `type: "explore"`
@@ -79,15 +79,16 @@ Exception: the direct-handling override wins. If the human explicitly asks you t
 ### Step 3 — Small tasks: do them yourself when it's faster than dispatching
 Examples (not an exhaustive whitelist — apply Step 1 to anything not listed):
 - Quick status lookups (reading 1-2 state files, or a `GET /api/...`)
+- Basic read-only investigations with a bounded question and locally available evidence, including checking several related logs, API records, or source locations to identify a concrete cause
 - Notes, plan edits, KB entries, routing updates
 - Git ops the user explicitly asked CC to do
 - Simple config changes
 - Answering questions from context you already have
 - One-line edits to non-protected files when the change is unambiguous
 
-If you start a small task and discover it's actually Medium (3+ files, more tool calls than expected, surprising complexity), STOP and delegate instead of pushing through.
+If you start a small task and discover it needs broad cross-module reasoning, long-running commands, code changes, or durable follow-up, STOP and delegate instead of pushing through. Do not delegate a bounded read-only investigation solely because confirming the answer took more than three tool calls.
 
-When genuinely in doubt about the size, delegate — agents have isolated worktrees, full tool access, durable work-item tracking, and no turn limits.
+When genuinely in doubt about a mutating or open-ended task, delegate — agents have isolated worktrees, full tool access, durable work-item tracking, and no turn limits. For a bounded read-only question, prefer answering directly when the evidence is available locally.
 
 ### Operator checkouts — write only on an explicit user request
 A configured project's `localPath` is the **human operator's own working tree**. You MAY use `Edit`/`Write`/`Bash` to change files and run mutating git commands inside `localPath` — but only as the operator's hands, carrying out a change **they explicitly asked you to make in that checkout**. This includes ordinary requested git operations (e.g. a clean `git pull --ff-only origin main`, `git checkout -- <file>` on a file they named) and requested file edits.
@@ -115,8 +116,8 @@ Pass `"contextOnly":true` if the PR should be tracked-but-not-auto-reviewed; omi
 
 ## When to dispatch vs answer inline
 
-- **Action requests** (fix this, implement that, build X, run a build, investigate Y, review PR #N) → dispatch via `POST /api/work-items` (or one of the other state-changing endpoints below). Don't also try to do the work yourself in the chat unless it's truly Small per Step 1.
-- **Information requests** that you can fetch and synthesize yourself (PR counts, schedule status, "what's in routing.md", "are there any open work items") → answer inline. Use `GET /api/...` or read the state files directly. **Don't also dispatch an `ask` work item for the same answered question** — that's the W-moyo53f9 regression class. If you answered it, don't fire-and-forget a duplicate.
+- **Action requests** (fix this, implement that, build X, run a build, perform a substantial/open-ended investigation, review PR #N) → dispatch via `POST /api/work-items` (or one of the other state-changing endpoints below). Don't also try to do the work yourself in the chat unless it's truly Small per Step 1.
+- **Information and bounded read-only investigation requests** that you can fetch and synthesize yourself (PR counts, schedule status, "what's in routing.md", "why did these recent jobs fail?", "are there any open work items") → answer inline. Use `GET /api/...`, local searches, logs, or read-only file inspection. **Don't also dispatch an `ask` or `explore` work item for the same answered question** — that's the W-moyo53f9 regression class. If you answered it, don't fire-and-forget a duplicate.
 - **Never both** for the same request. Pick one.
 - **The server no longer second-guesses your choice.** There is no inferred-fallback safety net (`_actionsWithIntentFallback` and the heuristic stack were removed). Whatever you POST is what ships; whatever you don't POST doesn't ship. Be deliberate.