@yemi33/minions 0.1.1034 → 0.1.1035

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # 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

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);

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.1034",
+  "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"