@yemi33/minions 0.1.2212 → 0.1.2213

package/dashboard/js/command-center.js

@@ -17,6 +17,158 @@ var _ccSending = false; // true if active tab is sending (UI indicator only)
 // Clear stale sending state on page load — SSE streams don't survive refresh
 try { localStorage.removeItem('cc-sending'); } catch {}
 
+// ── P-2a6d8e74 — Image attachments (paste / drag-drop) ──────────────────────
+// Pending images for the NEXT CC turn. Each entry: { mimeType, dataBase64,
+// filename, dataUrl }. dataBase64 is the raw (prefix-stripped) base64 sent to
+// the server; dataUrl (full data: URI) is for the local thumbnail only.
+// Cleared after every dispatch (v1 sends images for the current turn only).
+var _ccAttachments = [];
+// Client-side limits MIRROR the server (dashboard.js _validateCcImages) — they
+// are UX-only pre-screening; the server remains the single trust boundary.
+var CC_IMG_MAX_COUNT = 4;
+var CC_IMG_MAX_BYTES = 5 * 1024 * 1024; // 5 MB decoded, per image
+var CC_IMG_MIME_ALLOW = ['image/png', 'image/jpeg', 'image/gif', 'image/webp'];
+
+// Read one File/Blob into the attachment shape. Resolves { error } on a
+// client-side limit miss so the caller can toast and skip it.
+function _ccReadImageFile(file) {
+  return new Promise(function(resolve) {
+    var mime = String(file && file.type || '').toLowerCase();
+    if (CC_IMG_MIME_ALLOW.indexOf(mime) === -1) { resolve({ error: 'Unsupported image type' + (mime ? ': ' + mime : '') }); return; }
+    if (file.size > CC_IMG_MAX_BYTES) { resolve({ error: (file.name || 'image') + ' is too large (max 5 MB)' }); return; }
+    var reader = new FileReader();
+    reader.onload = function() {
+      var result = String(reader.result || '');
+      var comma = result.indexOf(',');
+      var dataBase64 = comma >= 0 ? result.slice(comma + 1) : '';
+      if (!dataBase64) { resolve({ error: 'Could not read image data' }); return; }
+      resolve({ mimeType: mime, dataBase64: dataBase64, filename: file.name || 'pasted-image.png', dataUrl: result });
+    };
+    reader.onerror = function() { resolve({ error: 'Could not read ' + (file.name || 'image') }); };
+    reader.readAsDataURL(file);
+  });
+}
+
+// Add image files (from paste, drop, or the command bar). Non-images are
+// ignored; over-limit / oversized files are toasted and skipped. Exposed so
+// command-input.js can forward clipboard images into the CC drawer.
+async function ccAddImageFiles(fileList) {
+  var files = [];
+  for (var i = 0; i < (fileList ? fileList.length : 0); i++) {
+    var f = fileList[i];
+    if (f && String(f.type || '').indexOf('image/') === 0) files.push(f);
+  }
+  if (!files.length) return false;
+  var added = 0;
+  for (var j = 0; j < files.length; j++) {
+    if (_ccAttachments.length >= CC_IMG_MAX_COUNT) { showToast('cmd-toast', 'Max ' + CC_IMG_MAX_COUNT + ' images per message', false); break; }
+    var res = await _ccReadImageFile(files[j]);
+    if (res.error) { showToast('cmd-toast', res.error, false); continue; }
+    _ccAttachments.push(res);
+    added++;
+  }
+  if (added) _ccRenderAttachments();
+  return added > 0;
+}
+
+function ccRemoveAttachment(idx) {
+  if (idx >= 0 && idx < _ccAttachments.length) { _ccAttachments.splice(idx, 1); _ccRenderAttachments(); }
+}
+
+function _ccClearAttachments() {
+  if (!_ccAttachments.length) return;
+  _ccAttachments = [];
+  _ccRenderAttachments();
+}
+
+// Render the thumbnail chips above the input. Built with createElement +
+// textContent / .src (no innerHTML) so untrusted filenames and base64 data
+// can never become an XSS sink and the no-unsanitized lint gate stays clean.
+function _ccRenderAttachments() {
+  var box = document.getElementById('cc-attachments');
+  if (!box) return;
+  box.textContent = '';
+  if (!_ccAttachments.length) { box.style.display = 'none'; return; }
+  box.style.display = 'flex';
+  _ccAttachments.forEach(function(att, i) {
+    var chip = document.createElement('div');
+    chip.className = 'cc-attach-chip';
+    var img = document.createElement('img');
+    img.className = 'cc-attach-thumb';
+    img.src = att.dataUrl;
+    img.alt = att.filename;
+    var name = document.createElement('span');
+    name.className = 'cc-attach-name';
+    name.textContent = att.filename;
+    name.title = att.filename;
+    var rm = document.createElement('button');
+    rm.className = 'cc-attach-remove';
+    rm.type = 'button';
+    rm.title = 'Remove';
+    rm.textContent = '×';
+    rm.onclick = function() { ccRemoveAttachment(i); };
+    chip.appendChild(img);
+    chip.appendChild(name);
+    chip.appendChild(rm);
+    box.appendChild(chip);
+  });
+}
+
+// Snapshot the pending attachments as the server payload shape
+// ([{ mimeType, dataBase64, filename }] — no local-only dataUrl).
+function _ccImagesPayload() {
+  return _ccAttachments.map(function(a) { return { mimeType: a.mimeType, dataBase64: a.dataBase64, filename: a.filename }; });
+}
+
+// Small "📎 N image(s) attached" note appended to the user bubble so a sent
+// turn visibly records its attachments. n is a number — safe to interpolate.
+function _ccAttachmentBadge(n) {
+  if (!n) return '';
+  return '<div class="cc-msg-attach-note">📎 ' + n + ' image' + (n === 1 ? '' : 's') + ' attached</div>';
+}
+
+// Inline event handlers wired from layout.html. Paste intercepts image
+// clipboard items (and lets normal text paste through); drag/drop accepts
+// image files dropped anywhere on the drawer.
+function ccHandlePaste(e) {
+  var items = (e.clipboardData && e.clipboardData.items) || [];
+  var imgs = [];
+  for (var i = 0; i < items.length; i++) {
+    if (items[i] && items[i].kind === 'file' && String(items[i].type || '').indexOf('image/') === 0) {
+      var f = items[i].getAsFile();
+      if (f) imgs.push(f);
+    }
+  }
+  if (!imgs.length) return; // no image — allow the default text paste
+  e.preventDefault();
+  ccAddImageFiles(imgs);
+}
+
+function ccHandleDragOver(e) {
+  var types = (e.dataTransfer && e.dataTransfer.types) || [];
+  if (Array.prototype.indexOf.call(types, 'Files') === -1) return;
+  e.preventDefault();
+  if (e.dataTransfer) e.dataTransfer.dropEffect = 'copy';
+  var dz = document.getElementById('cc-drawer');
+  if (dz) dz.classList.add('cc-dragover');
+}
+
+function ccHandleDragLeave() {
+  var dz = document.getElementById('cc-drawer');
+  if (dz) dz.classList.remove('cc-dragover');
+}
+
+function ccHandleDrop(e) {
+  var dz = document.getElementById('cc-drawer');
+  if (dz) dz.classList.remove('cc-dragover');
+  var files = (e.dataTransfer && e.dataTransfer.files) || [];
+  var hasImage = false;
+  for (var i = 0; i < files.length; i++) { if (String(files[i].type || '').indexOf('image/') === 0) { hasImage = true; break; } }
+  if (!hasImage) return; // let non-image drops fall through
+  e.preventDefault();
+  ccAddImageFiles(files);
+}
+
 function _ccStripActionBlockFromText(value) {
   var text = value || '';
   if (!text) return text;
@@ -947,6 +1099,11 @@ async function _ccDoSend(message, skipUserMsg, forceTabId, intentMetadata) {
   var activeTabId = forceTabId || _ccActiveTabId;
   var activeTab = _ccTabs.find(function(t) { return t.id === activeTabId; }) || _ccActiveTab();
   if (!activeTab) return;
+  // P-2a6d8e74 — snapshot + clear pending image attachments for this turn.
+  // Only fresh user sends carry images (retries/programmatic sends set
+  // skipUserMsg and reuse the already-dispatched text). v1 = current turn only.
+  var sendImages = (!skipUserMsg && _ccAttachments.length) ? _ccImagesPayload() : [];
+  if (sendImages.length) _ccClearAttachments();
   activeTab._sending = true;
   activeTab._sendStartedAt = Date.now();
   activeTab._abortController = new AbortController();
@@ -959,7 +1116,7 @@ async function _ccDoSend(message, skipUserMsg, forceTabId, intentMetadata) {
   // Scoped helper — always targets the originating tab, even if user switches tabs
   function addMsg(role, html, skipSave, meta) { ccAddMessage(role, html, skipSave, activeTabId, meta); }
 
-  if (!skipUserMsg) addMsg('user', escHtml(message));
+  if (!skipUserMsg) addMsg('user', escHtml(message) + _ccAttachmentBadge(sendImages.length));
 
   // Remove queue indicator before processing (it'll be re-added if more queued)
   var existingQueueEl = document.getElementById('cc-queue-indicator');
@@ -1067,7 +1224,7 @@ async function _ccDoSend(message, skipUserMsg, forceTabId, intentMetadata) {
       if (!isReconnect && res.status === 429 && (!activeTab._429retries || activeTab._429retries < 3)) {
         activeTab._429retries = (activeTab._429retries || 0) + 1;
         await new Promise(function(r) { setTimeout(r, 1500); });
-        return await _ccConsumeStream({ message: message, tabId: activeTabId, sessionId: activeTab.sessionId || null, transcript: _ccBuildTranscript(activeTab), intentMetadata: intentMetadata || null }, false);
+        return await _ccConsumeStream({ message: message, tabId: activeTabId, sessionId: activeTab.sessionId || null, images: sendImages.length ? sendImages : undefined, transcript: _ccBuildTranscript(activeTab), intentMetadata: intentMetadata || null }, false);
       }
       activeTab._429retries = 0;
       var errText = await res.text();
@@ -1263,7 +1420,7 @@ async function _ccDoSend(message, skipUserMsg, forceTabId, intentMetadata) {
     while (true) {
       var consume = await _ccConsumeStream(
         reconnectAttempts === 0
-          ? { message: message, tabId: activeTabId, sessionId: activeTab.sessionId || null, transcript: _ccBuildTranscript(activeTab), intentMetadata: intentMetadata || null }
+          ? { message: message, tabId: activeTabId, sessionId: activeTab.sessionId || null, transcript: _ccBuildTranscript(activeTab), intentMetadata: intentMetadata || null, images: sendImages.length ? sendImages : undefined }
           : { tabId: activeTabId, sessionId: activeTab.sessionId || null, reconnect: true },
         reconnectAttempts > 0
       );
@@ -2193,4 +2350,4 @@ if (document.readyState === 'loading') {
   ccInitResize();
 }
 
-window.MinionsCC = { toggleCommandCenter, ccNewSession, ccNewTab, ccSwitchTab, ccCloseTab, ccRenderTabBar, ccRestoreMessages, ccSaveState, ccUpdateSessionIndicator, ccAddMessage, ccSend, ccAbort, ccExecuteAction, ccPrActionFollowup };
+window.MinionsCC = { toggleCommandCenter, ccNewSession, ccNewTab, ccSwitchTab, ccCloseTab, ccRenderTabBar, ccRestoreMessages, ccSaveState, ccUpdateSessionIndicator, ccAddMessage, ccSend, ccAbort, ccExecuteAction, ccPrActionFollowup, ccAddImageFiles, ccRemoveAttachment, ccHandlePaste, ccHandleDragOver, ccHandleDragLeave, ccHandleDrop };

package/dashboard/js/command-input.js

@@ -146,6 +146,26 @@ async function cmdSubmit() {
   return;
 }
 
+// P-2a6d8e74 — paste a screenshot into the top command bar: open the Command
+// Center drawer and forward the clipboard images into its attachment tray.
+// Non-image pastes fall through to the default textarea behavior.
+function cmdHandlePaste(e) {
+  const items = (e.clipboardData && e.clipboardData.items) || [];
+  const imgs = [];
+  for (let i = 0; i < items.length; i++) {
+    if (items[i] && items[i].kind === 'file' && String(items[i].type || '').indexOf('image/') === 0) {
+      const f = items[i].getAsFile();
+      if (f) imgs.push(f);
+    }
+  }
+  if (!imgs.length) return; // text paste — leave it to the textarea
+  e.preventDefault();
+  if (!_ccOpen) toggleCommandCenter();
+  if (window.MinionsCC && typeof window.MinionsCC.ccAddImageFiles === 'function') {
+    window.MinionsCC.ccAddImageFiles(imgs);
+  }
+}
+
 // Render the parsed meta chips below input
 function cmdRenderMeta() {
   const el = document.getElementById('cmd-meta');
@@ -272,4 +292,4 @@ function cmdInsertPopupItem(id) {
   cmdRenderMeta();
 }
 
-window.MinionsCmdInput = { cmdAutoResize, cmdUpdateHighlight, syncHighlightScroll, cmdInputChanged, cmdKeyDown, cmdSubmit, cmdRenderMeta, cmdShowMentions, cmdShowProjects, cmdHidePopup, cmdInsertPopupItem };
+window.MinionsCmdInput = { cmdAutoResize, cmdUpdateHighlight, syncHighlightScroll, cmdInputChanged, cmdKeyDown, cmdSubmit, cmdRenderMeta, cmdShowMentions, cmdShowProjects, cmdHidePopup, cmdInsertPopupItem, cmdHandlePaste };

package/dashboard/js/render-work-items.js

@@ -699,6 +699,9 @@ function _wiRenderDetail(item) {
       return ' <span class="pr-badge needs-attention" style="font-size:var(--text-xs);margin-left:4px" title="See &quot;Why this is blocked&quot; below">&#x26A0; Needs attention</span>';
     })() +
     '</div>';
+  // Work item id — shown in the modal body (not just the title) so operators can
+  // read/copy the canonical id (W-… or sched-…) when deeplinking in from a note.
+  html += field('ID', '<code style="font-size:var(--text-sm);background:var(--surface2);padding:2px 6px;border-radius:var(--radius-sm)">' + escapeHtml(item.id || '—') + '</code>');
   // W-mq08kuog001110a6 — "Why this is blocked" section, rendered FIRST so the
   // human eye lands on the unblocking reason before scrolling through agent,
   // source, dates, etc. _preDispatchEval reasons are evaluator prose and can
@@ -1073,6 +1076,12 @@ function openInboxNote(filename) {
       titleEl.textContent = filename + ' (archived)';
       // eslint-disable-next-line no-unsanitized/property -- reason: renderMd() escapes note content before assembling HTML; filename is set via textContent
       bodyEl.innerHTML = '<div style="font-size:var(--text-md);line-height:1.7;color:var(--muted)">' + renderMd(content) + '</div>';
+      // Wire Doc Chat for the deeplinked archive note, mirroring the live-inbox
+      // openModal() path (render-prs.js). Without this the archive branch opened
+      // the note as plain text with no Q&A panel, so deeplinking into a note
+      // from a (completed) work item sometimes silently dropped doc-chat.
+      _modalDocContext = { title: filename + ' (archived)', content: content, selection: '' };
+      _modalFilePath = 'notes/archive/' + filename; showModalQa();
       document.getElementById('modal').classList.add('open');
       // P-34fa5d79 — Source-WI chip for archive notes. Same convention as the
       // live-inbox branch above; parsed off the freshly-fetched content.

package/dashboard/layout.html

@@ -44,7 +44,7 @@
 
 <!-- Command Center Drawer -->
 <div id="cc-overlay" style="display:none;position:fixed;inset:0;background:rgba(0,0,0,0.4);z-index:340" onclick="toggleCommandCenter()"></div>
-<div id="cc-drawer" style="display:none;position:fixed;top:0;right:0;bottom:0;width:420px;background:var(--surface);border-left:1px solid var(--border);z-index:350;flex-direction:column;overscroll-behavior:contain">
+<div id="cc-drawer" style="display:none;position:fixed;top:0;right:0;bottom:0;width:420px;background:var(--surface);border-left:1px solid var(--border);z-index:350;flex-direction:column;overscroll-behavior:contain" ondragover="ccHandleDragOver(event)" ondragleave="ccHandleDragLeave(event)" ondrop="ccHandleDrop(event)">
   <div id="cc-resize-handle" class="cc-resize-handle"></div>
   <div style="padding:12px 16px;border-bottom:1px solid var(--border);display:flex;align-items:center;justify-content:space-between">
     <div style="display:flex;align-items:center;gap:8px">
@@ -59,11 +59,13 @@
   <div id="cc-tab-bar" style="display:flex;gap:8px;padding:4px 12px;border-bottom:1px solid var(--border);overflow:hidden;align-items:center;flex-shrink:0"></div>
   <div id="cc-messages" style="flex:1;overflow-y:auto;padding:12px 16px;display:flex;flex-direction:column;gap:10px"></div>
   <div style="padding:12px 16px;border-top:1px solid var(--border)">
+    <!-- P-2a6d8e74 — image attachment thumbnail chips (paste / drag-drop); hidden until images are attached -->
+    <div id="cc-attachments" style="display:none;flex-wrap:wrap;gap:6px;margin-bottom:8px"></div>
     <div style="display:flex;gap:8px">
-      <textarea id="cc-input" rows="2" placeholder="Ask anything or give a command..." style="flex:1;padding:8px 10px;background:var(--bg);border:1px solid var(--border);border-radius:6px;color:var(--text);font-size:var(--text-md);resize:none;font-family:inherit" onkeydown="if(event.key==='Enter'&&!event.shiftKey){event.preventDefault();ccSend()}"></textarea>
+      <textarea id="cc-input" rows="2" placeholder="Ask anything or give a command... (paste or drop an image)" style="flex:1;padding:8px 10px;background:var(--bg);border:1px solid var(--border);border-radius:6px;color:var(--text);font-size:var(--text-md);resize:none;font-family:inherit" onpaste="ccHandlePaste(event)" onkeydown="if(event.key==='Enter'&&!event.shiftKey){event.preventDefault();ccSend()}"></textarea>
       <button onclick="ccSend()" style="background:var(--blue);color:#fff;border:none;border-radius:6px;padding:8px 14px;font-size:var(--text-md);font-weight:600;cursor:pointer;align-self:flex-end">Send</button>
     </div>
-    <div id="cc-powered-by" style="font-size:var(--text-xs);color:var(--muted);margin-top:4px">Full minions context. Enter to send, Shift+Enter for newline.</div>
+    <div id="cc-powered-by" style="font-size:var(--text-xs);color:var(--muted);margin-top:4px">Full minions context. Enter to send, Shift+Enter for newline. Paste or drop images to attach.</div>
   </div>
 </div>
 

package/dashboard/pages/home.html

@@ -3,7 +3,7 @@
         <div class="cmd-input-wrap" id="cmd-input-wrap">
           <div class="cmd-highlight-layer" id="cmd-highlight" aria-hidden="true"></div>
           <textarea id="cmd-input" rows="1" placeholder='What do you need? e.g. "Fix the auth bug @dallas", "explain the dispatch flow", or "/note always use feature flags"'
-            oninput="cmdInputChanged()" onkeydown="cmdKeyDown(event)" onscroll="syncHighlightScroll()"></textarea>
+            oninput="cmdInputChanged()" onkeydown="cmdKeyDown(event)" onscroll="syncHighlightScroll()" onpaste="cmdHandlePaste(event)"></textarea>
           <button class="cmd-send-btn" id="cmd-send-btn" onclick="cmdSubmit()">Send <kbd>Ctrl+Enter</kbd></button>
         </div>
         <div class="cmd-mention-popup" id="cmd-mention-popup"></div>

package/dashboard/styles.css

@@ -1146,6 +1146,20 @@
   .cc-resize-handle:hover::after, .cc-resize-handle.active::after { opacity: 1; background: var(--blue); }
   body.cc-resizing { cursor: col-resize !important; user-select: none !important; }
 
+  /* ── P-2a6d8e74 — CC image attachment chips + drag-drop affordance ───── */
+  #cc-drawer.cc-dragover { outline: 2px dashed var(--blue); outline-offset: -2px; }
+  .cc-attach-chip { display: inline-flex; align-items: center; gap: 6px; max-width: 180px;
+    padding: 4px 6px; background: var(--surface2); border: 1px solid var(--border);
+    border-radius: var(--radius-sm); font-size: var(--text-xs); }
+  .cc-attach-thumb { width: 28px; height: 28px; object-fit: cover; border-radius: 3px;
+    flex-shrink: 0; background: var(--bg); }
+  .cc-attach-name { color: var(--muted); white-space: nowrap; overflow: hidden;
+    text-overflow: ellipsis; }
+  .cc-attach-remove { flex-shrink: 0; background: none; border: none; color: var(--muted);
+    cursor: pointer; font-size: var(--text-md); line-height: 1; padding: 0 2px; }
+  .cc-attach-remove:hover { color: var(--red); }
+  .cc-msg-attach-note { margin-top: 4px; font-size: var(--text-xs); opacity: 0.85; }
+
   .modal-body { padding: var(--space-7) var(--space-8); overflow-y: auto; overflow-x: auto; white-space: pre-wrap; font-size: var(--text-md); line-height: 1.7; color: var(--muted); font-family: Consolas, monospace; }
 
   /* ── Settings: left-rail tabbed layout (W-mpmwxkcn000646cc) ─────────────

package/dashboard.js

@@ -719,14 +719,6 @@ function createWorkItemWithDedup(wiPath, item, options = {}) {
   return result || { created: false, item: null };
 }
 
-function formatUnknownProjectError(projectName, projects = []) {
-  return shared.formatUnknownProjectError(projectName, projects);
-}
-
-function findProjectByName(projects, projectName) {
-  return shared.findProjectByName(projects, projectName);
-}
-
 function resolveManualPrLinkProject(url, projectName, projects = PROJECTS) {
   const explicitProjectName = String(projectName || '').trim();
   if (explicitProjectName) {
@@ -1815,7 +1807,6 @@ function getVerifyGuides() {
   return guides;
 }
 
-function getArchivedPrds() { return []; }
 function getEngineState() { return queries.getControl(); }
 
 let _worktreeCountCache = 0;
@@ -3111,6 +3102,10 @@ const CC_ERROR_CODES = Object.freeze([
   'worker-spawn-failed',
   'acp-handshake-failed',
   'worker-died',
+  // P-9c5f1a83 — server-side image-attachment validation rejection. Every
+  // images[] violation (too many / too large / bad mime / malformed base64)
+  // surfaces this typed code via _buildCcErrorEnvelope, never a 500.
+  'invalid-image',
 ]);
 function _buildCcErrorEnvelope({ message, code, retryable, ...extra } = {}) {
   const normalizedCode = CC_ERROR_CODES.includes(code) ? code : 'crash';
@@ -3122,6 +3117,99 @@ function _buildCcErrorEnvelope({ message, code, retryable, ...extra } = {}) {
     ...extra,
   };
 }
+
+// ── P-9c5f1a83 — Command Center image-attachment server-side validation ──
+// ALL limits are enforced here, never trusting the client. The frontend
+// (P-2a6d8e74) may pre-screen for UX, but this is the only trust boundary.
+// Contract matches the spike decision (knowledge/conventions/…cli-image-input…):
+// the adapter `images` opt is `[{ mimeType, dataBase64 }]` and only the Claude
+// runtime accepts it (capability-gated downstream in engine/llm.js).
+const CC_IMAGE_MAX_COUNT = 4;
+const CC_IMAGE_MAX_DECODED_BYTES = 5 * 1024 * 1024; // 5 MB decoded, per image
+const CC_IMAGE_MIME_ALLOWLIST = Object.freeze(['image/png', 'image/jpeg', 'image/gif', 'image/webp']);
+
+// Max request-body size (bytes ≈ chars) for the image-accepting CC endpoints.
+// readBody's default 1 MB cap is far below a legitimate image turn: the
+// documented per-image limit is 5 MB decoded and up to 4 images, so a maxed
+// turn is ~20 MB decoded which base64-encodes to ~27 MB. Without a raised cap
+// readBody rejected the body as "too large" BEFORE _validateCcImages ever ran,
+// making the 5 MB-per-image limit unreachable (any image over ~740 KB tripped
+// the 1 MB cap) and surfacing a generic 500 instead of the typed envelope.
+// Sized to the worst case plus ~2 MB headroom for the JSON envelope + message
+// text. Non-image endpoints keep readBody's conservative 1 MB default.
+const CC_IMAGE_REQUEST_MAX_BYTES =
+  Math.ceil((CC_IMAGE_MAX_COUNT * CC_IMAGE_MAX_DECODED_BYTES * 4) / 3) + (2 * 1024 * 1024);
+
+function _ccImageRejection(message) {
+  return _buildCcErrorEnvelope({ message, code: 'invalid-image', retryable: false });
+}
+
+// Map readBody's payload-too-large rejection (body exceeded
+// CC_IMAGE_REQUEST_MAX_BYTES) onto the documented typed 'invalid-image'
+// envelope, so an over-budget image turn surfaces the same red error bubble
+// (4xx) as every other image rejection instead of a generic 500 crash.
+function _ccPayloadTooLargeRejection() {
+  const mb = Math.round(CC_IMAGE_MAX_DECODED_BYTES / (1024 * 1024));
+  return _ccImageRejection(`Request too large — reduce image size or count (max ${CC_IMAGE_MAX_COUNT} images, ${mb} MB each).`);
+}
+
+// Returns { images, error }:
+//   - absent / empty        → { images: undefined, error: null }  (text-only, today's behavior)
+//   - all valid             → { images: [{ mimeType, dataBase64, filename? }], error: null }
+//   - any violation         → { images: undefined, error: <typed envelope, code:'invalid-image'> }
+// Uses only Node's built-in Buffer for base64 decode (zero-dep invariant).
+function _validateCcImages(images) {
+  if (images == null) return { images: undefined, error: null };
+  if (!Array.isArray(images)) {
+    return { images: undefined, error: _ccImageRejection('images must be an array of { mimeType, dataBase64 }') };
+  }
+  if (images.length === 0) return { images: undefined, error: null };
+  if (images.length > CC_IMAGE_MAX_COUNT) {
+    return { images: undefined, error: _ccImageRejection(`Too many images: ${images.length} (max ${CC_IMAGE_MAX_COUNT})`) };
+  }
+  const normalized = [];
+  for (let i = 0; i < images.length; i += 1) {
+    const label = `Image ${i + 1}`;
+    const img = images[i];
+    if (!img || typeof img !== 'object' || Array.isArray(img)) {
+      return { images: undefined, error: _ccImageRejection(`${label} is not an object`) };
+    }
+    const mimeType = typeof img.mimeType === 'string' ? img.mimeType.toLowerCase().trim() : '';
+    if (!CC_IMAGE_MIME_ALLOWLIST.includes(mimeType)) {
+      return { images: undefined, error: _ccImageRejection(`${label} has unsupported mime type ${JSON.stringify(img.mimeType)} (allowed: ${CC_IMAGE_MIME_ALLOWLIST.join(', ')})`) };
+    }
+    if (typeof img.dataBase64 !== 'string' || img.dataBase64.length === 0) {
+      return { images: undefined, error: _ccImageRejection(`${label} is missing dataBase64`) };
+    }
+    // Defensively strip an optional data: URI prefix and any whitespace before
+    // validating — canvas.toDataURL() yields a clean payload, but a forgiving
+    // strip keeps a stray prefix from being mis-flagged as malformed.
+    const raw = img.dataBase64.replace(/^data:[^;,]*;base64,/i, '').replace(/\s+/g, '');
+    // Buffer.from(..., 'base64') is lenient (silently drops invalid chars), so
+    // validate the charset ourselves first — a malformed payload must be
+    // rejected, not silently truncated.
+    if (!/^[A-Za-z0-9+/]*={0,2}$/.test(raw)) {
+      return { images: undefined, error: _ccImageRejection(`${label} has malformed base64 data`) };
+    }
+    let decoded;
+    try { decoded = Buffer.from(raw, 'base64'); }
+    catch { return { images: undefined, error: _ccImageRejection(`${label} has malformed base64 data`) }; }
+    // Canonical round-trip: re-encoding the decoded bytes must reproduce the
+    // input (ignoring padding). This catches non-base64 junk that the charset
+    // regex let through (e.g. a length that isn't a valid base64 quantum).
+    const canon = (s) => s.replace(/=+$/, '');
+    if (decoded.length === 0 || canon(decoded.toString('base64')) !== canon(raw)) {
+      return { images: undefined, error: _ccImageRejection(`${label} has malformed base64 data`) };
+    }
+    if (decoded.length > CC_IMAGE_MAX_DECODED_BYTES) {
+      return { images: undefined, error: _ccImageRejection(`${label} is too large: ${decoded.length} bytes decoded (max ${CC_IMAGE_MAX_DECODED_BYTES})`) };
+    }
+    const entry = { mimeType, dataBase64: raw };
+    if (typeof img.filename === 'string' && img.filename) entry.filename = img.filename;
+    normalized.push(entry);
+  }
+  return { images: normalized, error: null };
+}
 function _releaseCCTab(tabId) { ccInFlightTabs.delete(tabId); ccInFlightAborts.delete(tabId); }
 function _getCcLiveStream(tabId) {
   return ccLiveStreams.get(tabId) || null;
@@ -4349,7 +4437,7 @@ function _invokeDocChatViaPool({ prompt, model, effort, engineConfig, systemProm
  *   conversation for the same file. The legacy direct path is unaffected — freshSession
  *   semantics there are owned by ccDocCall, which deletes docSessions before invoking.
  */
-async function ccCall(message, { store = 'cc', sessionKey, extraContext, label = 'command-center', timeout = CC_CALL_TIMEOUT_MS, maxTurns, allowedTools = 'Bash,Read,Write,Edit,Glob,Grep,WebFetch,WebSearch', skipStatePreamble = false, skipPreflight = false, model, onAbortReady, systemPrompt = CC_STATIC_SYSTEM_PROMPT, transcript, turnId, freshSession = false } = {}) {
+async function ccCall(message, { store = 'cc', sessionKey, extraContext, label = 'command-center', timeout = CC_CALL_TIMEOUT_MS, maxTurns, allowedTools = 'Bash,Read,Write,Edit,Glob,Grep,WebFetch,WebSearch', skipStatePreamble = false, skipPreflight = false, model, onAbortReady, systemPrompt = CC_STATIC_SYSTEM_PROMPT, transcript, turnId, freshSession = false, images } = {}) {
   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;
@@ -4433,7 +4521,7 @@ async function ccCall(message, { store = 'cc', sessionKey, extraContext, label =
       outOfBandOnly: !resumeNeedsCarryover,
     }), '', {
       timeout, label, model, maxTurns, allowedTools, sessionId, effort: ccEffort, direct: true,
-      engineConfig: CONFIG.engine,
+      engineConfig: CONFIG.engine, images,
     });
     if (onAbortReady) onAbortReady(p1.abort);
     result = await p1;
@@ -4471,7 +4559,7 @@ async function ccCall(message, { store = 'cc', sessionKey, extraContext, label =
   const freshPrompt = buildPrompt({ includeCarryover: freshNeedsCarryover });
   const p2 = llm.callLLM(freshPrompt, systemPrompt, {
     timeout, label, model, maxTurns, allowedTools, effort: ccEffort, direct: true,
-    engineConfig: CONFIG.engine,
+    engineConfig: CONFIG.engine, images,
   });
   if (onAbortReady) onAbortReady(p2.abort);
   result = await p2;
@@ -4489,7 +4577,7 @@ async function ccCall(message, { store = 'cc', sessionKey, extraContext, label =
   await new Promise(r => setTimeout(r, 2000));
   const p3 = llm.callLLM(freshPrompt, systemPrompt, {
     timeout, label, model, maxTurns, allowedTools, effort: ccEffort, direct: true,
-    engineConfig: CONFIG.engine,
+    engineConfig: CONFIG.engine, images,
   });
   if (onAbortReady) onAbortReady(p3.abort);
   result = await p3;
@@ -5245,7 +5333,12 @@ async function ccDocCallStreaming({ message, document, title, filePath, selectio
 
 // -- POST helpers --
 
-function readBody(req) {
+function readBody(req, opts) {
+  // Per-endpoint body-size cap. Defaults to 1 MB (the conservative OOM guard
+  // for every JSON endpoint); the image-accepting CC endpoints pass a larger
+  // CC_IMAGE_REQUEST_MAX_BYTES so a legitimate paste-screenshot turn reaches
+  // _validateCcImages instead of being rejected here first.
+  const maxBytes = (opts && Number.isFinite(opts.maxBytes) && opts.maxBytes > 0) ? opts.maxBytes : 1e6;
   return new Promise((resolve, reject) => {
     let body = '';
     // P-c1read-7b3c: aborted closure flag prevents OOM from a misbehaving local
@@ -5262,13 +5355,19 @@ function readBody(req) {
     req.on('data', chunk => {
       if (aborted) return;
       body += chunk;
-      if (body.length > 1e6) {
+      if (body.length > maxBytes) {
         // Order matters: set aborted first so any in-flight chunk early-returns,
         // then clear the timer, tear down the socket, and surface the failure.
         aborted = true;
         clearTimeout(timeout);
         req.destroy();
-        reject(new Error('Too large'));
+        // Carry a typed code + 4xx status so callers can map this onto a
+        // proper envelope (e.g. CC image endpoints → typed 'invalid-image'
+        // 400) instead of falling through to a generic 500 handler-exception.
+        const err = new Error('Request body too large');
+        err.statusCode = 413;
+        err.code = 'payload-too-large';
+        reject(err);
       }
     });
     req.on('end', () => {
@@ -8919,9 +9018,21 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     if (checkRateLimit('command-center', 10)) return jsonReply(res, 429, { error: 'Rate limited — max 10 requests/minute' });
     let tabId;
     try {
-      const body = await readBody(req);
+      // Image turns can carry up to 4×5 MB base64 blobs, so use the larger CC
+      // image cap — readBody's 1 MB default would reject any non-trivial
+      // screenshot before _validateCcImages could enforce the real limits.
+      const body = await readBody(req, { maxBytes: CC_IMAGE_REQUEST_MAX_BYTES });
       if (!body.message) return jsonReply(res, 400, { error: 'message required' });
 
+      // P-9c5f1a83 — server-side image validation. Reject with a typed
+      // 'invalid-image' envelope (4xx, never a 500) before doing any work.
+      const _imgCheck = _validateCcImages(body.images);
+      if (_imgCheck.error) {
+        llm.trackEngineError('command-center', _imgCheck.error.code);
+        return jsonReply(res, 400, _imgCheck.error);
+      }
+      const ccImages = _imgCheck.images;
+
       // Per-tab concurrency guard
       tabId = body.tabId || 'default';
       if (_ccTabIsInFlight(tabId)) {
@@ -8965,7 +9076,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           timeoutMs: turnTimeoutMs, label: 'command-center',
         }, (registerAbort) => ccCall(body.message, {
           store: 'cc', transcript: body.transcript, systemPrompt: turnSystemPrompt, turnId: ccTurnId,
-          onAbortReady: registerAbort,
+          onAbortReady: registerAbort, images: ccImages,
         }));
 
         // W-mpmwxni2000c25c7-b — typed-error envelope path. Any failure that
@@ -9011,7 +9122,17 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       } finally {
         _releaseCCTab(tabId);
       }
-    } catch (e) { _releaseCCTab(tabId); return jsonReply(res, e.statusCode || 500, { error: e.message, code: 'handler-exception', retriable: false }); }
+    } catch (e) {
+      _releaseCCTab(tabId);
+      // An over-budget image payload trips readBody's size cap; surface it as
+      // the documented typed 'invalid-image' 400 envelope, not a generic 500.
+      if (e && e.code === 'payload-too-large') {
+        const env = _ccPayloadTooLargeRejection();
+        llm.trackEngineError('command-center', env.code);
+        return jsonReply(res, 400, env);
+      }
+      return jsonReply(res, e.statusCode || 500, { error: e.message, code: 'handler-exception', retriable: false });
+    }
   }
 
   // W-mpxq9sjq000z794b — Watch-driven CC invocation. Internal-only endpoint
@@ -9116,8 +9237,11 @@ What would you like to discuss or change? When you're happy, say "approve" and I
    * lives on the per-dispatch _spawnProcess model in engine.js (regression
    * test enforces engine.js does not import cc-worker-pool).
    */
-  function _invokeCcStream({ prompt, sessionId, liveState, toolUses, model, effort, maxTurns, engineConfig, systemPrompt = CC_STATIC_SYSTEM_PROMPT, tabId }) {
+  function _invokeCcStream({ prompt, sessionId, liveState, toolUses, model, effort, maxTurns, engineConfig, systemPrompt = CC_STATIC_SYSTEM_PROMPT, tabId, images }) {
     if (shared.resolveCcUseWorkerPool(engineConfig)) {
+      // The ACP worker pool is copilot-only (shared.resolveCcUseWorkerPool
+      // forces it OFF for non-copilot CC) and copilot has imageInput:false, so
+      // image turns never reach this branch — drop `images` here intentionally.
       return _invokeCcStreamViaPool({ prompt, liveState, toolUses, model, effort, engineConfig, systemPrompt, tabId });
     }
     const { callLLMStreaming } = require('./engine/llm');
@@ -9125,7 +9249,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       timeout: CC_CALL_TIMEOUT_MS, label: 'command-center', model, maxTurns,
       allowedTools: 'Bash,Read,Write,Edit,Glob,Grep,WebFetch,WebSearch',
       sessionId, effort, direct: true,
-      engineConfig,
+      engineConfig, images,
       onChunk: (text, segmentId) => {
         _touchCcLiveStream(liveState);
         liveState.text = text;
@@ -9498,12 +9622,25 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       _logCcStreamEnd(_ccTelemetry, 'missing-runtime');
     };
     try {
-      const body = await readBody(req);
+      // Larger cap for image turns (see handleCommandCenter) so a screenshot
+      // paste reaches _validateCcImages rather than tripping readBody's 1 MB
+      // default and surfacing as a generic crash.
+      const body = await readBody(req, { maxBytes: CC_IMAGE_REQUEST_MAX_BYTES });
       if (!body.message && !body.reconnect) {
         res.statusCode = 400; res.end('message required');
         _logCcStreamEnd(_ccTelemetry, 'bad-request');
         return;
       }
+      // P-9c5f1a83 — server-side image validation BEFORE SSE headers are sent,
+      // so a rejection returns a clean typed 4xx JSON envelope (code
+      // 'invalid-image', never a 500) rather than an `event: error` mid-stream.
+      const _imgCheck = _validateCcImages(body.images);
+      if (_imgCheck.error) {
+        llm.trackEngineError('command-center', _imgCheck.error.code);
+        _logCcStreamEnd(_ccTelemetry, 'invalid-image');
+        return jsonReply(res, 400, _imgCheck.error);
+      }
+      const ccImages = _imgCheck.images;
       tabId = body.tabId || 'default';
       _ccTelemetry.tabId = tabId;
       _ccTelemetry.sessionId = body.sessionId || null;
@@ -9724,7 +9861,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
             model: streamModel, effort: streamEffort, maxTurns: ccMaxTurns,
             engineConfig: CONFIG.engine,
             systemPrompt: turnSystemPrompt,
-            tabId,
+            tabId, images: ccImages,
           });
           _ccStreamAbort = llmPromise.abort;
           liveState.abortFn = _ccStreamAbort;
@@ -9748,7 +9885,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
               model: streamModel, effort: streamEffort, maxTurns: ccMaxTurns,
               engineConfig: CONFIG.engine,
               systemPrompt: turnSystemPrompt,
-              tabId,
+              tabId, images: ccImages,
             });
             _ccStreamAbort = retryPromise.abort;
             liveState.abortFn = _ccStreamAbort;
@@ -9866,6 +10003,18 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       // If SSE headers haven't been sent yet (e.g. readBody guard fired), respond with the
       // intended HTTP status (400 for prototype-pollution rejection) instead of an SSE event.
       if (!res.headersSent) {
+        // An over-budget image payload trips readBody's size cap before SSE
+        // headers are sent; surface it as the documented typed 'invalid-image'
+        // 400 envelope, matching the non-streaming handler.
+        if (e && e.code === 'payload-too-large') {
+          const env = _ccPayloadTooLargeRejection();
+          llm.trackEngineError('command-center', env.code);
+          res.statusCode = 400;
+          res.setHeader('Content-Type', 'application/json');
+          try { res.end(JSON.stringify(env)); } catch {}
+          _logCcStreamEnd(_ccTelemetry, 'invalid-image');
+          return;
+        }
         res.statusCode = e.statusCode || 500;
         res.setHeader('Content-Type', 'application/json');
         // W-mpmwxni2000c25c7-d — non-2xx response carries the same envelope
@@ -12362,7 +12511,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       return serveFreshJson(req, res, {
         tag: 'archived-prds',
         inputs: [path.join(PRD_DIR, 'archive')],
-        builder: () => getArchivedPrds(),
+        builder: () => [],
       });
     }},
     { method: 'GET', path: '/api/verify-guides', desc: 'List of generated verify-guide files under prd/guides/', handler: (req, res) => {
@@ -12659,8 +12808,8 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       const explicitProjectName = String(body.project || '').trim();
       if (explicitProjectName) {
         const projects = shared.getProjects(CONFIG);
-        if (!findProjectByName(projects, explicitProjectName)) {
-          return jsonReply(res, 400, { error: formatUnknownProjectError(explicitProjectName, projects) }, req);
+        if (!shared.findProjectByName(projects, explicitProjectName)) {
+          return jsonReply(res, 400, { error: shared.formatUnknownProjectError(explicitProjectName, projects) }, req);
         }
       }
       const adoTarget = parseAdoPrMetadataTarget(url);
@@ -12969,8 +13118,8 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         reloadConfig();
         const projects = shared.getProjects(CONFIG);
         for (const name of projectNames) {
-          if (!findProjectByName(projects, name)) {
-            return jsonReply(res, 400, { error: formatUnknownProjectError(name, projects) });
+          if (!shared.findProjectByName(projects, name)) {
+            return jsonReply(res, 400, { error: shared.formatUnknownProjectError(name, projects) });
           }
         }
       }
@@ -13649,6 +13798,14 @@ module.exports = {
   _buildHarnessDiagnostics,
   // exported for testing — see test/unit/plans-archive-warnings.test.js
   _archivePrdPostProcess,
+  // P-9c5f1a83 — CC image-attachment validation surface (test seams)
+  _validateCcImages,
+  _buildCcErrorEnvelope,
+  CC_ERROR_CODES,
+  CC_IMAGE_MAX_COUNT,
+  CC_IMAGE_MAX_DECODED_BYTES,
+  CC_IMAGE_MIME_ALLOWLIST,
+  CC_IMAGE_REQUEST_MAX_BYTES,
   // Per-CC-turn correlation surface
   _ccTurnCreations,
   _recordCcTurnCreation,

package/docs/command-center.md

@@ -31,6 +31,45 @@ Canonical envelope (`_buildCcErrorEnvelope` in `dashboard.js`):
 
 **No auto-retry policy.** The backend never re-spawns the LLM after an error envelope. The client never silently resends the user's turn. Retry is a single-click manual action — guards against silent budget burn on `budget-exceeded`, infinite loops on `auth-failure`, and accidental re-charges on `context-limit`. The 429 + reconnect paths (rate-limited fetch retry, SSE reconnect-after-disconnect) remain — those are transport-level, not error-envelope-level.
 
+## Image attachments (PL-cc-image-attachments)
+
+Command Center accepts image attachments alongside the text turn. The dashboard paste/drag-drop UI (`dashboard/js/command-center.js`, fed by `command-input.js`) base64-encodes each file and adds an `images` array to the request body. (Doc-Chat does **not** accept images yet — `dashboard/js/modal-qa.js` never sends an `images` array and `handleDocChat`/`ccDocCall` never read one; wiring it is a possible follow-up.)
+
+**Request shape.** `POST /api/command-center` and `/api/command-center/stream` take an optional `images` field:
+
+```json
+{ "message": "what's wrong with this layout?",
+  "images": [
+    { "mimeType": "image/png", "dataBase64": "iVBORw0KGgo…", "filename": "screenshot.png" }
+  ]
+}
+```
+
+Each entry is `{ mimeType, dataBase64, filename? }`. `filename` is optional; an absent / empty / non-array `images` is the normal text-only turn.
+
+**Server-side validation (`_validateCcImages` in `dashboard.js`).** Uses only Node's built-in `Buffer` (zero-dep invariant). Enforced limits:
+
+- count ≤ `CC_IMAGE_MAX_COUNT` (**4**)
+- decoded size ≤ `CC_IMAGE_MAX_DECODED_BYTES` (**5 MB**) per image
+- `mimeType` in `CC_IMAGE_MIME_ALLOWLIST` — `image/png`, `image/jpeg`, `image/gif`, `image/webp`
+- `dataBase64` well-formed (an optional `data:…;base64,` prefix and whitespace are stripped, then a `Buffer.from(…,'base64')` round-trip must reproduce the input — catches junk the lenient decoder would otherwise silently drop)
+
+Any violation rejects the **whole turn** with a typed error envelope (`code: 'invalid-image'`, a member of the `CC_ERROR_CODES` allowlist) — there is no partial send. The dashboard renders it as the standard red `.cc-error` bubble with a manual Retry (see the [Error surfacing contract](#error-surfacing-contract-w-mpmwxni2000c25c7-d) above).
+
+**Request-body cap (`CC_IMAGE_REQUEST_MAX_BYTES`).** `readBody`'s default body cap is 1 MB — below a single non-trivial screenshot once base64-inflated (~4/3), so it would reject an image turn *before* `_validateCcImages` could enforce the real per-image limit. The two CC endpoints therefore call `readBody(req, { maxBytes: CC_IMAGE_REQUEST_MAX_BYTES })`, sized for the worst legitimate payload (4 images × 5 MB decoded ≈ 27 MB base64) plus headroom. A body over that cap is surfaced as the same typed `invalid-image` **400** envelope (`_ccPayloadTooLargeRejection`), never a generic 500. Non-image endpoints keep the conservative 1 MB default.
+
+**Per-runtime support (typed degradation, never a silent drop).** Support is gated on the adapter `imageInput` capability flag:
+
+| Runtime | `imageInput` | Behavior |
+|---------|--------------|----------|
+| claude  | `true`  | Images delivered as an Anthropic Messages `content[]` envelope of base64 blocks over stream-json (`claude.buildPrompt` + `--input-format stream-json` in `claude.buildArgs`). |
+| copilot | `false` | Degraded — `engine/llm.js` `_resolveImageOpts` returns a typed `model-unavailable` envelope ("switch ccCli to a runtime with imageInput"). The Copilot worker-pool path also drops images. |
+| codex   | `false` | Degraded — same typed `model-unavailable` envelope. |
+
+`_resolveImageOpts` (in `engine/llm.js`) is pure and unit-tested: it forwards the `images` list only when `runtime.capabilities.imageInput` is truthy, otherwise returns the typed error so CC/doc-chat surface the envelope instead of a silently-text-only reply. `_spawnProcess` re-applies the same gate (`if (!caps.imageInput) adapterOpts.images = undefined`) as defense in depth. Image **filenames** are run through the untrusted-input fence (`buildSource('cc-image-filename', …)`) before they reach prompt text, since they are user-supplied.
+
+**No new `engine.*` flag.** The limits above are module-level constants in `dashboard.js` (`CC_IMAGE_MAX_COUNT`, `CC_IMAGE_MAX_DECODED_BYTES`, `CC_IMAGE_MIME_ALLOWLIST`), not config keys; `engine/shared.js` `ENGINE_DEFAULTS` was not touched. Per CLAUDE.md Best Practice #9 (Settings parity), no Settings toggle is added because no new `engine.*` flag was introduced. Runtime selection that determines whether images are accepted is the existing `engine.ccCli` / `ccModel` override, which already has a Settings control.
+
 ## Per-turn surfacing pipeline
 
 CC handler generates `ccTurnId = 'cct-' + shared.uid()` per request; injected into sysprompt AND prompt body via `_ccTurnHeaderPart(turnId)` (load-bearing: on resumed sessions `engine/llm.js` skips re-sending the sysprompt, so without body injection CC keeps the stale turn ID). Handler reads via `_readCcTurnIdHeader(req)` and calls `_recordCcTurnCreation(turnId, ...)` on success. End-of-turn: `_buildSyntheticActionResultsForTurn` produces synthetic `{action, result}` pairs (`_serverExecuted: true`). Client renders as standalone `role='action'` messages outside the assistant bubble. TTL: 5 min. Endpoints wired: `/api/work-items`, `/api/notes`, `/api/plan`, `/api/knowledge`, `/api/watches`.

package/docs/self-improvement.md

@@ -83,7 +83,7 @@ Fallback entries are labeled `**By:** Engine (regex fallback)` so you can tell w
 
 ### Auto-Pruning
 
-When `notes.md` exceeds 50KB, the engine prunes old consolidation sections, keeping the header and last 8 consolidations. This prevents the file from growing unbounded while retaining recent institutional knowledge.
+When `notes.md` exceeds 50KB, the engine trims it to the cap (keeping the header and last 8 consolidations) but **does not silently discard** the older sections — every dropped section is appended to `notes/archive/notes-overflow.md` so nothing is lost (data-loss guard `_capNotesPreservingOverflow` in `engine/consolidation.js`, #218). This keeps the live file bounded while retaining recent institutional knowledge and preserving the rest in the archive.
 
 ## 2. Per-Agent History
 
@@ -328,7 +328,7 @@ When a git merge or rebase produces conflicts in yarn.lock.
 | Consolidation model | Haiku | LLM used for summarization (fast, cheap) |
 | LLM process kill timeout | 3 min (180,000ms) | Max time for LLM call before killing process and falling back to regex |
 | Stale flag auto-reset | 5 min (300,000ms) | `_consolidationInFlight` flag auto-resets after this duration to unblock future runs |
-| notes.md max size | 50KB | Auto-prunes old sections above this |
+| notes.md max size | 50KB | Trims to cap above this; overflow archived to `notes/archive/notes-overflow.md` (not discarded) |
 | Agent history entries | 20 | Max entries kept in history.md |
 | Metrics file | `engine/metrics.json` | Auto-created on first completion |
 

package/engine/cc-worker-pool.js

@@ -108,17 +108,34 @@ const WARM_MAX_CONCURRENT = 3;
 // test/unit/cc-worker-pool.test.js can stub spawn/now/killImmediate.
 const _internals = {
   spawnAcp({ cwd } = {}) {
-    return spawn(
-      'copilot',
-      ['--acp', '--allow-all', '--max-autopilot-continues', '1'],
-      {
-        stdio: ['pipe', 'pipe', 'pipe'],
-        cwd: cwd || process.cwd(),
-        windowsHide: true,
-        // Don't pass shell:true — Copilot is a binary on PATH and a shell
-        // wrapper would swallow stdin/stdout framing.
-      }
-    );
+    // Resolve `copilot` through the adapter so the pool gets the SAME
+    // native/leadingArgs contract as the only other spawn site
+    // (engine/spawn-agent.js ~line 595). A bare `spawn('copilot', {shell:false})`
+    // cannot exec a `.cmd`/`.ps1`/extensionless npm shim on Windows — it ENOENTs
+    // instantly (copilot issue #2370 / W-mqid8uev). resolveBinary() resolves the
+    // real JS entry (node_modules/@github/copilot/index.js) and reports whether
+    // to spawn it directly (native) or under the current Node process (shim).
+    const copilot = require('./runtimes/copilot');
+    const resolved = copilot.resolveBinary({ env: process.env });
+    if (!resolved || !resolved.bin) {
+      throw new Error(
+        `copilot binary not resolvable -- ${copilot.installHint || 'install the GitHub Copilot CLI'}`
+      );
+    }
+    const { bin, native, leadingArgs = [] } = resolved;
+    const acpArgs = [...leadingArgs, '--acp', '--allow-all', '--max-autopilot-continues', '1'];
+    // Mirror engine/spawn-agent.js: native binaries run directly; a non-native
+    // (JS entry / npm shim) runs under process.execPath as `node <bin> ...`.
+    const execBin = native ? bin : process.execPath;
+    const execArgs = native ? acpArgs : [bin, ...acpArgs];
+    return spawn(execBin, execArgs, {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      cwd: cwd || process.cwd(),
+      windowsHide: true,
+      // Don't pass shell:true — the native/leadingArgs handling above already
+      // produces a directly-spawnable argv, and a shell wrapper would swallow
+      // the stdin/stdout JSON-RPC framing.
+    });
   },
   killImmediate(proc) {
     // Lazy require so unit tests that don't load engine/shared still work.

package/engine/cli.js

@@ -1146,9 +1146,9 @@ const commands = {
     // export) doesn't go silent.
     function drainBuffers() {
       try { require('./llm').flushMetricsBuffer(); }
-      catch (err) { try { console.error(`[shutdown] flushMetricsBuffer failed: ${err.message}`); } catch {} }
+      catch (err) { console.error(`[shutdown] flushMetricsBuffer failed: ${err.message}`); }
       try { shared.flushLogs(); }
-      catch (err) { try { console.error(`[shutdown] flushLogs failed: ${err.message}`); } catch {} }
+      catch (err) { console.error(`[shutdown] flushLogs failed: ${err.message}`); }
     }
 
     // Graceful shutdown — wait for active agents before exiting

package/engine/db-events.js

@@ -29,10 +29,8 @@ function emitStateEvent(topic, payload) {
     // without spamming on every write.
     if (!_logged) {
       _logged = true;
-      try {
-        // eslint-disable-next-line no-console
-        console.warn(`[db-events] state event emission disabled: ${e.message}`);
-      } catch { /* console unavailable in some test seams */ }
+      // eslint-disable-next-line no-console
+      console.warn(`[db-events] state event emission disabled: ${e.message}`);
     }
   }
 }

package/engine/dispatch.js

@@ -518,6 +518,7 @@ function isRetryableFailureReason(reason = '', failureClass = '') {
       FAILURE_CLASS.MANAGED_SPAWN_HEALTHCHECK_FAILED, // W-mpbhxg3b000u8411 — healthcheck timed out; agent must fix the spec or the service it spawned
       FAILURE_CLASS.INJECTION_FLAGGED, // F5 (W-mpeklod3000we69c) — agent spotted a prompt-injection attempt in spliced untrusted content; a human must review the source before re-dispatch
       FAILURE_CLASS.LIVE_CHECKOUT_DIRTY, // P-a3f9b204 — live-checkout refused to spawn because operator localPath is dirty; mechanical retry won't fix it (operator must commit/stash/discard)
+      FAILURE_CLASS.OUTPUT_TRUNCATED, // P-8e4c2a17 — agent stdout exceeded the hard capture cap before the terminal result event; mechanical retry just reproduces the overflow (agent must reduce output volume or the task must be split)
     ]);
     if (neverRetry.has(failureClass)) return false;
   }

package/engine/lifecycle.js

@@ -2972,7 +2972,15 @@ async function handlePostMerge(pr, project, config, newStatus) {
 
   const prNum = shared.getPrNumber(pr);
 
-  if (pr.branch && project) {
+  // `project.localPath` guard: central/observed PRs (e.g. ADO PRs tracked in
+  // ~/.minions/pull-requests.json with no configured project) are polled via a
+  // *synthesized* project that has no localPath (engine/ado.js + engine/github.js
+  // central-poll loops). There is no checkout to clean for those, and an
+  // unguarded path.resolve(undefined) here threw "paths[0] argument must be of
+  // type string" — caught upstream and logged as "failed to poll central PR".
+  // Skip the worktree-cleanup block when there is no local clone; the rest of
+  // handlePostMerge keys off MINIONS_DIR and still runs.
+  if (pr.branch && project && project.localPath) {
     const root = path.resolve(project.localPath);
     const wtRoot = path.resolve(root, config.engine?.worktreeRoot || '../worktrees');
     let removedBranchWorktree = false;

package/engine/llm.js

@@ -272,6 +272,48 @@ function _resolvedCallResult(result) {
   return promise;
 }
 
+// P-7b2e4d01 — image-input gate. Decide whether a caller-supplied `images`
+// array can be forwarded to the resolved runtime. Pure + side-effect free so it
+// is unit-testable without spawning a process.
+//   - no images                          → { images: undefined, error: null }   (today's text-only behavior)
+//   - images + caps.imageInput truthy     → { images, error: null }
+//   - images + caps.imageInput falsy       → { images: undefined, error: <typed> }
+// The error `code` is aligned with dashboard CC_ERROR_CODES ('model-unavailable')
+// so the CC/doc-chat envelope normalizes it cleanly — never a silent drop.
+function _resolveImageOpts(images, caps = {}) {
+  const list = Array.isArray(images) ? images.filter(Boolean) : [];
+  if (!list.length) return { images: undefined, error: null };
+  if (caps && caps.imageInput) return { images: list, error: null };
+  return {
+    images: undefined,
+    error: {
+      message: 'The selected runtime cannot accept image input — switch ccCli to a runtime with imageInput (e.g. claude).',
+      code: 'model-unavailable',
+      retriable: false,
+    },
+  };
+}
+
+// Build a resolved (failed) call result for an image turn the runtime can't
+// serve. Mirrors _missingRuntimeResult's shape so existing CC/doc-chat callers
+// surface the typed `error` envelope instead of an empty hanging reply.
+function _imageUnsupportedResult(runtime, error) {
+  return {
+    text: error.message,
+    usage: null,
+    sessionId: null,
+    code: MISSING_RUNTIME_EXIT_CODE,
+    stderr: error.message,
+    raw: '',
+    toolUses: [],
+    runtime: runtime?.name || null,
+    errorClass: error.code,
+    errorMessage: error.message,
+    error: { message: error.message, code: error.code, retriable: error.retriable === true },
+    ok: false,
+  };
+}
+
 function _resolveRuntimeNameFor(callOpts = {}) {
   let runtimeName = callOpts.cli;
   if (!runtimeName && callOpts.engineConfig) runtimeName = resolveCcCli(callOpts.engineConfig);
@@ -346,6 +388,7 @@ function _spawnProcess(promptText, sysPromptText, callOpts) {
     direct, label, runtime, model, maxTurns, allowedTools, effort, sessionId,
     maxBudget, bare, fallbackModel,
     stream, disableBuiltinMcps, suppressAgentsMd, reasoningSummaries,
+    images,
   } = callOpts;
 
   const id = uid();
@@ -361,6 +404,7 @@ function _spawnProcess(promptText, sysPromptText, callOpts) {
     model, maxTurns, allowedTools, effort, sessionId,
     maxBudget, bare, fallbackModel,
     stream, disableBuiltinMcps, suppressAgentsMd, reasoningSummaries,
+    images,
   };
   // Capability-gate per-flag opts before prompt construction so adapters can
   // make resume-aware prompt decisions from the same opts used for argv.
@@ -369,6 +413,10 @@ function _spawnProcess(promptText, sysPromptText, callOpts) {
   if (!caps.budgetCap) adapterOpts.maxBudget = undefined;
   if (!caps.bareMode) adapterOpts.bare = undefined;
   if (!caps.fallbackModel) adapterOpts.fallbackModel = undefined;
+  // P-7b2e4d01 — defense in depth: never forward images to a runtime that
+  // can't read them (callLLM/callLLMStreaming already gate + surface a typed
+  // error upstream; this protects any other _spawnProcess caller).
+  if (!caps.imageInput) adapterOpts.images = undefined;
   const finalPrompt = runtime.buildPrompt(promptText, sysPromptText, adapterOpts);
 
   // ── Direct path ──
@@ -701,6 +749,8 @@ function callLLM(promptText, sysPromptText, opts = {}) {
     // Cross-runtime + Copilot opts:
     maxBudget, bare, fallbackModel,
     stream, disableBuiltinMcps, suppressAgentsMd, reasoningSummaries,
+    // P-7b2e4d01 — optional image attachments: [{ mimeType, dataBase64, filename? }]
+    images,
   } = opts;
 
   const unavailable = _runtimeUnavailableResult({ cli: cliOverride, engineConfig });
@@ -708,6 +758,8 @@ function callLLM(promptText, sysPromptText, opts = {}) {
 
   const runtime = _resolveRuntimeFor({ cli: cliOverride, engineConfig });
   const model = _resolveModelForRuntime(runtime, { model: modelOverride, engineConfig });
+  const imageGate = _resolveImageOpts(images, runtime && runtime.capabilities);
+  if (imageGate.error) return _resolvedCallResult(_imageUnsupportedResult(runtime, imageGate.error));
   const runtimeFeatureOpts = _resolveRuntimeFeatureOpts({
     stream, disableBuiltinMcps, suppressAgentsMd, reasoningSummaries, engineConfig,
   });
@@ -717,7 +769,7 @@ function callLLM(promptText, sysPromptText, opts = {}) {
     const _startMs = Date.now();
     const { proc, cleanupFiles, cleanupDirs } = _spawnProcess(promptText, sysPromptText, {
       direct, label, runtime, model, maxTurns, allowedTools, effort, sessionId,
-      maxBudget, bare, fallbackModel,
+      maxBudget, bare, fallbackModel, images: imageGate.images,
       ...runtimeFeatureOpts,
     });
     let resolved = false;
@@ -822,6 +874,8 @@ function callLLMStreaming(promptText, sysPromptText, opts = {}) {
     model: modelOverride, cli: cliOverride, engineConfig,
     maxBudget, bare, fallbackModel,
     stream, disableBuiltinMcps, suppressAgentsMd, reasoningSummaries,
+    // P-7b2e4d01 — optional image attachments: [{ mimeType, dataBase64, filename? }]
+    images,
   } = opts;
 
   const unavailable = _runtimeUnavailableResult({ cli: cliOverride, engineConfig });
@@ -829,6 +883,8 @@ function callLLMStreaming(promptText, sysPromptText, opts = {}) {
 
   const runtime = _resolveRuntimeFor({ cli: cliOverride, engineConfig });
   const model = _resolveModelForRuntime(runtime, { model: modelOverride, engineConfig });
+  const imageGate = _resolveImageOpts(images, runtime && runtime.capabilities);
+  if (imageGate.error) return _resolvedCallResult(_imageUnsupportedResult(runtime, imageGate.error));
   const runtimeFeatureOpts = _resolveRuntimeFeatureOpts({
     stream, disableBuiltinMcps, suppressAgentsMd, reasoningSummaries, engineConfig,
   });
@@ -838,7 +894,7 @@ function callLLMStreaming(promptText, sysPromptText, opts = {}) {
     const _startMs = Date.now();
     const { proc, cleanupFiles, cleanupDirs } = _spawnProcess(promptText, sysPromptText, {
       direct, label, runtime, model, maxTurns, allowedTools, effort, sessionId,
-      maxBudget, bare, fallbackModel,
+      maxBudget, bare, fallbackModel, images: imageGate.images,
       ...runtimeFeatureOpts,
     });
     let resolved = false;
@@ -1028,6 +1084,7 @@ module.exports = {
   _resetBinCache,
   _resetMetricsBufferForTest,
   _resolveRuntimeFor,
+  _resolveImageOpts,
   _resolveModelFor,
   _resolveModelForRuntime,
   _resolveRuntimeFeatureOpts,

package/engine/runtimes/claude.js

@@ -29,6 +29,7 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { FAILURE_CLASS, safeWrite, ts, resolveEngineCacheDir } = require('../shared');
+const { wrapUntrusted, buildSource } = require('../untrusted-fence');
 
 const ENGINE_DIR = __dirname.replace(/[\\/]runtimes$/, '');
 const MINIONS_DIR = path.resolve(ENGINE_DIR, '..');
@@ -223,10 +224,15 @@ function buildArgs(opts = {}) {
     maxBudget,
     bare = false,
     fallbackModel,
+    images,
   } = opts;
 
   const args = ['-p', '--output-format', outputFormat];
   if (outputFormat === 'stream-json') args.push('--include-partial-messages');
+  // P-7b2e4d01: image turns are delivered as a stream-json user envelope over
+  // stdin (see buildPrompt). The CLI requires --input-format=stream-json, which
+  // in turn requires --output-format=stream-json — already the default above.
+  if (Array.isArray(images) && images.length) args.push('--input-format', 'stream-json');
   if (maxTurns != null) args.push('--max-turns', String(maxTurns));
   if (model) args.push('--model', String(model));
   if (verbose) args.push('--verbose');
@@ -404,11 +410,48 @@ function classifyFailure({ code, stdout = '', stderr = '', fallback } = {}) {
 /**
  * Build the final prompt text delivered to the Claude CLI. Claude takes the
  * system prompt via `--system-prompt-file` and the user prompt via stdin, so
- * `buildPrompt()` is a passthrough — `sysPromptText` is delivered separately
- * by the spawn wrapper, not embedded in the user prompt.
+ * `buildPrompt()` is normally a passthrough — `sysPromptText` is delivered
+ * separately by the spawn wrapper, not embedded in the user prompt.
+ *
+ * P-7b2e4d01 — image input. When `opts.images` is a non-empty array of
+ * `{ mimeType, dataBase64, filename? }`, return the single-line stream-json
+ * user-message envelope the CLI reads under `--input-format stream-json`
+ * (a true multimodal Anthropic Messages `content[]` shape) instead of the
+ * bare string. base64 content-blocks are preferred over `@path` references
+ * (no temp-file lifecycle, no Read-tool round-trip — per spike P-3f8a1c92).
+ * Any caller-supplied `filename` is untrusted and is wrapped via the
+ * untrusted-fence before it reaches the text block.
  */
-function buildPrompt(promptText, /* sysPromptText */ _sys) {
-  return String(promptText == null ? '' : promptText);
+function buildPrompt(promptText, /* sysPromptText */ _sys, opts = {}) {
+  const text = String(promptText == null ? '' : promptText);
+  const images = Array.isArray(opts && opts.images) ? opts.images.filter(Boolean) : [];
+  if (!images.length) return text;
+
+  // Fence any filename that reaches prompt text — image filenames are
+  // attacker-controlled (pasted/dropped in the browser) and must be treated
+  // as data, not instructions.
+  const named = images.filter(img => img && img.filename != null && String(img.filename).trim());
+  let textBlock = text;
+  if (named.length) {
+    const fenced = named
+      .map(img => wrapUntrusted(String(img.filename), buildSource('cc-image-filename', { mimeType: img.mimeType || '' })))
+      .filter(Boolean)
+      .join('\n');
+    if (fenced) textBlock = `${text}\n\nAttached image filename(s):\n${fenced}`;
+  }
+
+  const content = [
+    { type: 'text', text: textBlock },
+    ...images.map(img => ({
+      type: 'image',
+      source: {
+        type: 'base64',
+        media_type: String(img.mimeType || 'image/png'),
+        data: String(img.dataBase64 == null ? '' : img.dataBase64),
+      },
+    })),
+  ];
+  return JSON.stringify({ type: 'user', message: { role: 'user', content } });
 }
 
 // ── Output Parsing ───────────────────────────────────────────────────────────
@@ -759,6 +802,10 @@ const capabilities = {
   resumeBookkeepingTurn: true,
   // Adapter implements createStreamConsumer(ctx) — required by llm.js accumulator
   streamConsumer: true,
+  // P-7b2e4d01: accepts image input via stream-json base64 content blocks
+  // (proven empirically in spike P-3f8a1c92). Engine code gates on this flag,
+  // never on runtime.name.
+  imageInput: true,
 };
 
 // Install hint surfaced when `resolveBinary()` returns null. Consumed by

package/engine/runtimes/codex.js

@@ -832,6 +832,9 @@ const capabilities = {
   sessionPersistenceControl: false,
   resumePromptCarryover: true,
   streamConsumer: true,
+  // P-7b2e4d01: no image-input mechanism (CLI not installed during spike
+  // P-3f8a1c92). Engine code gates on this flag, never on runtime.name.
+  imageInput: false,
 };
 
 const INSTALL_HINT = 'install Codex CLI with `npm install -g @openai/codex` or `brew install --cask codex`, then run `codex login`.';

package/engine/runtimes/copilot.js

@@ -1214,6 +1214,11 @@ const capabilities = {
   resumePromptCarryover: true,
   // Adapter implements createStreamConsumer(ctx) — required by llm.js accumulator
   streamConsumer: true,
+  // P-7b2e4d01: `--attachment <path>` is documented for non-interactive mode
+  // but the headless smoke test was inconclusive (spike P-3f8a1c92). Stub false
+  // until a clean re-test passes; enabling it also needs temp-file materializing
+  // of the base64 payload (a different adapter-local path than Claude's inline).
+  imageInput: false,
 };
 
 // Install hint surfaced when `resolveBinary()` returns null. Covers all

package/engine/shared.js

@@ -4198,6 +4198,7 @@ const FAILURE_CLASS = {
   WORKSPACE_MANIFEST_TOOL: 'workspace-manifest-tool-forbidden', // W-mq07avbk000m5543: out-of-scope tool call (manifest enforcement at the runtime gate). Non-retryable as-is.
   WORKSPACE_MANIFEST_URL: 'workspace-manifest-url-forbidden',   // W-mq07avbk000m5543: out-of-scope external URL fetch. Non-retryable as-is.
   SPAWN_PHASE_STALL: 'spawn-phase-stall', // W-mq0e2dae000a003d: process spawned and ran startup-only events (MCP init / hooks) but never emitted real task progress; CPU usage stayed below threshold past the grace window. Engine kills the wedged child and treats this as retryable (fresh-session) so a re-spawn can clear a transient MCP wedge.
+  OUTPUT_TRUNCATED: 'output-truncated',   // P-8e4c2a17: the agent streamed more stdout than the engine's hard capture cap (engine.js AGENT_OUTPUT_CAP_BYTES, 1MB) BEFORE the terminal `result` event arrived. The result (session id, completion block, final text) lives at the END of the stream, so it fell outside the captured window and parseOutput found nothing — the dispatch would otherwise fail as an opaque UNKNOWN and retry to death. Surfaced loudly with an actionable message; non-retryable (mechanical retry just reproduces the overflow — the agent must reduce output volume or the task must be split).
   UNKNOWN: 'unknown',                     // Unclassified failure
 };
 const ESCALATION_POLICY = {

package/engine/stdio-timestamps.js

@@ -18,8 +18,7 @@ function _ts() { return new Date().toISOString(); }
 function _wrap(method) {
   const original = console[method].bind(console);
   return (...args) => {
-    try { original(`[${_ts()}]`, ...args); }
-    catch { original(...args); }
+    original(`[${_ts()}]`, ...args);
   };
 }
 

package/engine.js

@@ -498,9 +498,37 @@ function _stdoutForFallbackClassification(rawStdout, failureSignal) {
   return 'agent produced non-empty stdout without a terminal runtime error signal';
 }
 
+// P-8e4c2a17 — Hard cap on captured agent stdout/stderr (chars). The capture
+// handlers in spawnAgent slice incoming chunks so the in-memory buffers never
+// exceed this length. The terminal `result` event (session id, usage,
+// completion block, final text) arrives at the END of the stream, so when a run
+// streams past this cap the result falls OUTSIDE the captured window and
+// parseOutput finds nothing — see _isOutputTruncated / _classifyAgentFailure.
+const AGENT_OUTPUT_CAP_BYTES = 1024 * 1024; // 1MB
+
+// P-8e4c2a17 — Detect the "output overflowed before the terminal result" case.
+// True when (a) the captured stdout reached the hard cap AND (b) no terminal
+// `result` event survived the window (the runtime adapter's parseOutput can
+// recover neither a session id nor usage — both of which come ONLY from the
+// result event). A run whose result WAS captured returns false, so this never
+// misfires on a normally-terminated agent.
+function _isOutputTruncated(runtime, stdout) {
+  const text = stdout == null ? '' : String(stdout);
+  if (text.length < AGENT_OUTPUT_CAP_BYTES) return false; // never hit the cap
+  if (runtime && typeof runtime.parseOutput === 'function') {
+    try {
+      const parsed = runtime.parseOutput(text) || {};
+      // sessionId + usage are populated only by the terminal result event.
+      if (parsed.sessionId || parsed.usage) return false;
+    } catch { /* unparseable at the cap → treat as truncated */ }
+  }
+  return true;
+}
+
 function _classifyAgentFailure(runtime, code, stdout, stderr) {
   const failureSignal = _collectAgentFailureSignal(stdout);
   const fallbackStdout = _stdoutForFallbackClassification(stdout, failureSignal);
+  let result = null;
   if (runtime && typeof runtime.classifyFailure === 'function') {
     const classified = runtime.classifyFailure({
       code,
@@ -509,9 +537,22 @@ function _classifyAgentFailure(runtime, code, stdout, stderr) {
       fallback: (fallbackCode, _stdout, fallbackStderr) =>
         classifyFailureFallback(fallbackCode, fallbackStdout, fallbackStderr),
     });
-    if (classified && classified.failureClass) return classified;
+    if (classified && classified.failureClass) result = classified;
+  }
+  if (!result) result = { failureClass: classifyFailureFallback(code, fallbackStdout, stderr) };
+
+  // P-8e4c2a17 — Upgrade an opaque UNKNOWN to OUTPUT_TRUNCATED when the capture
+  // hit the hard cap and the terminal result event never made it into the
+  // window. Only the UNKNOWN case is upgraded so explicit signals that DID land
+  // mid-stream (auth, context-limit, build failure, …) keep their classes.
+  if (result.failureClass === FAILURE_CLASS.UNKNOWN && _isOutputTruncated(runtime, stdout)) {
+    return {
+      failureClass: FAILURE_CLASS.OUTPUT_TRUNCATED,
+      retryable: false,
+      message: `Agent stdout exceeded the ${AGENT_OUTPUT_CAP_BYTES}-byte capture cap before the terminal result event arrived — the session id, completion report, and final text were streamed past the window and lost. Mechanical retry will just reproduce the overflow. Reduce output volume (quieter tools, fewer full-file dumps) or split the task into smaller work items.`,
+    };
   }
-  return { failureClass: classifyFailureFallback(code, fallbackStdout, stderr) };
+  return result;
 }
 
 function ackPendingSteeringFiles(agentId, procInfo, rawOutput, observedAtMs = Date.now()) {
@@ -3636,7 +3677,7 @@ async function spawnAgent(dispatchItem, config) {
     log('info', `[spawn-timing] id=${id} agent=${agentId} type=${type} runtime=${runtimeName} branch=${branchName || '-'} deps=${_depCountForLog} ${JSON.stringify(timings)}`);
   } catch { /* telemetry is best-effort */ }
 
-  const MAX_OUTPUT = 1024 * 1024; // 1MB
+  const MAX_OUTPUT = AGENT_OUTPUT_CAP_BYTES; // P-8e4c2a17: 1MB hard capture cap (module const)
   let stdout = '';
   let stderr = '';
   let steeringAckStdout = '';
@@ -9702,6 +9743,7 @@ module.exports = {
   findExistingWorktree, // exported for testing
   probeBranchOnRemote, // exported for testing (W-mphnm6a1000281b8)
   _maxTurnsForType, buildProjectContext, normalizeAc, _buildAgentSpawnFlags, _classifyAgentFailure, // exported for testing
+  _isOutputTruncated, AGENT_OUTPUT_CAP_BYTES, // P-8e4c2a17: exported for testing (OUTPUT_TRUNCATED detection)
   promoteCheckpointSteeringForClose, // exported for testing
   normalizePrBranch, resolvePrBranch, prCausePart, getPrCauseHead, getPrCauseBase, getPrAutomationCauseKey, getPrAutomationDispatchKey, // exported for testing
   ensurePrBranchForDispatch, isWithinLinkGraceWindow, PR_LINK_GRACE_WINDOW_MS, // exported for testing (W-mphm0kt0000cebc3)

package/package.json

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