@yemi33/minions 0.1.1033 → 0.1.1035

package/CHANGELOG.md

@@ -1,5 +1,84 @@
 # Changelog
 
+## 0.1.1035 (2026-04-16)
+
+### Features
+-  Doc-chat performance — debounced persistence, session TTL, smart disk reads (#1164)
+- split getStatus() into fast/slow state tiers with separate TTLs (#1170)
+-  Cache _countWorktrees() with 30s TTL (#1166)
+- Pre-cache gzipped status buffer alongside JSON cache (#1171)
+- parallelize ADO and GitHub PR polling with Promise.allSettled (#1172)
+- route implement items to dedicated implement playbook (#1115)
+
+### Fixes
+-  sidecar oversized dispatch prompts to prevent dashboard OOM (closes #1167) (#1183)
+-  use locked write for failed-with-PR reconciliation in cleanup.js (#1169)
+-  prevent test from corrupting live meeting state
+- scheduler enabled field falsy check treats undefined as disabled (#1160)
+-  update branch-dedup tests to use canonical PR IDs after merge with master (#1146)
+-  auto-review not firing for manually-linked PRs with autoObserve=true
+-  mark PR abandoned on 404 instead of silently retrying each tick
+- replace undefined PROJECTS with config.projects in checkWatches (#1108)
+- write permission for publish workflow
+-  run tests inline and post check runs for publish PRs
+- add maxBuffer to all GitHub CLI spawns + paginate PR list (#1130)
+-  add required CI checks for PRs + update publish for auto-merge
+-  revert to PR merge now that stale status check is removed
+- guard live review check against undefined vote/state values (#1132)
+-  push version bump directly to master instead of via PR
+-  add push-triggered CI for chore/publish branches
+-  publish workflow chore PRs failing to merge
+-  harden KB ordering
+-  harden audited state transitions
+
+### Other
+- [E2E] Dashboard & engine perf: gzip cache, tiered status, lock backoff, polling parallelization (#1174)
+- Fix doc chat session isolation
+- test(pipeline): add unit tests for CRUD, stage execution, run lifecycle (#1162)
+- chore: test publish after removing stale status check
+- chore: trigger publish test
+- chore: test publish workflow fix
+- chore: trigger publish workflow test
+
+## 0.1.1034 (2026-04-16)
+
+### Features
+-  Doc-chat performance — debounced persistence, session TTL, smart disk reads (#1164)
+- split getStatus() into fast/slow state tiers with separate TTLs (#1170)
+-  Cache _countWorktrees() with 30s TTL (#1166)
+- Pre-cache gzipped status buffer alongside JSON cache (#1171)
+- parallelize ADO and GitHub PR polling with Promise.allSettled (#1172)
+- route implement items to dedicated implement playbook (#1115)
+
+### Fixes
+-  use locked write for failed-with-PR reconciliation in cleanup.js (#1169)
+-  prevent test from corrupting live meeting state
+- scheduler enabled field falsy check treats undefined as disabled (#1160)
+-  update branch-dedup tests to use canonical PR IDs after merge with master (#1146)
+-  auto-review not firing for manually-linked PRs with autoObserve=true
+-  mark PR abandoned on 404 instead of silently retrying each tick
+- replace undefined PROJECTS with config.projects in checkWatches (#1108)
+- write permission for publish workflow
+-  run tests inline and post check runs for publish PRs
+- add maxBuffer to all GitHub CLI spawns + paginate PR list (#1130)
+-  add required CI checks for PRs + update publish for auto-merge
+-  revert to PR merge now that stale status check is removed
+- guard live review check against undefined vote/state values (#1132)
+-  push version bump directly to master instead of via PR
+-  add push-triggered CI for chore/publish branches
+-  publish workflow chore PRs failing to merge
+-  harden KB ordering
+-  harden audited state transitions
+
+### Other
+- [E2E] Dashboard & engine perf: gzip cache, tiered status, lock backoff, polling parallelization (#1174)
+- Fix doc chat session isolation
+- test(pipeline): add unit tests for CRUD, stage execution, run lifecycle (#1162)
+- chore: test publish after removing stale status check
+- chore: trigger publish test
+- chore: test publish workflow fix
+- chore: trigger publish workflow test
+
 ## 0.1.1033 (2026-04-16)
 
 ### Features

package/dashboard/js/modal-qa.js

@@ -428,6 +428,7 @@ async function _processQaMessage(message, selection, opts) {
         selection: selection,
         filePath: capturedFilePath || null,
         model: window._lastStatus?.autoMode?.ccModel || undefined,
+        contentHash: capturedDocContext.content ? capturedDocContext.content.length + ':' + capturedDocContext.content.charCodeAt(0) + ':' + capturedDocContext.content.charCodeAt(capturedDocContext.content.length - 1) : undefined,
       }),
     });
     const data = await res.json();

package/dashboard.js

@@ -32,6 +32,24 @@ const { getAgents, getAgentDetail, getPrdInfo, getWorkItems, getDispatchQueue,
   getEngineLog, getMetrics, getKnowledgeBaseEntries, timeSince,
   MINIONS_DIR, AGENTS_DIR, ENGINE_DIR, INBOX_DIR, DISPATCH_PATH, PRD_DIR } = queries;
 
+// Startup size guard (#1167): fail fast with a clear error when dispatch.json /
+// cooldowns.json have ballooned past ENGINE_DEFAULTS.maxStateFileBytes. Without
+// this, V8 silently OOMs on JSON.parse(~1 GB) and the operator has no hint as to
+// which file is bloated. The thrown error names the file and directs to
+// engine/contexts/ where sidecars live.
+(() => {
+  const stateFiles = [
+    DISPATCH_PATH,
+    path.join(ENGINE_DIR, 'cooldowns.json'),
+  ];
+  for (const fp of stateFiles) {
+    try { shared.assertStateFileSize(fp); } catch (e) {
+      console.error('\n[dashboard] STARTUP ABORTED — ' + e.message + '\n');
+      process.exit(78); // 78 = configuration error; consistent with spawn-agent.js
+    }
+  }
+})();
+
 const PORT = parseInt(process.env.PORT || process.argv[2]) || 7331;
 let CONFIG = queries.getConfig();
 let PROJECTS = _getProjects(CONFIG);
@@ -852,16 +870,18 @@ async function executeCCActions(actions) {
 // Session store for doc modals — keyed by filePath or title, persisted to disk
 const CC_SESSIONS_PATH = path.join(ENGINE_DIR, 'cc-sessions.json');
 const DOC_SESSIONS_PATH = path.join(ENGINE_DIR, 'doc-sessions.json');
+const DOC_SESSION_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 604800000 — 7 days
 const docSessions = new Map(); // key → { sessionId, lastActiveAt, turnCount }
 
 // Load persisted doc sessions on startup
 try {
   const saved = safeJson(DOC_SESSIONS_PATH);
   if (saved && typeof saved === 'object') {
+    const now = Date.now();
     for (const [key, s] of Object.entries(saved)) {
-      if (s.turnCount < CC_SESSION_MAX_TURNS) {
-        docSessions.set(key, s);
-      }
+      if (s.turnCount >= CC_SESSION_MAX_TURNS) continue;
+      if (s.lastActiveAt && now - new Date(s.lastActiveAt).getTime() > DOC_SESSION_TTL_MS) continue;
+      docSessions.set(key, s);
     }
   }
 } catch { /* optional */ }
@@ -872,6 +892,25 @@ function persistDocSessions() {
   safeWrite(DOC_SESSIONS_PATH, obj);
 }
 
+// Debounced variant — coalesces rapid writes (e.g. back-to-back doc-chat turns)
+let _persistDocSessionsTimer = null;
+function schedulePersistDocSessions() {
+  if (_persistDocSessionsTimer) clearTimeout(_persistDocSessionsTimer);
+  _persistDocSessionsTimer = setTimeout(() => {
+    _persistDocSessionsTimer = null;
+    persistDocSessions();
+  }, 5000); // 5s debounce — rapid turns produce one write per burst
+}
+
+/** Flush any pending debounced write immediately (call on shutdown). */
+function flushPendingDocSessions() {
+  if (_persistDocSessionsTimer) {
+    clearTimeout(_persistDocSessionsTimer);
+    _persistDocSessionsTimer = null;
+    persistDocSessions();
+  }
+}
+
 // Resolve session from any store (CC global or doc-specific)
 function resolveSession(store, key) {
   if (store === 'cc') {
@@ -885,6 +924,11 @@ function resolveSession(store, key) {
     persistDocSessions();
     return null;
   }
+  if (s.lastActiveAt && Date.now() - new Date(s.lastActiveAt).getTime() > DOC_SESSION_TTL_MS) {
+    docSessions.delete(key);
+    persistDocSessions();
+    return null;
+  }
   return s;
 }
 
@@ -909,7 +953,7 @@ function updateSession(store, key, sessionId, existing) {
       turnCount: (existing && prev ? prev.turnCount : 0) + 1,
       _docHash: prev?._docHash || null,
     });
-    persistDocSessions();
+    schedulePersistDocSessions();
   }
 }
 
@@ -972,7 +1016,7 @@ async function ccCall(message, { store = 'cc', sessionKey, extraContext, label =
       safeWrite(path.join(ENGINE_DIR, 'cc-session.json'), ccSession);
     } else if (sessionKey) {
       docSessions.delete(sessionKey);
-      persistDocSessions();
+      schedulePersistDocSessions();
     }
   }
 
@@ -1007,6 +1051,12 @@ async function ccCall(message, { store = 'cc', sessionKey, extraContext, label =
   return result;
 }
 
+// Lightweight content fingerprint — same algorithm used browser-side (no crypto needed)
+function contentFingerprint(str) {
+  if (!str) return '';
+  return str.length + ':' + str.charCodeAt(0) + ':' + str.charCodeAt(str.length - 1);
+}
+
 // Doc-specific wrapper — adds document context, parses ---DOCUMENT---
 async function ccDocCall({ message, document, title, filePath, selection, canEdit, isJson, model, freshSession, onAbortReady }) {
   const sessionKey = filePath || title;
@@ -1047,7 +1097,7 @@ async function ccDocCall({ message, document, title, filePath, selection, canEdi
     // One-shot call — discard the session ccCall just stored so it cannot
     // bleed into future interactions under the same key.
     docSessions.delete(sessionKey);
-    persistDocSessions();
+    schedulePersistDocSessions();
   } else if (result.code === 0 && result.sessionId) {
     // Store doc hash for next call's unchanged check
     const session = resolveSession('doc', sessionKey);
@@ -3221,7 +3271,14 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         try { shared.sanitizePath(body.filePath, MINIONS_DIR); } catch { return jsonReply(res, 400, { error: 'path must be under minions directory' }); }
         fullPath = path.resolve(MINIONS_DIR, body.filePath);
         const diskContent = safeRead(fullPath);
-        if (diskContent !== null) currentContent = diskContent;
+        if (diskContent !== null) {
+          // If client sent a contentHash and it matches disk, skip replacement — client copy is fresh
+          if (body.contentHash && contentFingerprint(diskContent) === body.contentHash) {
+            // body.document is already current — no override needed
+          } else {
+            currentContent = diskContent;
+          }
+        }
       }
 
       const { answer, content, actions } = await ccDocCall({
@@ -4741,7 +4798,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     { method: 'GET', path: /^\/api\/knowledge\/([^/]+)\/([^?]+)/, desc: 'Read a specific knowledge base entry', handler: handleKnowledgeRead },
 
     // Doc chat
-    { method: 'POST', path: '/api/doc-chat', desc: 'Minions-aware doc Q&A + editing via CC session', params: 'message, document, title?, filePath?, selection?', handler: handleDocChat },
+    { method: 'POST', path: '/api/doc-chat', desc: 'Minions-aware doc Q&A + editing via CC session', params: 'message, document, title?, filePath?, selection?, contentHash?', handler: handleDocChat },
 
     // Inbox
     { method: 'POST', path: '/api/inbox/persist', desc: 'Promote an inbox item to team notes', params: 'name', handler: handleInboxPersist },
@@ -5102,3 +5159,8 @@ server.on('error', e => {
   }
   process.exit(1);
 });
+
+// ── Graceful shutdown: flush debounced writes ──────────────────────────────
+server.on('close', () => flushPendingDocSessions());
+process.on('SIGTERM', () => { flushPendingDocSessions(); process.exit(0); });
+process.on('SIGINT', () => { flushPendingDocSessions(); process.exit(0); });

package/engine/cli.js

@@ -51,6 +51,18 @@ function handleCommand(cmd, args) {
 
 const commands = {
   start() {
+    // Startup state-file size guard (#1167): dispatch.json / cooldowns.json
+    // bloated past 100 MB silently OOMed V8 on JSON.parse at startup. Fail fast
+    // with an actionable message instead.
+    try {
+      for (const fp of [DISPATCH_PATH, path.join(ENGINE_DIR, 'cooldowns.json')]) {
+        shared.assertStateFileSize(fp);
+      }
+    } catch (stateErr) {
+      console.error('\n[engine] STARTUP ABORTED — ' + stateErr.message + '\n');
+      process.exit(78); // 78 = configuration error
+    }
+
     // Run preflight checks (warn but don't block — engine may still be useful)
     try {
       const { runPreflight, printPreflight } = require('./preflight');

package/engine/cooldown.js

@@ -10,6 +10,31 @@ const queries = require('./queries');
 const { safeJson, safeWrite, log, ENGINE_DEFAULTS } = shared;
 const { ENGINE_DIR } = queries;
 
+/**
+ * Truncate any string fields on a pendingContexts entry so a single huge PR
+ * comment / build log cannot bloat cooldowns.json to hundreds of MB (#1167).
+ * Returns a new entry object (does not mutate the caller's copy).
+ */
+function _truncateContextEntry(entry, maxBytes) {
+  if (entry == null) return entry;
+  const limit = Number(maxBytes) > 0 ? Number(maxBytes) : ENGINE_DEFAULTS.maxPendingContextEntryBytes;
+  if (typeof entry === 'string') {
+    return Buffer.byteLength(entry, 'utf8') > limit
+      ? entry.slice(0, limit) + `\n\n... [truncated: context exceeded ${Math.round(limit / 1024)} KB]`
+      : entry;
+  }
+  if (typeof entry !== 'object') return entry;
+  const out = Array.isArray(entry) ? [] : {};
+  for (const [k, v] of Object.entries(entry)) {
+    if (typeof v === 'string' && Buffer.byteLength(v, 'utf8') > limit) {
+      out[k] = v.slice(0, limit) + `\n\n... [truncated: ${k} exceeded ${Math.round(limit / 1024)} KB]`;
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
 const COOLDOWN_PATH = path.join(ENGINE_DIR, 'cooldowns.json');
 const dispatchCooldowns = new Map(); // key → { timestamp, failures }
 
@@ -39,9 +64,15 @@ function saveCooldowns() {
     }
     // Trim pendingContexts arrays before writing to prevent bloat
     const cap = ENGINE_DEFAULTS.maxPendingContexts;
+    const entryLimit = ENGINE_DEFAULTS.maxPendingContextEntryBytes;
     for (const [, v] of dispatchCooldowns) {
-      if (Array.isArray(v.pendingContexts) && v.pendingContexts.length > cap) {
-        v.pendingContexts = v.pendingContexts.slice(-cap);
+      if (Array.isArray(v.pendingContexts)) {
+        if (v.pendingContexts.length > cap) {
+          v.pendingContexts = v.pendingContexts.slice(-cap);
+        }
+        // Also truncate oversized individual entries — #1167 showed
+        // 20 entries × 25 MB each still produced a 500 MB cooldowns.json.
+        v.pendingContexts = v.pendingContexts.map(e => _truncateContextEntry(e, entryLimit));
       }
     }
     const obj = Object.fromEntries(dispatchCooldowns);
@@ -69,7 +100,12 @@ function setCooldown(key) {
 function setCooldownWithContext(key, context) {
   const existing = dispatchCooldowns.get(key);
   let pendingContexts = existing?.pendingContexts || [];
-  if (context) pendingContexts.push(context);
+  if (context) {
+    // Truncate oversized string fields per-entry BEFORE storing so a single
+    // huge payload (PR diff, build log, full repo dump) cannot bloat
+    // cooldowns.json regardless of array cap (#1167).
+    pendingContexts.push(_truncateContextEntry(context, ENGINE_DEFAULTS.maxPendingContextEntryBytes));
+  }
   // Cap to last N entries to prevent unbounded growth (cooldowns.json bloat)
   const cap = ENGINE_DEFAULTS.maxPendingContexts;
   if (pendingContexts.length > cap) pendingContexts = pendingContexts.slice(-cap);

package/engine/dispatch.js

@@ -11,6 +11,7 @@ const { setCooldownFailure } = require('./cooldown');
 
 const { safeJson, safeWrite, safeReadDir, mutateJsonFileLocked, mutateWorkItems,
   mutatePullRequests, getProjects, projectWorkItemsPath, projectPrPath, log, ts, dateStamp,
+  sidecarDispatchPrompt, deleteDispatchPromptSidecar,
   WI_STATUS, DISPATCH_RESULT, ENGINE_DEFAULTS, AGENT_STATUS, FAILURE_CLASS } = shared;
 const { getConfig, getDispatch, DISPATCH_PATH, INBOX_DIR } = queries;
 
@@ -24,13 +25,34 @@ function recovery() { if (!_recovery) _recovery = require('./recovery'); return
 
 // ─── Dispatch Mutation ───────────────────────────────────────────────────────
 
+/**
+ * Sweep pending + active dispatch entries and move any oversized prompts to
+ * sidecar files. Keeps dispatch.json from bloating to hundreds of MB when
+ * fix-type prompts inline PR diffs / build logs / coalesced feedback (#1167).
+ * Safe to call on every mutation: small prompts are untouched.
+ */
+function _sidecarOversizedPrompts(dispatch) {
+  const threshold = ENGINE_DEFAULTS.maxDispatchPromptBytes;
+  const lists = [dispatch.pending, dispatch.active];
+  for (const list of lists) {
+    if (!Array.isArray(list)) continue;
+    for (const item of list) {
+      if (item && typeof item.prompt === 'string') sidecarDispatchPrompt(item, threshold);
+    }
+  }
+}
+
 function mutateDispatch(mutator) {
   const defaultDispatch = { pending: [], active: [], completed: [] };
   const result = mutateJsonFileLocked(DISPATCH_PATH, (dispatch) => {
     dispatch.pending = Array.isArray(dispatch.pending) ? dispatch.pending : [];
     dispatch.active = Array.isArray(dispatch.active) ? dispatch.active : [];
     dispatch.completed = Array.isArray(dispatch.completed) ? dispatch.completed : [];
-    return mutator(dispatch) ?? dispatch;
+    const next = mutator(dispatch) ?? dispatch;
+    // Prompt-size guard: runs on every write so a single bad item cannot bloat
+    // dispatch.json. Sidecars live in engine/contexts/<id>.md.
+    _sidecarOversizedPrompts(next);
+    return next;
   }, { defaultValue: defaultDispatch });
   // Invalidate the read cache so next getDispatch() sees fresh data
   try { require('./queries').invalidateDispatchCache(); } catch {}
@@ -116,7 +138,12 @@ function completeDispatch(id, result = DISPATCH_RESULT.SUCCESS, reason = '', res
     if (reason) item.reason = reason;
     if (resultSummary) item.resultSummary = resultSummary;
     if (failureClass && result === DISPATCH_RESULT.ERROR) item.failureClass = failureClass;
+    // Drop prompt (and sidecar file, if any) — completed entries don't need
+    // replayable content and it would accumulate forever (#1167).
+    try { deleteDispatchPromptSidecar(item); } catch { /* best-effort */ }
     delete item.prompt;
+    delete item._promptFile;
+    delete item._promptBytes;
     if (dispatch.completed.length >= 100) {
       dispatch.completed = dispatch.completed.slice(-100);
     }

package/engine/shared.js

@@ -162,6 +162,118 @@ function safeUnlink(p) {
   try { fs.unlinkSync(p); } catch { /* cleanup */ }
 }
 
+// ── Dispatch Prompt Sidecar (#1167) ─────────────────────────────────────────
+// Large prompts (PR diffs, build error logs, coalesced human feedback) inlined
+// into dispatch.json caused hundreds-of-MB bloat per entry and eventual V8 OOM
+// at startup. Sidecar files keep dispatch.json small while preserving full
+// content for the agent at spawn time.
+
+// Resolve lazily so MINIONS_TEST_DIR overrides work in tests.
+function _promptContextsDir() {
+  return path.join(MINIONS_DIR, 'engine', 'contexts');
+}
+// Keep the constant for callers that expect a stable export; callers that need
+// the current value (tests) should call _promptContextsDir().
+const PROMPT_CONTEXTS_DIR = _promptContextsDir();
+
+/** Absolute path to the sidecar prompt file for a given dispatch id. */
+function dispatchPromptSidecarPath(dispatchId) {
+  if (!dispatchId) return null;
+  const safeId = String(dispatchId).replace(/[^a-zA-Z0-9._-]/g, '-');
+  return path.join(_promptContextsDir(), `${safeId}.md`);
+}
+
+/**
+ * If the dispatch item's prompt exceeds thresholdBytes, write the full prompt
+ * to engine/contexts/<id>.md and replace `item.prompt` with a short stub
+ * + `_promptFile` reference. Mutates item in place and returns true when
+ * sidecaring happened, false otherwise.
+ */
+function sidecarDispatchPrompt(item, thresholdBytes) {
+  if (!item || typeof item.prompt !== 'string') return false;
+  const threshold = Number(thresholdBytes) > 0
+    ? Number(thresholdBytes)
+    : ENGINE_DEFAULTS.maxDispatchPromptBytes;
+  const byteLen = Buffer.byteLength(item.prompt, 'utf8');
+  if (byteLen <= threshold) return false;
+  if (!item.id) return false; // can't sidecar without a stable id
+  try {
+    const ctxDir = _promptContextsDir();
+    if (!fs.existsSync(ctxDir)) fs.mkdirSync(ctxDir, { recursive: true });
+    const sidecar = dispatchPromptSidecarPath(item.id);
+    safeWrite(sidecar, item.prompt);
+    const relPath = path.relative(MINIONS_DIR, sidecar).replace(/\\/g, '/');
+    item._promptFile = relPath;
+    item._promptBytes = byteLen;
+    item.prompt = `[Prompt sidecarred to ${relPath} — ${Math.round(byteLen / 1024)} KB. The engine reads the sidecar when spawning this agent.]`;
+    try { log('warn', `Sidecarred oversized dispatch prompt: ${item.id} (${Math.round(byteLen / 1024)} KB → ${relPath})`); } catch { /* logger may not be ready */ }
+    return true;
+  } catch (e) {
+    try { log('warn', `sidecarDispatchPrompt failed for ${item.id}: ${e.message}`); } catch { /* cleanup */ }
+    return false;
+  }
+}
+
+/**
+ * Read the effective prompt for a dispatch item. Prefers the sidecar file when
+ * `_promptFile` is set so spawnAgent always sees the full prompt even though
+ * dispatch.json only stores a small stub.
+ */
+function resolveDispatchPrompt(item) {
+  if (!item) return '';
+  if (item._promptFile) {
+    const candidates = [
+      path.isAbsolute(item._promptFile) ? item._promptFile : path.resolve(MINIONS_DIR, item._promptFile),
+      dispatchPromptSidecarPath(item.id),
+    ].filter(Boolean);
+    for (const c of candidates) {
+      try {
+        const content = fs.readFileSync(c, 'utf8');
+        if (content) return content;
+      } catch { /* try next candidate */ }
+    }
+  }
+  return item.prompt || '';
+}
+
+/** Remove the sidecar prompt file for a completed/cancelled dispatch. */
+function deleteDispatchPromptSidecar(item) {
+  if (!item) return;
+  const paths = new Set();
+  if (item._promptFile) {
+    paths.add(path.isAbsolute(item._promptFile) ? item._promptFile : path.resolve(MINIONS_DIR, item._promptFile));
+  }
+  const idPath = dispatchPromptSidecarPath(item.id);
+  if (idPath) paths.add(idPath);
+  for (const p of paths) safeUnlink(p);
+}
+
+/**
+ * Startup guard: throw a clear error when a state file has grown past
+ * maxStateFileBytes. Without this the dashboard silently OOMs on JSON.parse
+ * (seen on a 491 MB dispatch.json + 509 MB cooldowns.json — #1167).
+ * The thrown error points at the bloated file so operators can act instead
+ * of chasing V8 heap traces.
+ */
+function assertStateFileSize(filePath, maxBytes) {
+  const limit = Number(maxBytes) > 0 ? Number(maxBytes) : ENGINE_DEFAULTS.maxStateFileBytes;
+  try {
+    const stat = fs.statSync(filePath);
+    if (stat.size > limit) {
+      throw new Error(
+        `State file too large: ${filePath} is ${Math.round(stat.size / (1024 * 1024))} MB ` +
+        `(limit ${Math.round(limit / (1024 * 1024))} MB). ` +
+        `This usually means dispatch prompts or cooldown contexts were inlined and not sidecarred. ` +
+        `Inspect/trim the file manually, then restart. See engine/contexts/ for sidecar files.`
+      );
+    }
+  } catch (e) {
+    if (e.code === 'ENOENT') return; // file absent is fine
+    if (e.message && e.message.startsWith('State file too large:')) throw e;
+    // Other stat errors (permission etc.) — do not block startup
+  }
+}
+
 function sleepMs(ms) {
   try {
     const ab = new SharedArrayBuffer(4);
@@ -571,6 +683,9 @@ const ENGINE_DEFAULTS = {
   ccEffort: null, // effort level for CC/doc-chat (null, 'low', 'medium', 'high')
   heartbeatTimeouts: {}, // populated after WORK_TYPE is defined (below)
   maxPendingContexts: 20, // cap pendingContexts arrays in cooldowns.json to prevent unbounded growth
+  maxPendingContextEntryBytes: 256 * 1024, // 256 KB — cap each pendingContexts entry to prevent huge PR comments from bloating cooldowns.json
+  maxDispatchPromptBytes: 1024 * 1024, // 1 MB — dispatch items with prompts larger than this sidecar to engine/contexts/ to prevent dispatch.json OOM (#1167)
+  maxStateFileBytes: 100 * 1024 * 1024, // 100 MB — fail startup with a clear error when dispatch.json / cooldowns.json exceed this, rather than silently OOMing on JSON.parse (#1167)
   ccMaxTurns: 50, // max tool-use turns for CC/doc-chat before CLI stops
   // Teams integration — config.teams shape: { enabled, appId, appPassword, certPath, privateKeyPath, tenantId, notifyEvents, ccMirror, inboxPollInterval }
   // Auth modes: (1) appId + appPassword (client secret), or (2) appId + certPath + privateKeyPath + tenantId (certificate)
@@ -1399,6 +1514,12 @@ module.exports = {
   safeJson, safeJsonObj, safeJsonArr,
   safeWrite,
   safeUnlink,
+  PROMPT_CONTEXTS_DIR,
+  dispatchPromptSidecarPath,
+  sidecarDispatchPrompt,
+  resolveDispatchPrompt,
+  deleteDispatchPromptSidecar,
+  assertStateFileSize,
   withFileLock,
   mutateJsonFileLocked,
   mutateWorkItems,

package/engine.js

@@ -355,7 +355,11 @@ async function recoverPartialWorktree(rootDir, worktreePath, branchName, gitOpts
 }
 
 async function spawnAgent(dispatchItem, config) {
-  const { id, agent: agentId, prompt: taskPrompt, type, meta } = dispatchItem;
+  const { id, agent: agentId, type, meta } = dispatchItem;
+  // Resolve prompt — prefers sidecar file when dispatchItem._promptFile is set
+  // (large prompts are written to engine/contexts/<id>.md to keep dispatch.json
+  // small — see shared.sidecarDispatchPrompt / #1167).
+  const taskPrompt = shared.resolveDispatchPrompt(dispatchItem);
   const claudeConfig = config.claude || {};
   const engineConfig = config.engine || {};
   const startedAt = ts();

package/package.json

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