@yemi33/minions 0.1.1736 → 0.1.1738

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.1.1738 (2026-05-06)
+
+### Features
+- add feature-flag registry for experimental UX gates
+- graceful runtime-switch reset with transcript carryover
+
+### Fixes
+- prevent hung callLLM Promises when child stdio doesn't drain
+
+### Other
+- chore(gitignore): ignore root-level config.json.backup sidecar
+
+## 0.1.1737 (2026-05-05)
+
+### Other
+- perf: buffered metrics, snapshot-diff sidecar, parallel worktree branch probes
+
 ## 0.1.1736 (2026-05-05)
 
 ### Other

package/dashboard/js/command-center.js

@@ -101,6 +101,26 @@ function _ccActiveTab() {
   return _ccTabs.find(function(t) { return t.id === _ccActiveTabId; }) || null;
 }
 
+// Build a plain-text transcript from a tab's stored messages — sent on every
+// initial request so the server can carry it over if the session has to reset
+// (runtime switch, system-prompt change). Last 20 user/assistant turns only;
+// system/action rows are skipped because they're UI artifacts, not dialog.
+var CC_TRANSCRIPT_MAX_TURNS = 20;
+function _ccBuildTranscript(tab) {
+  if (!tab || !Array.isArray(tab.messages) || tab.messages.length === 0) return [];
+  var out = [];
+  for (var i = 0; i < tab.messages.length; i++) {
+    var m = tab.messages[i];
+    if (!m || (m.role !== 'user' && m.role !== 'assistant')) continue;
+    var html = typeof m.html === 'string' ? m.html : '';
+    var tmp = document.createElement('div');
+    tmp.innerHTML = html;
+    var text = (tmp.textContent || tmp.innerText || '').trim();
+    if (text) out.push({ role: m.role, text: text });
+  }
+  return out.slice(-CC_TRANSCRIPT_MAX_TURNS);
+}
+
 function _ccMergeStreamText(prev, incoming) {
   // `prev` is already merged-clean from prior frames (server strips actions
   // before SSE emission, and any leaked partial was sanitized by the previous
@@ -756,7 +776,15 @@ async function _ccDoSend(message, skipUserMsg, forceTabId) {
         terminalEventSeen = true;
         _cleanupStreamDiv();
         if (evt.sessionReset) {
-          addMsg('system', '<div style="text-align:center;padding:6px 12px;font-size:11px;color:var(--muted);background:var(--surface2);border-radius:6px;margin:4px 0">Minions was updated — started a fresh session with latest context.</div>', false, activeTabId);
+          var resetText;
+          if (evt.sessionResetReason === 'runtimeChanged' && evt.previousRuntime && evt.currentRuntime) {
+            resetText = 'Runtime switched (' + escHtml(evt.previousRuntime) + ' → ' + escHtml(evt.currentRuntime) + ') — started a fresh session and carried over recent history.';
+          } else if (evt.sessionResetReason === 'promptChanged') {
+            resetText = 'Minions was updated — started a fresh session and carried over recent history.';
+          } else {
+            resetText = 'Minions was updated — started a fresh session with latest context.';
+          }
+          addMsg('system', '<div style="text-align:center;padding:6px 12px;font-size:11px;color:var(--muted);background:var(--surface2);border-radius:6px;margin:4px 0">' + resetText + '</div>', false, activeTabId);
         }
         var finalText = _ccMergeStreamText(streamedText, evt.text || '');
         var rendered = renderMd(finalText || streamedText || '');
@@ -824,7 +852,7 @@ async function _ccDoSend(message, skipUserMsg, forceTabId) {
     while (true) {
       var consume = await _ccConsumeStream(
         reconnectAttempts === 0
-          ? { message: message, tabId: activeTabId, sessionId: activeTab.sessionId || null }
+          ? { message: message, tabId: activeTabId, sessionId: activeTab.sessionId || null, transcript: _ccBuildTranscript(activeTab) }
           : { tabId: activeTabId, sessionId: activeTab.sessionId || null, reconnect: true },
         reconnectAttempts > 0
       );

package/dashboard/js/features-client.js

@@ -0,0 +1,16 @@
+// features-client.js — Client-side feature flag accessor.
+// Reads `window.MINIONS_FEATURES` (data injected at HTML build time:
+// { flags: {id: bool}, defaults: {id: bool} }) and exposes synchronous
+// `MinionsFeatures.isOn(id)` so gated render code can branch without async.
+
+window.MinionsFeatures = {
+  isOn: function(id) {
+    var f = window.MINIONS_FEATURES || { flags: {}, defaults: {} };
+    if (Object.prototype.hasOwnProperty.call(f.flags, id)) return f.flags[id] === true;
+    return f.defaults && f.defaults[id] === true;
+  },
+  _setLocal: function(id, enabled) {
+    if (!window.MINIONS_FEATURES) window.MINIONS_FEATURES = { flags: {}, defaults: {} };
+    window.MINIONS_FEATURES.flags[id] = enabled === true;
+  },
+};

package/dashboard/js/settings.js

@@ -28,10 +28,18 @@ async function openSettings() {
 
   _settingsData = null;
   let data;
+  let featuresList = [];
   try {
-    const res = await fetch('/api/settings');
-    data = await res.json();
+    const [settingsRes, featuresRes] = await Promise.all([
+      fetch('/api/settings'),
+      fetch('/api/features').catch(() => null),
+    ]);
+    data = await settingsRes.json();
     _settingsData = data;
+    if (featuresRes && featuresRes.ok) {
+      const fjson = await featuresRes.json().catch(() => null);
+      if (fjson && Array.isArray(fjson.features)) featuresList = fjson.features;
+    }
   } catch (e) { showToast('cmd-toast', 'Failed to load settings: ' + e.message, false); return; }
 
   const e = data.engine || {};
@@ -276,6 +284,36 @@ async function openSettings() {
     '<h3 style="font-size:13px;color:var(--blue);margin-bottom:8px">Routing Table</h3>' +
     '<textarea id="set-routing" rows="12" style="width:100%;padding:8px;background:var(--surface);border:1px solid var(--border);border-radius:4px;color:var(--text);font-family:monospace;font-size:11px;resize:vertical">' + escHtml(data.routing || '') + '</textarea>' +
 
+    // Toggles persist immediately via POST /api/features/toggle — no Save needed.
+    '<details id="settings-features-details" style="margin-top:16px;border-top:1px solid var(--border);padding-top:12px">' +
+      '<summary style="cursor:pointer;font-size:13px;color:var(--blue);user-select:none">Show experimental flags ' +
+        '<span style="font-size:10px;color:var(--muted)">(' + featuresList.length + ' registered)</span>' +
+      '</summary>' +
+      '<div style="font-size:10px;color:var(--muted);margin:8px 0 10px">In-progress UX or behavior gates. Toggles persist immediately. Registry: <code>engine/features.js</code>. Env override: <code>MINIONS_FEATURE_&lt;NAME&gt;=1</code>.</div>' +
+      (featuresList.length === 0
+        ? '<div style="font-size:11px;color:var(--muted);padding:12px;border:1px dashed var(--border);border-radius:4px;text-align:center">No experimental features registered. Add entries to <code>engine/features.js</code> to gate new work.</div>'
+        : '<div style="display:flex;flex-direction:column;gap:8px">' +
+          featuresList.map(function(f) {
+            const checked = f.enabled ? ' checked' : '';
+            const expiredBadge = f.expired
+              ? ' <span style="font-size:9px;padding:1px 5px;background:rgba(220,80,80,0.15);color:var(--red);border-radius:3px;margin-left:4px">EXPIRED</span>'
+              : '';
+            const meta = [];
+            if (f.addedIn) meta.push('added in ' + escHtml(f.addedIn));
+            if (f.expires) meta.push('expires ' + escHtml(f.expires));
+            meta.push(f.default ? 'default: on' : 'default: off');
+            return '<label data-feature-id="' + escHtml(f.id) + '" style="display:flex;align-items:flex-start;gap:8px;padding:8px;border:1px solid var(--border);border-radius:4px;cursor:pointer">' +
+              '<input type="checkbox" data-feature-toggle="' + escHtml(f.id) + '"' + checked + ' style="margin-top:3px;cursor:pointer">' +
+              '<div style="flex:1">' +
+                '<div style="font-size:11px;font-weight:600;color:var(--text)">' + escHtml(f.id) + expiredBadge + '</div>' +
+                (f.description ? '<div style="font-size:10px;color:var(--muted);margin-top:2px">' + escHtml(f.description) + '</div>' : '') +
+                '<div style="font-size:9px;color:var(--muted);margin-top:3px">' + meta.join(' · ') + '</div>' +
+              '</div>' +
+            '</label>';
+          }).join('') +
+        '</div>') +
+    '</details>' +
+
   '</div>';
 
   document.getElementById('modal-title').textContent = 'Settings';
@@ -312,6 +350,34 @@ async function openSettings() {
   // 3. On defaultCli change → re-fetch models so the input never shows stale list.
   // The same pattern wires ccCli → ccModel; ccCli inherits defaultCli when unset.
   initRuntimeFleetUI(e, agents);
+
+  document.querySelectorAll('input[data-feature-toggle]').forEach(function(input) {
+    input.addEventListener('change', async function() {
+      const id = input.getAttribute('data-feature-toggle');
+      const enabled = input.checked;
+      if (window.MinionsFeatures && typeof window.MinionsFeatures._setLocal === 'function') {
+        window.MinionsFeatures._setLocal(id, enabled);
+      }
+      try {
+        const r = await fetch('/api/features/toggle', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ id, enabled }),
+        });
+        if (!r.ok) {
+          const j = await r.json().catch(() => ({}));
+          throw new Error(j.error || ('HTTP ' + r.status));
+        }
+        showToast('cmd-toast', 'Feature "' + id + '" ' + (enabled ? 'enabled' : 'disabled'), true);
+      } catch (err) {
+        input.checked = !enabled;
+        if (window.MinionsFeatures && typeof window.MinionsFeatures._setLocal === 'function') {
+          window.MinionsFeatures._setLocal(id, !enabled);
+        }
+        showToast('cmd-toast', 'Failed to toggle "' + id + '": ' + err.message, false);
+      }
+    });
+  });
 }
 
 async function initRuntimeFleetUI(engineCfg, agentsCfg) {

package/dashboard-build.js

@@ -29,7 +29,7 @@ function buildDashboardHtml() {
   }
 
   const jsFiles = [
-    'utils', 'state', 'detail-panel', 'live-stream',
+    'utils', 'state', 'features-client', 'detail-panel', 'live-stream',
     'render-agents', 'render-dispatch', 'render-work-items', 'render-prd',
     'render-prs', 'render-plans', 'render-inbox', 'render-kb', 'render-skills',
     'render-other', 'render-schedules', 'render-watches', 'render-pipelines', 'render-meetings', 'render-pinned',

package/dashboard.js

@@ -30,6 +30,7 @@ const playbook = require('./engine/playbook');
 const dispatchMod = require('./engine/dispatch');
 const steering = require('./engine/steering');
 const projectDiscovery = require('./engine/project-discovery');
+const features = require('./engine/features');
 const os = require('os');
 
 const { safeRead, safeReadDir, safeWrite, safeJson, safeJsonObj, safeJsonArr, safeUnlink, mutateJsonFileLocked, mutateControl, mutateCooldowns, mutateWorkItems, getProjects: _getProjects, DONE_STATUSES, WI_STATUS, WORK_TYPE, reopenWorkItem } = shared;
@@ -448,7 +449,7 @@ function buildDashboardHtml() {
 
   // Assemble JS modules (order matters: utils → state → renderers → commands → refresh)
   const jsFiles = [
-    'utils', 'state', 'render-utils', 'detail-panel', 'live-stream',
+    'utils', 'state', 'features-client', 'render-utils', 'detail-panel', 'live-stream',
     'render-agents', 'render-dispatch', 'render-work-items', 'render-prd',
     'render-prs', 'render-plans', 'render-inbox', 'render-kb', 'render-skills',
     'render-other', 'render-schedules', 'render-watches', 'render-pipelines', 'render-meetings', 'render-pinned',
@@ -461,10 +462,23 @@ function buildDashboardHtml() {
     jsHtml += `\n// ─── ${f}.js ────────────────────────────────────────\n${content}\n`;
   }
 
+  // Snapshot feature-flag state at build time so the client renders synchronously
+  // without an extra /api/features round-trip. Helper itself lives in
+  // dashboard/js/features-client.js (auto-concatenated below).
+  let featuresBoot = { flags: {}, defaults: {} };
+  try {
+    for (const f of features.listFeatures(queries.getConfig())) {
+      featuresBoot.flags[f.id] = f.enabled;
+      featuresBoot.defaults[f.id] = f.default;
+    }
+  } catch { /* registry empty or config unreadable — ship empty boot state */ }
+
+  const featuresBootstrap = `window.MINIONS_FEATURES = ${JSON.stringify(featuresBoot)};\n`;
+
   return layout
     .replace('/* __CSS__ */', () => css)
     .replace('<!-- __PAGES__ -->', () => pageHtml)
-    .replace('/* __JS__ */', () => `window.__MINIONS_HOME = ${JSON.stringify(os.homedir())};\n${jsHtml}`);
+    .replace('/* __JS__ */', () => `window.__MINIONS_HOME = ${JSON.stringify(os.homedir())};\n${featuresBootstrap}${jsHtml}`);
 }
 
 let HTML_RAW = buildDashboardHtml();
@@ -1121,6 +1135,28 @@ function _readCcTabSessions({ prune = true } = {}) {
   return sessions;
 }
 
+const CC_CARRYOVER_MAX_TURNS = 20;
+const CC_CARRYOVER_PER_MSG_CHARS = 2000;
+
+function _buildTranscriptCarryover(transcript, { previousRuntime } = {}) {
+  if (!Array.isArray(transcript) || transcript.length === 0) return '';
+  const filtered = transcript.filter(m => m && (m.role === 'user' || m.role === 'assistant') && typeof m.text === 'string' && m.text.trim());
+  if (filtered.length === 0) return '';
+  const recent = filtered.slice(-CC_CARRYOVER_MAX_TURNS);
+  const truncated = filtered.length > recent.length;
+  const header = previousRuntime
+    ? `--- Previous conversation (carried over from ${previousRuntime} session) ---`
+    : `--- Previous conversation (carried over) ---`;
+  const lines = recent.map(m => {
+    const who = m.role === 'user' ? 'User' : 'Assistant';
+    let text = m.text.trim();
+    if (text.length > CC_CARRYOVER_PER_MSG_CHARS) text = text.slice(0, CC_CARRYOVER_PER_MSG_CHARS) + '… [truncated]';
+    return `${who}: ${text}`;
+  });
+  const truncationNote = truncated ? `[earlier messages truncated — showing last ${recent.length} of ${filtered.length}]\n\n` : '';
+  return `${header}\n\n${truncationNote}${lines.join('\n\n')}\n\n--- Current message follows ---`;
+}
+
 // Load persisted CC session on startup
 try {
   const saved = safeJson(path.join(ENGINE_DIR, 'cc-session.json'));
@@ -5513,7 +5549,10 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         // Session management — per-tab: use sessionId from request, don't mutate global ccSession
         let tabSessionId = body.sessionId || null;
         let sessionReset = false;
-        // If system prompt changed since this session was created, force a fresh session
+        let sessionResetReason = null;
+        let previousRuntime = null;
+        const currentRuntime = shared.resolveCcCli(CONFIG.engine);
+        // If system prompt or runtime changed since this session was created, force a fresh session
         if (tabSessionId) {
           const sessions = _readCcTabSessions();
           const tabEntry = sessions.find(s => s.id === (body.tabId || 'default'));
@@ -5523,12 +5562,19 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           } else if (tabEntry._promptHash && tabEntry._promptHash !== _ccPromptHash) {
             tabSessionId = null;
             sessionReset = true;
+            sessionResetReason = 'promptChanged';
+          } else if (tabEntry.runtime && tabEntry.runtime !== currentRuntime) {
+            tabSessionId = null;
+            sessionReset = true;
+            sessionResetReason = 'runtimeChanged';
+            previousRuntime = tabEntry.runtime;
           }
         }
         const wasResume = !!tabSessionId;
         const sessionId = tabSessionId || null;
         const preamble = wasResume ? '' : buildCCStatePreamble();
-        const prompt = (preamble ? preamble + '\n\n---\n\n' : '') + body.message;
+        const carryover = sessionReset ? _buildTranscriptCarryover(body.transcript, { previousRuntime }) : '';
+        const prompt = (preamble ? preamble + '\n\n---\n\n' : '') + (carryover ? carryover + '\n\n---\n\n' : '') + body.message;
 
         const { trackEngineUsage: trackUsage } = require('./engine/llm');
         const streamModel = CONFIG.engine?.ccModel || shared.ENGINE_DEFAULTS.ccModel;
@@ -5606,8 +5652,9 @@ What would you like to discuss or change? When you're happy, say "approve" and I
               existing.turnCount = sessionReset ? 1 : (existing.turnCount || 0) + 1;
               existing.preview = preview;
               existing._promptHash = _ccPromptHash;
+              existing.runtime = currentRuntime;
             } else {
-              sessions.push({ id: _persistTabId, title: (body.message || 'New chat').slice(0, 40), sessionId: responseSessionId, createdAt: new Date(now).toISOString(), lastActiveAt: new Date(now).toISOString(), turnCount: 1, preview, _promptHash: _ccPromptHash });
+              sessions.push({ id: _persistTabId, title: (body.message || 'New chat').slice(0, 40), sessionId: responseSessionId, createdAt: new Date(now).toISOString(), lastActiveAt: new Date(now).toISOString(), turnCount: 1, preview, _promptHash: _ccPromptHash, runtime: currentRuntime });
             }
             safeWrite(CC_SESSIONS_PATH, sessions);
           } catch { /* non-critical */ }
@@ -5630,7 +5677,12 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         // Issue #1834: surface action JSON parse failures so the UI can warn
         // instead of silently dropping. Client renders this as a small notice.
         if (_actionParseError) donePayload.actionParseError = _actionParseError;
-        if (sessionReset) donePayload.sessionReset = true;
+        if (sessionReset) {
+          donePayload.sessionReset = true;
+          if (sessionResetReason) donePayload.sessionResetReason = sessionResetReason;
+          if (previousRuntime) donePayload.previousRuntime = previousRuntime;
+          donePayload.currentRuntime = currentRuntime;
+        }
         liveState.donePayload = donePayload;
         if (liveState.writer) liveState.writer(donePayload);
 
@@ -6253,6 +6305,33 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     } catch (e) { return jsonReply(res, e.statusCode || 500, { error: e.message }); }
   }
 
+  async function handleFeaturesList(req, res) {
+    try {
+      return jsonReply(res, 200, { features: features.listFeatures(CONFIG) });
+    } catch (e) { return jsonReply(res, e.statusCode || 500, { error: e.message }); }
+  }
+
+  async function handleFeaturesToggle(req, res) {
+    try {
+      const body = await readBody(req);
+      const id = body && typeof body.id === 'string' ? body.id.trim() : '';
+      if (!id) return jsonReply(res, 400, { error: 'id required' });
+      if (!features.hasFeature(id)) {
+        return jsonReply(res, 404, { error: `Unknown feature flag: "${id}". Register it in engine/features.js.` });
+      }
+      const enabled = body.enabled === true;
+      const configPath = path.join(MINIONS_DIR, 'config.json');
+      mutateJsonFileLocked(configPath, (cfg) => {
+        if (!cfg.features || typeof cfg.features !== 'object') cfg.features = {};
+        cfg.features[id] = enabled;
+        return cfg;
+      });
+      reloadConfig();
+      invalidateStatusCache();
+      return jsonReply(res, 200, { ok: true, id, enabled });
+    } catch (e) { return jsonReply(res, e.statusCode || 500, { error: e.message }); }
+  }
+
   async function handleHealth(req, res) {
     const engine = getEngineState();
     const agents = getAgents();
@@ -7043,6 +7122,10 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     { method: 'POST', path: '/api/settings/routing', desc: 'Update routing.md', params: 'content', handler: handleSettingsRouting },
     { method: 'POST', path: '/api/settings/reset', desc: 'Reset engine + claude + agent settings to defaults', handler: handleSettingsReset },
 
+    // Feature flags (experimental / in-progress UX gates — see engine/features.js)
+    { method: 'GET', path: '/api/features', desc: 'List registered feature flags with current enabled state', handler: handleFeaturesList },
+    { method: 'POST', path: '/api/features/toggle', desc: 'Enable/disable a registered feature flag', params: 'id, enabled', handler: handleFeaturesToggle },
+
     // Teams Bot Framework webhook
     { method: 'POST', path: '/api/bot', desc: 'Bot Framework webhook for Teams integration', handler: handleTeamsBot },
   ];

package/engine/cleanup.js

@@ -8,7 +8,7 @@ const path = require('path');
 const shared = require('./shared');
 const queries = require('./queries');
 
-const { exec, execSilent, log, ts, ENGINE_DEFAULTS } = shared;
+const { exec, execAsync, execSilent, log, ts, ENGINE_DEFAULTS } = shared;
 const { safeJson, safeWrite, safeReadDir, mutateCooldowns, mutateWorkItems, mutateJsonFileLocked, getProjects, projectWorkItemsPath, projectPrPath,
   sanitizeBranch, KB_CATEGORIES } = shared;
 const { getDispatch, getAgentStatus } = queries;
@@ -56,6 +56,15 @@ function getWorktreeBranch(wtPath) {
   }
 }
 
+async function getWorktreeBranchAsync(wtPath) {
+  try {
+    const out = await execAsync(`git -C "${wtPath}" branch --show-current`, { encoding: 'utf8', timeout: 5000 });
+    return (out || '').toString().trim();
+  } catch {
+    return '';
+  }
+}
+
 let _orphanPidProcessNamesCache = null;
 function _orphanPidProcessNames() {
   if (_orphanPidProcessNamesCache) return _orphanPidProcessNamesCache;
@@ -134,7 +143,7 @@ function _killProcessInWorktree(dir, activeProcesses, activeIds) {
 
 // ─── Cleanup Orchestrator ────────────────────────────────────────────────────
 
-function runCleanup(config, verbose = false) {
+async function runCleanup(config, verbose = false) {
   const activeProcesses = engine().activeProcesses;
   const projects = getProjects(config);
   let cleaned = { tempFiles: 0, liveOutputs: 0, worktrees: 0, zombies: 0 };
@@ -248,11 +257,26 @@ function runCleanup(config, verbose = false) {
       const dispatch = getDispatch();
       const activeDispatchIds = new Set((dispatch.active || []).map(d => d.id));
 
+      // Probe `git branch --show-current` for every worktree in chunks of 5.
+      // Sequential probing was the dominant cost in the cleanup phase
+      // (5–15s tick stall every 10 ticks at 50+ worktrees), but unbounded
+      // Promise.all would spawn 50+ concurrent git children — bad on Windows
+      // where each fork pays AV-scan overhead. Mirrors engine/ado.js:611.
+      const BRANCH_PROBE_CONCURRENCY = 5;
+      const branchMap = new Map();
+      for (let i = 0; i < allDirs.length; i += BRANCH_PROBE_CONCURRENCY) {
+        const batch = allDirs.slice(i, i + BRANCH_PROBE_CONCURRENCY);
+        const pairs = await Promise.all(
+          batch.map(async ({ wtPath }) => [wtPath, await getWorktreeBranchAsync(wtPath)])
+        );
+        for (const [wtPath, branch] of pairs) branchMap.set(wtPath, branch);
+      }
+
       for (const { dir, wtPath } of allDirs) {
 
         let shouldClean = false;
         let isProtected = false;
-        const actualBranch = getWorktreeBranch(wtPath);
+        const actualBranch = branchMap.get(wtPath) || '';
 
         // Check if this worktree's branch is merged/abandoned
         // Prefer actual git branch metadata; compact Windows dirs intentionally omit branch names.

package/engine/cli.js

@@ -745,6 +745,16 @@ const commands = {
     }
     watchForWorkChanges();
 
+    // Drain in-memory buffers (metrics, logs) before any process.exit. Logs
+    // a stderr line if a flush fails so a refactor mistake (typo, missing
+    // export) doesn't go silent.
+    function drainBuffers() {
+      try { require('./llm').flushMetricsBuffer(); }
+      catch (err) { try { console.error(`[shutdown] flushMetricsBuffer failed: ${err.message}`); } catch {} }
+      try { shared.flushLogs(); }
+      catch (err) { try { console.error(`[shutdown] flushLogs failed: ${err.message}`); } catch {} }
+    }
+
     // Graceful shutdown — wait for active agents before exiting
     let shuttingDown = false;
     function gracefulShutdown(signal) {
@@ -768,7 +778,7 @@ const commands = {
           e.log('warn', 'Graceful shutdown skipped control.json stopped transition; control file is owned by a different engine process');
         }
         e.log('info', 'Graceful shutdown complete (no active agents)');
-        shared.flushLogs(); // drain buffered log entries before exit
+        drainBuffers();
         console.log('No active agents — stopped.');
         process.exit(0);
       }
@@ -785,7 +795,7 @@ const commands = {
             e.log('warn', 'Graceful shutdown skipped control.json stopped transition; control file is owned by a different engine process');
           }
           e.log('info', 'Graceful shutdown complete (all agents finished)');
-          shared.flushLogs(); // drain buffered log entries before exit
+          drainBuffers();
           console.log('All agents finished — stopped.');
           process.exit(0);
         }
@@ -796,7 +806,7 @@ const commands = {
             e.log('warn', 'Graceful shutdown skipped control.json stopped transition; control file is owned by a different engine process');
           }
           e.log('warn', `Graceful shutdown timed out after ${timeout / 1000}s with ${e.activeProcesses.size} agent(s) still active`);
-          shared.flushLogs(); // drain buffered log entries before exit
+          drainBuffers();
           console.log(`Shutdown timeout (${timeout / 1000}s) — force exiting with ${e.activeProcesses.size} agent(s) still running.`);
           process.exit(1);
         }
@@ -811,7 +821,7 @@ const commands = {
       const msg = reason instanceof Error ? reason.stack || reason.message : String(reason);
       console.error(`[FATAL] Unhandled promise rejection: ${msg}`);
       try { shared.log('fatal', `Unhandled promise rejection: ${msg}`); } catch { /* best effort */ }
-      try { shared.flushLogs(); } catch { /* best effort */ }
+      drainBuffers();
       process.exit(1);
     });
 
@@ -819,7 +829,7 @@ const commands = {
       const msg = err instanceof Error ? err.stack || err.message : String(err);
       console.error(`[FATAL] Uncaught exception: ${msg}`);
       try { shared.log('fatal', `Uncaught exception: ${msg}`); } catch { /* best effort */ }
-      try { shared.flushLogs(); } catch { /* best effort */ }
+      drainBuffers();
       process.exit(1);
     });
   },
@@ -1359,11 +1369,11 @@ const commands = {
     console.log(`\nDone: ${killed.length} dispatches killed, agents reset.`);
   },
 
-  cleanup() {
+  async cleanup() {
     const e = engine();
     const config = getConfig();
     console.log('\n=== Cleanup ===\n');
-    const result = e.runCleanup(config, true);
+    const result = await e.runCleanup(config, true);
     console.log(`\nDone: ${result.tempFiles} temp files, ${result.liveOutputs} live outputs, ${result.worktrees} worktrees, ${result.zombies} zombies cleaned.`);
   },
 

package/engine/copilot-models.json

@@ -1,5 +1,5 @@
 {
   "runtime": "copilot",
   "models": null,
-  "cachedAt": "2026-05-05T21:38:46.577Z"
+  "cachedAt": "2026-05-06T00:16:35.626Z"
 }

package/engine/dispatch.js

@@ -24,18 +24,35 @@ function lifecycle() { if (!_lifecycle) _lifecycle = require('./lifecycle'); ret
 // ─── 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.
+ * Walk pending + active dispatch entries and snapshot {id → prompt} for items
+ * that have a string prompt. Used to diff before/after a mutation so we only
+ * re-check items the mutator actually touched (#1167).
  */
-function _sidecarOversizedPrompts(dispatch) {
+function _snapshotPrompts(dispatch) {
+  const snap = new Map();
+  for (const list of [dispatch.pending, dispatch.active]) {
+    if (!Array.isArray(list)) continue;
+    for (const item of list) {
+      if (item && item.id && typeof item.prompt === 'string') snap.set(item.id, item.prompt);
+    }
+  }
+  return snap;
+}
+
+/**
+ * Sidecar oversized prompts only for items the mutator added or modified.
+ * Keeps dispatch.json safe from bloat (#1167) without paying O(n) on every
+ * unrelated mutation (e.g. status flips, completion-marking).
+ */
+function _sidecarChangedPrompts(dispatch, prevSnap) {
   const threshold = ENGINE_DEFAULTS.maxDispatchPromptBytes;
-  const lists = [dispatch.pending, dispatch.active];
-  for (const list of lists) {
+  for (const list of [dispatch.pending, dispatch.active]) {
     if (!Array.isArray(list)) continue;
     for (const item of list) {
-      if (item && typeof item.prompt === 'string') sidecarDispatchPrompt(item, threshold);
+      if (!item || typeof item.prompt !== 'string') continue;
+      const prev = item.id ? prevSnap.get(item.id) : undefined;
+      if (prev === item.prompt) continue; // untouched — already validated on insert
+      sidecarDispatchPrompt(item, threshold);
     }
   }
 }
@@ -46,10 +63,11 @@ function mutateDispatch(mutator) {
     dispatch.pending = Array.isArray(dispatch.pending) ? dispatch.pending : [];
     dispatch.active = Array.isArray(dispatch.active) ? dispatch.active : [];
     dispatch.completed = Array.isArray(dispatch.completed) ? dispatch.completed : [];
+    const prevSnap = _snapshotPrompts(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);
+    // Prompt-size guard: only scan items whose prompt changed (or new items),
+    // so a 100-item status-flip doesn't re-byte-count every prompt.
+    _sidecarChangedPrompts(next, prevSnap);
     return next;
   }, { defaultValue: defaultDispatch });
   // Invalidate the read cache so next getDispatch() sees fresh data

package/engine/features.js

@@ -0,0 +1,58 @@
+/**
+ * engine/features.js — Feature flag registry. Recipe in CLAUDE.md → "Feature Flags".
+ */
+
+// Entry shape: id → { description, default: bool, addedIn?: version, expires?: ISO-date }
+const FEATURES = {
+  // Example:
+  // 'ux-sidebar-v2': { description: '…', default: false, addedIn: '0.1.1738', expires: '2026-06-01' },
+};
+
+const ENV_TRUTHY = new Set(['1', 'true', 'on', 'yes']);
+const ENV_FALSY = new Set(['0', 'false', 'off', 'no', '']);
+
+function envKey(id) {
+  return 'MINIONS_FEATURE_' + String(id).toUpperCase().replace(/-/g, '_');
+}
+
+function readEnvOverride(id) {
+  const raw = process.env[envKey(id)];
+  if (raw === undefined) return undefined;
+  const v = String(raw).trim().toLowerCase();
+  if (ENV_TRUTHY.has(v)) return true;
+  if (ENV_FALSY.has(v)) return false;
+  return undefined;
+}
+
+function isFeatureOn(id, config, registry = FEATURES) {
+  if (!Object.prototype.hasOwnProperty.call(registry, id)) {
+    throw new Error(`Unknown feature flag: "${id}". Register it in engine/features.js.`);
+  }
+  const env = readEnvOverride(id);
+  if (env !== undefined) return env;
+  const fromConfig = config && config.features && config.features[id];
+  if (typeof fromConfig === 'boolean') return fromConfig;
+  return registry[id].default === true;
+}
+
+function listFeatures(config, registry = FEATURES) {
+  const now = Date.now();
+  return Object.entries(registry).map(([id, meta]) => {
+    const expiresAt = meta.expires ? Date.parse(meta.expires) : NaN;
+    return {
+      id,
+      description: meta.description || '',
+      default: meta.default === true,
+      enabled: isFeatureOn(id, config, registry),
+      addedIn: meta.addedIn || null,
+      expires: meta.expires || null,
+      expired: expiresAt < now,
+    };
+  });
+}
+
+function hasFeature(id, registry = FEATURES) {
+  return Object.prototype.hasOwnProperty.call(registry, id);
+}
+
+module.exports = { FEATURES, isFeatureOn, listFeatures, hasFeature };

package/engine/llm.js

@@ -23,44 +23,123 @@ const { resolveRuntime } = require('./runtimes');
 const MINIONS_DIR = shared.MINIONS_DIR;
 const ENGINE_DIR = path.join(MINIONS_DIR, 'engine');
 const COPILOT_TASK_COMPLETE_GRACE_MS = 3000;
+const LLM_EXIT_SETTLE_GRACE_MS = 1000;
 const MISSING_RUNTIME_EXIT_CODE = 78;
 
 // ─── Engine-Usage Metrics ────────────────────────────────────────────────────
+//
+// Updates accumulate in an in-memory buffer and flush every
+// metricsFlushIntervalMs (default 10s). Replaces the per-call mutateJsonFileLocked
+// that was both serializing the LLM hot path and bumping metrics.json mtime
+// on every call — defeating the dashboard fast-state mtime-based early-exit.
+
+let _pendingMetrics = { engine: Object.create(null), daily: Object.create(null) };
+let _flushTimer = null;
+
+function _emptyEngineDelta() {
+  return { calls: 0, costUsd: 0, inputTokens: 0, outputTokens: 0, cacheRead: 0, cacheCreation: 0, totalDurationMs: 0, timedCalls: 0 };
+}
+
+function _emptyDailyDelta() {
+  return { costUsd: 0, inputTokens: 0, outputTokens: 0, cacheRead: 0 };
+}
+
+function _ensureFlushTimer() {
+  if (_flushTimer) return;
+  const interval = shared.ENGINE_DEFAULTS.metricsFlushIntervalMs || 10000;
+  _flushTimer = setInterval(flushMetricsBuffer, interval);
+  if (typeof _flushTimer.unref === 'function') _flushTimer.unref();
+}
 
 function trackEngineUsage(category, usage) {
   if (!usage) return;
   if (category && (category.startsWith('_test') || category.startsWith('test-'))) return;
+
+  if (!_pendingMetrics.engine[category]) _pendingMetrics.engine[category] = _emptyEngineDelta();
+  const cat = _pendingMetrics.engine[category];
+  cat.calls++;
+  cat.costUsd += usage.costUsd || 0;
+  cat.inputTokens += usage.inputTokens || 0;
+  cat.outputTokens += usage.outputTokens || 0;
+  cat.cacheRead += usage.cacheRead || 0;
+  cat.cacheCreation += usage.cacheCreation || 0;
+  if (usage.durationMs) {
+    cat.totalDurationMs += usage.durationMs;
+    cat.timedCalls += 1;
+  }
+
+  const today = ts().slice(0, 10);
+  if (!_pendingMetrics.daily[today]) _pendingMetrics.daily[today] = _emptyDailyDelta();
+  const daily = _pendingMetrics.daily[today];
+  daily.costUsd += usage.costUsd || 0;
+  daily.inputTokens += usage.inputTokens || 0;
+  daily.outputTokens += usage.outputTokens || 0;
+  daily.cacheRead += usage.cacheRead || 0;
+
+  _ensureFlushTimer();
+}
+
+function flushMetricsBuffer() {
+  const pending = _pendingMetrics;
+  if (!Object.keys(pending.engine).length && !Object.keys(pending.daily).length) return;
+  _pendingMetrics = { engine: Object.create(null), daily: Object.create(null) };
+
   try {
     const metricsPath = path.join(ENGINE_DIR, 'metrics.json');
     mutateJsonFileLocked(metricsPath, (metrics) => {
       if (!metrics._engine) metrics._engine = {};
-      if (!metrics._engine[category]) {
-        metrics._engine[category] = { calls: 0, costUsd: 0, inputTokens: 0, outputTokens: 0, cacheRead: 0, cacheCreation: 0 };
-      }
-      const cat = metrics._engine[category];
-      cat.calls++;
-      cat.costUsd += usage.costUsd || 0;
-      cat.inputTokens += usage.inputTokens || 0;
-      cat.outputTokens += usage.outputTokens || 0;
-      cat.cacheRead += usage.cacheRead || 0;
-      cat.cacheCreation = (cat.cacheCreation || 0) + (usage.cacheCreation || 0);
-      if (usage.durationMs) {
-        cat.totalDurationMs = (cat.totalDurationMs || 0) + usage.durationMs;
-        cat.timedCalls = (cat.timedCalls || 0) + 1;
+      for (const [category, delta] of Object.entries(pending.engine)) {
+        if (!metrics._engine[category]) {
+          metrics._engine[category] = { calls: 0, costUsd: 0, inputTokens: 0, outputTokens: 0, cacheRead: 0, cacheCreation: 0 };
+        }
+        const cat = metrics._engine[category];
+        cat.calls = (cat.calls || 0) + delta.calls;
+        cat.costUsd = (cat.costUsd || 0) + delta.costUsd;
+        cat.inputTokens = (cat.inputTokens || 0) + delta.inputTokens;
+        cat.outputTokens = (cat.outputTokens || 0) + delta.outputTokens;
+        cat.cacheRead = (cat.cacheRead || 0) + delta.cacheRead;
+        cat.cacheCreation = (cat.cacheCreation || 0) + delta.cacheCreation;
+        if (delta.timedCalls > 0) {
+          cat.totalDurationMs = (cat.totalDurationMs || 0) + delta.totalDurationMs;
+          cat.timedCalls = (cat.timedCalls || 0) + delta.timedCalls;
+        }
       }
-
-      const today = ts().slice(0, 10);
       if (!metrics._daily) metrics._daily = {};
-      if (!metrics._daily[today]) metrics._daily[today] = { costUsd: 0, inputTokens: 0, outputTokens: 0, cacheRead: 0, tasks: 0 };
-      const daily = metrics._daily[today];
-      daily.costUsd += usage.costUsd || 0;
-      daily.inputTokens += usage.inputTokens || 0;
-      daily.outputTokens += usage.outputTokens || 0;
-      daily.cacheRead += usage.cacheRead || 0;
-
+      for (const [day, delta] of Object.entries(pending.daily)) {
+        if (!metrics._daily[day]) {
+          metrics._daily[day] = { costUsd: 0, inputTokens: 0, outputTokens: 0, cacheRead: 0, tasks: 0 };
+        }
+        const d = metrics._daily[day];
+        d.costUsd += delta.costUsd;
+        d.inputTokens += delta.inputTokens;
+        d.outputTokens += delta.outputTokens;
+        d.cacheRead += delta.cacheRead;
+      }
       return metrics;
     });
-  } catch (e) { console.error('metrics update:', e.message); }
+  } catch (e) {
+    // Re-merge pending so the next flush retries — never drop counters silently.
+    for (const [category, delta] of Object.entries(pending.engine)) {
+      if (!_pendingMetrics.engine[category]) _pendingMetrics.engine[category] = _emptyEngineDelta();
+      const c = _pendingMetrics.engine[category];
+      c.calls += delta.calls; c.costUsd += delta.costUsd;
+      c.inputTokens += delta.inputTokens; c.outputTokens += delta.outputTokens;
+      c.cacheRead += delta.cacheRead; c.cacheCreation += delta.cacheCreation;
+      c.totalDurationMs += delta.totalDurationMs; c.timedCalls += delta.timedCalls;
+    }
+    for (const [day, delta] of Object.entries(pending.daily)) {
+      if (!_pendingMetrics.daily[day]) _pendingMetrics.daily[day] = _emptyDailyDelta();
+      const d = _pendingMetrics.daily[day];
+      d.costUsd += delta.costUsd; d.inputTokens += delta.inputTokens;
+      d.outputTokens += delta.outputTokens; d.cacheRead += delta.cacheRead;
+    }
+    console.error('metrics flush:', e.message);
+  }
+}
+
+function _resetMetricsBufferForTest() {
+  _pendingMetrics = { engine: Object.create(null), daily: Object.create(null) };
+  if (_flushTimer) { clearInterval(_flushTimer); _flushTimer = null; }
 }
 
 // ─── Runtime Binary Resolution (TTL-cached) ──────────────────────────────────
@@ -83,7 +162,10 @@ function _resolveBin(runtime) {
   if (!runtime) return null;
   const key = runtime.name;
   const cached = _binCache.get(key);
-  if (cached && Date.now() - cached.ts < _BIN_TTL && fs.existsSync(cached.bin)) {
+  // Trust the 30-min TTL — skip per-call existsSync (10-50ms on Windows w/ AV).
+  // If the binary disappears mid-window, spawn fails with ENOENT and the
+  // adapter's resolveBinary() reprobes on the next cache miss.
+  if (cached && Date.now() - cached.ts < _BIN_TTL) {
     return { bin: cached.bin, native: cached.native, leadingArgs: cached.leadingArgs };
   }
   let resolved = null;
@@ -528,6 +610,8 @@ function callLLM(promptText, sysPromptText, opts = {}) {
       maxBudget, bare, fallbackModel,
       ...runtimeFeatureOpts,
     });
+    let settled = false;
+    let exitSettleTimer = null;
     let taskCompleteTimer = null;
     const scheduleTaskCompleteClose = () => {
       if (taskCompleteTimer) return;
@@ -554,11 +638,16 @@ function callLLM(promptText, sysPromptText, opts = {}) {
 
     const timer = setTimeout(() => { shared.killImmediate(proc); }, timeout);
 
-    proc.on('close', (code) => {
+    function finish(code) {
+      if (settled) return;
+      settled = true;
       clearTimeout(timer);
+      if (exitSettleTimer) clearTimeout(exitSettleTimer);
       clearTaskCompleteTimer();
       for (const f of cleanupFiles) safeUnlink(f);
       const parsed = acc.finalize();
+      try { proc.stdout?.destroy(); } catch {}
+      try { proc.stderr?.destroy(); } catch {}
       const durationMs = Date.now() - _startMs;
       const usage = parsed.usage ? { ...parsed.usage, durationMs } : { durationMs };
       // parseError lets the adapter classify obvious failure modes (auth /
@@ -578,10 +667,19 @@ function callLLM(promptText, sysPromptText, opts = {}) {
         runtime: runtime.name,
         errorClass: errInfo.code,
       });
+    }
+
+    proc.on('close', finish);
+    proc.on('exit', (code) => {
+      if (settled) return;
+      exitSettleTimer = setTimeout(() => finish(code), LLM_EXIT_SETTLE_GRACE_MS);
     });
 
     proc.on('error', (err) => {
+      if (settled) return;
+      settled = true;
       clearTimeout(timer);
+      if (exitSettleTimer) clearTimeout(exitSettleTimer);
       clearTaskCompleteTimer();
       for (const f of cleanupFiles) safeUnlink(f);
       shared.log('error', `LLM spawn error (${label}): ${err.message}`);
@@ -628,6 +726,8 @@ function callLLMStreaming(promptText, sysPromptText, opts = {}) {
       maxBudget, bare, fallbackModel,
       ...runtimeFeatureOpts,
     });
+    let settled = false;
+    let exitSettleTimer = null;
     let taskCompleteTimer = null;
     const scheduleTaskCompleteClose = () => {
       if (taskCompleteTimer) return;
@@ -657,11 +757,16 @@ function callLLMStreaming(promptText, sysPromptText, opts = {}) {
 
     const timer = setTimeout(() => { shared.killImmediate(proc); }, timeout);
 
-    proc.on('close', (code) => {
+    function finish(code) {
+      if (settled) return;
+      settled = true;
       clearTimeout(timer);
+      if (exitSettleTimer) clearTimeout(exitSettleTimer);
       clearTaskCompleteTimer();
       for (const f of cleanupFiles) safeUnlink(f);
       const parsed = acc.finalize();
+      try { proc.stdout?.destroy(); } catch {}
+      try { proc.stderr?.destroy(); } catch {}
       const durationMs = Date.now() - _startMs;
       const usage = parsed.usage ? { ...parsed.usage, durationMs } : { durationMs };
       const errInfo = code !== 0
@@ -678,10 +783,19 @@ function callLLMStreaming(promptText, sysPromptText, opts = {}) {
         runtime: runtime.name,
         errorClass: errInfo.code,
       });
+    }
+
+    proc.on('close', finish);
+    proc.on('exit', (code) => {
+      if (settled) return;
+      exitSettleTimer = setTimeout(() => finish(code), LLM_EXIT_SETTLE_GRACE_MS);
     });
 
     proc.on('error', (err) => {
+      if (settled) return;
+      settled = true;
       clearTimeout(timer);
+      if (exitSettleTimer) clearTimeout(exitSettleTimer);
       clearTaskCompleteTimer();
       for (const f of cleanupFiles) safeUnlink(f);
       shared.log('error', `LLM-stream spawn error (${label}): ${err.message}`);
@@ -700,10 +814,12 @@ module.exports = {
   callLLM,
   callLLMStreaming,
   trackEngineUsage,
+  flushMetricsBuffer,
   // Exposed for unit tests — engine code MUST use the runtime adapter contract.
   _buildSpawnAgentFlags,
   _resolveBin,
   _resetBinCache,
+  _resetMetricsBufferForTest,
   _resolveRuntimeFor,
   _resolveModelFor,
   _resolveModelForRuntime,

package/engine/shared.js

@@ -918,6 +918,7 @@ const ENGINE_DEFAULTS = {
   docSessionTtlMs: 7 * 24 * 60 * 60 * 1000, // 7d — longer-lived doc sessions, still bounded
   docSessionMaxEntries: 200, // cap doc-chat session map/disk store by least-recent activity
   ccLiveStreamMaxAgeMs: 30 * 60 * 1000, // hard cap reconnect buffers if abort/cleanup stalls
+  metricsFlushIntervalMs: 10000, // batch trackEngineUsage writes to metrics.json — flushed every 10s instead of per-call to cut lock contention and dashboard mtime churn
   maxLlmRawBytes: 256 * 1024, // keep only a bounded stdout tail from direct Claude calls
   maxLlmStderrBytes: 64 * 1024, // keep only a bounded stderr tail from direct Claude calls
   maxLlmLineBufferBytes: 128 * 1024, // cap the incremental JSON line buffer to avoid malformed-stream OOMs

package/engine.js

@@ -4071,7 +4071,7 @@ async function tickInner() {
 
   // 2.5. Periodic cleanup + MCP sync (every 10 ticks = ~5 minutes)
   if (tickCount % 10 === 0) {
-    safe('runCleanup', () => runCleanup(config));
+    try { await runCleanup(config); } catch (e) { log('warn', `runCleanup: ${e.message}`); }
   }
 
   // 2.55. Check persistent watches (3 tick-equivalents, default ~3 minutes)

package/package.json

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