@yemi33/minions 0.1.2381 → 0.1.2383

package/bin/minions.js

@@ -336,7 +336,11 @@ function _sqliteSpawnFlags() {
  *  CLI's intent (EADDRINUSE retries still apply inside the dashboard if a
  *  race opens between the CLI's port-free check and the actual bind). */
 function spawnDashboard(requestedPort) {
-  const env = { ...process.env, MINIONS_NO_AUTO_OPEN: '1' };
+  const env = {
+    ...process.env,
+    MINIONS_NO_AUTO_OPEN: '1',
+    MINIONS_REQUIRE_DASHBOARD_PORT: '1',
+  };
   const out = _openStdioLog('dashboard-stdio.log');
   const err = _openStdioLog('dashboard-stdio.log');
   const args = [..._sqliteSpawnFlags(), path.join(MINIONS_HOME, 'dashboard.js')];
@@ -444,19 +448,43 @@ function spawnFullStackAndVerify({ rest, forceOpen, dashWasUp, restartStartMs })
     // failure rather than a false "healthy".
     const actualPort = await _waitForDashboardPortFile(MINIONS_HOME, 12000, 150, dashProc.pid) || requested.port;
     if (actualPort !== requested.port) {
-      console.log(`  Dashboard bound to alternate port ${actualPort} (requested ${requested.port} was busy)`);
+      console.error(`\n  ERROR: Dashboard bound to unexpected port ${actualPort}; required ${requested.port}.`);
+      console.error('  Refusing to verify a split-port Minions topology. Run `minions restart` again.');
+      _cleanupFailedStackSpawn({
+        enginePid: engineProc.pid,
+        dashboardPid: dashProc.pid,
+        supervisorPid: supProc.pid,
+        dashboardPort: actualPort,
+      });
+      process.exit(1);
     }
+    const supervisorInternals = require(path.join(PKG_ROOT, 'engine', 'supervisor'))._internals;
     const result = await waitForRestartHealth({
       minionsHome: MINIONS_HOME,
+      expectedEnginePid: engineProc.pid,
       dashboardPid: dashProc.pid,
       dashboardPort: actualPort,
+      supervisorPid: supProc.pid,
       timeoutMs: _resolveRestartHealthTimeoutMs(),
       // Verify the process bound to the port IS the dashboard we just spawned
       // (beacon pid match), not a stale leftover still holding it.
       requireBeaconOwner: true,
+      requireExactTopology: true,
+      listProcessPids: supervisorInternals.listNodePidsMatching,
+      topologyScripts: {
+        engine: path.join(MINIONS_HOME, 'engine.js'),
+        dashboard: path.join(MINIONS_HOME, 'dashboard.js'),
+        supervisor: path.join(MINIONS_HOME, 'engine', 'supervisor.js'),
+      },
     });
     if (!result.ok) {
       console.error(formatRestartHealthError(result));
+      _cleanupFailedStackSpawn({
+        enginePid: engineProc.pid,
+        dashboardPid: dashProc.pid,
+        supervisorPid: supProc.pid,
+        dashboardPort: actualPort,
+      });
       process.exit(1);
     }
     console.log(`  Restart verified: engine PID ${result.engine.pid}; dashboard healthy.`);
@@ -479,6 +507,17 @@ function spawnFullStackAndVerify({ rest, forceOpen, dashWasUp, restartStartMs })
   });
 }
 
+function _cleanupFailedStackSpawn({ enginePid, dashboardPid, supervisorPid, dashboardPort }) {
+  writeStopIntent('restart verification failed');
+  for (const pid of [supervisorPid, dashboardPid, enginePid]) killPidOnly(pid);
+  for (const pid of [supervisorPid, dashboardPid, enginePid]) waitForPidDeath(pid, 5000);
+  if (dashboardPort) {
+    killByPort(dashboardPort);
+    waitForPortRelease(dashboardPort, 5000);
+  }
+  shared.clearDashboardPortFile(MINIONS_HOME);
+}
+
 /** Poll engine/dashboard-port.json until it appears (dashboard wrote it on
  *  listen) or the timeout elapses. Returns the bound port or null on
  *  timeout. Stale files left behind by a crashed dashboard are tolerated —
@@ -873,6 +912,7 @@ function init() {
 
   // Copy with smart merge logic
   copyDir(PKG_ROOT, MINIONS_HOME, excludeTop, alwaysUpdate, neverOverwrite, isUpgrade, actions);
+  shared.syncBundledPersonalSkills(path.join(MINIONS_HOME, 'skills'), { homeDir: os.homedir() });
 
   // Create config from template if it doesn't exist
   const configPath = path.join(MINIONS_HOME, 'config.json');

package/dashboard/js/refresh.js

@@ -151,8 +151,11 @@ const RENDER_VERSIONS = {
   dispatch: 2,
   engineLog: 2,
   metrics: 1,
-  // Bumped 8->9: row actions now preserve work-item source scope when IDs collide.
-  workItems: 9,
+  // Bumped 7→8: WI detail modal's branch pill moved out of the Artifacts
+  // chip row into its own non-interactive "Branch" field (W-mr2qjr3b0002522f).
+  // Bumped 8→9 for paused pre-dispatch evaluation guidance.
+  // Bumped 9→10: row actions now preserve work-item source scope when IDs collide.
+  workItems: 10,
   skills: 1,
   commands: 1,
   mcpServers: 1,
@@ -840,6 +843,9 @@ function _processStatusUpdate(data, opts) {
       .catch(function () { /* keep render even if managed fetch failed — getLastItems() returns the last good cache (or []) */ })
       .then(function () { try { renderKeepProcesses(); } catch {} });
   }
+  if (typeof renderWorktreeQuarantineRefs === 'function') {
+    _safeRender('worktreeQuarantineRefs', function () { renderWorktreeQuarantineRefs(); });
+  }
   // Work items now come from /api/work-items — a dedicated fresh-JSON
   // endpoint that re-runs getWorkItems() server-side on every request
   // with input-mtime ETag (issue #2949). The previous /state/ + stale-

package/dashboard/js/render-other.js

@@ -1250,3 +1250,41 @@ async function killKeepPid(agentId, pid) {
 }
 
 window.MinionsKeepProcesses = { renderKeepProcesses, killKeepPid, mountKeepProcessesPanel, unmountKeepProcessesPanel };
+
+async function renderWorktreeQuarantineRefs() {
+  const root = document.getElementById('worktree-quarantine-refs-content');
+  const count = document.getElementById('worktree-quarantine-refs-count');
+  if (!root) return;
+  let html;
+  try {
+    const res = await fetch('/api/worktree-quarantine-refs');
+    const data = await res.json();
+    if (!res.ok) throw new Error(data.error || String(res.status));
+    const items = Array.isArray(data.items) ? data.items : [];
+    if (count) count.textContent = String(items.length);
+    if (!items.length) {
+      html = '<p class="empty">No quarantined work refs found.</p>';
+    } else {
+      html = '<table style="width:100%;border-collapse:collapse"><thead><tr>' +
+        '<th style="text-align:left">Project</th><th style="text-align:left">Backup ref</th>' +
+        '<th style="text-align:left">SHA</th><th style="text-align:left">Created</th></tr></thead><tbody>' +
+        items.map(function (item) {
+          if (item.error) {
+            return '<tr><td>' + escHtml(item.project || '') + '</td><td colspan="3" style="color:var(--red)">' + escHtml(item.error) + '</td></tr>';
+          }
+          return '<tr><td>' + escHtml(item.project || '') + '</td>' +
+            '<td><code>' + escHtml(item.ref || '') + '</code></td>' +
+            '<td><code>' + escHtml(String(item.sha || '').slice(0, 12)) + '</code></td>' +
+            '<td>' + escHtml(item.createdAt || '') + '</td></tr>';
+        }).join('') +
+        '</tbody></table>';
+    }
+  } catch (e) {
+    if (count) count.textContent = '?';
+    html = '<span style="color:var(--red)">Failed to load: ' + escHtml(e.message) + '</span>';
+  }
+  // eslint-disable-next-line no-unsanitized/method -- structural HTML only; API fields are escaped above
+  root.replaceChildren(document.createRange().createContextualFragment(html));
+}
+
+window.MinionsWorktreeQuarantineRefs = { renderWorktreeQuarantineRefs };

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

@@ -52,10 +52,17 @@ function needsAttentionInfo(item) {
   if (item._preDispatchEval && item._preDispatchEval.valid === false) {
     var rawReason = String(item._preDispatchEval.reason || '(no reason recorded)');
     var firstLine = rawReason.split(/\r?\n/, 1)[0] || rawReason;
+    var exhausted = item._preDispatchEval.exhausted === true;
+    var prefix = exhausted
+      ? 'Pre-dispatch evaluation paused after ' + (item._preDispatchEval.rejectCount || '?') + ' unchanged rejections: '
+      : 'Pre-dispatch evaluation rejected: ';
+    var fullReason = exhausted
+      ? rawReason + '\n\nEdit the work item description to resume evaluation, or cancel it.'
+      : rawReason;
     return {
       kind: 'pre_dispatch_eval',
-      short: 'Pre-dispatch evaluation rejected: ' + firstLine,
-      full: rawReason,
+      short: prefix + firstLine,
+      full: fullReason,
     };
   }
 
@@ -1065,7 +1072,9 @@ function viewAgentOutput(logPath) {
     });
 }
 
+let _inboxNoteOpenSeq = 0;
 function openInboxNote(filename) {
+  var openSeq = ++_inboxNoteOpenSeq;
   var idx = (inboxData || []).findIndex(function(item) { return item.name === filename; });
   if (idx >= 0) {
     openModal(idx);
@@ -1083,29 +1092,61 @@ function openInboxNote(filename) {
   // 'archive:<name>' token). Fetch it from notes/archive/ and show it in the
   // modal instead of bouncing to the inbox page. Falls back to the inbox page
   // only if the file is genuinely gone (e.g. merged into notes.md).
+  var title = filename + ' (archived)';
+  var filePath = 'notes/archive/' + filename;
+  var titleEl = document.getElementById('modal-title');
+  var bodyEl = document.getElementById('modal-body');
+  if (titleEl) titleEl.textContent = title;
+  if (bodyEl) {
+    bodyEl.innerHTML = '<p style="color:var(--muted)">Loading...</p>';
+    bodyEl.style.fontFamily = "'Segoe UI', system-ui, sans-serif";
+    bodyEl.style.whiteSpace = 'normal';
+  }
+  _modalDocContext = { title: title, content: '', selection: '' };
+  _modalFilePath = filePath;
+  var qaEl = document.getElementById('modal-qa');
+  if (qaEl) qaEl.style.display = 'none';
+  var modalEl = document.getElementById('modal');
+  if (modalEl) modalEl.classList.add('open');
+
+  // A note can be superseded by another note before its archive fetch resolves,
+  // or by a different artifact stacked above it. Guard both cases so delayed
+  // success and failure handlers only affect the selection that started them.
+  var applyIfCurrent = function(fn) {
+    if (openSeq !== _inboxNoteOpenSeq ||
+        _modalFilePath !== filePath ||
+        !modalEl ||
+        !modalEl.classList.contains('open')) return false;
+    if (typeof withTopFrame === 'function') return withTopFrame('note', filename, fn);
+    fn();
+    return true;
+  };
+
   fetch('/state/notes/archive/' + encodeURIComponent(filename))
     .then(function(r) { if (!r.ok) throw new Error('HTTP ' + r.status); return r.text(); })
     .then(function(content) {
-      var titleEl = document.getElementById('modal-title');
-      var bodyEl = document.getElementById('modal-body');
-      if (!titleEl || !bodyEl) return;
-      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.
-      _wiInjectSourceChipFromFrontmatter(content, 'modal-body');
+      applyIfCurrent(function() {
+        if (!titleEl || !bodyEl) return;
+        titleEl.textContent = title;
+        // 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: title, content: content, selection: '' };
+        _modalFilePath = filePath;
+        showModalQa();
+        // P-34fa5d79 — Source-WI chip for archive notes. Same convention as the
+        // live-inbox branch above; parsed off the freshly-fetched content.
+        _wiInjectSourceChipFromFrontmatter(content, 'modal-body');
+      });
     })
     .catch(function() {
-      closeModal();
-      switchPage('inbox');
+      applyIfCurrent(function() {
+        closeModal();
+        switchPage('inbox');
+      });
     });
 }
 

package/dashboard/js/settings.js

@@ -476,6 +476,7 @@ async function openSettings() {
       // Tooltip on copilotDisableBuiltinMcps MUST warn about the split-brain risk
       settingsToggle('Copilot: disable built-in MCPs', 'set-copilotDisableBuiltinMcps', e.copilotDisableBuiltinMcps !== false,
         '⚠ When OFF, Copilot agents can autonomously create PRs/labels/comments via the github-mcp-server, bypassing pull-requests.json tracking — Minions and Copilot end up with split views of the same PR. Keep ON unless you understand the risk.') +
+      settingsToggle('Propagate CLAUDE.md to non-Claude runtimes', 'set-propagateClaudeMdForNonClaudeRuntimes', e.propagateClaudeMdForNonClaudeRuntimes !== false, 'Copilot/Codex have NO native CLAUDE.md auto-load. When ON (default), the engine bounded-discovers the nearest applicable repo-authored CLAUDE.md files for a dispatch and injects them as a "Project instructions (CLAUDE.md)" context layer so load-bearing "keep in sync" rules and blessed tooling reach the agent. Claude is always skipped (its CLI reads CLAUDE.md itself). Orthogonal to each runtime\'s native AGENTS.md discovery — CLAUDE.md carries no split-brain risk because Copilot/Codex never read it themselves. Per-project override via project.propagateClaudeMdForNonClaudeRuntimes.') +
       settingsToggle('Copilot: reasoning summaries', 'set-copilotReasoningSummaries', !!e.copilotReasoningSummaries, '--enable-reasoning-summaries (Anthropic-family models only)') +
     '</div>' +
     '<div class="settings-grid-2">' +
@@ -973,19 +974,16 @@ async function loadModelsForAgent(agentId, runtimeName, currentValue) {
     cell.innerHTML = '<input ' + baseAttrs + ' value="' + escHtml(currentValue || '') + '" placeholder="' + escHtml(runtimeName) + ' default" style="' + baseStyle + '">';
     return;
   }
-  let opts = '<option value=""' + (!currentValue ? ' selected' : '') + '>(fleet/default)</option>';
+  const listId = 'agent-model-options-' + agentId;
+  let opts = '';
   for (const m of models) {
     const id = m.id || m.name || '';
     if (!id) continue;
-    const label = m.name && m.name !== id ? (id + ' — ' + m.name) : id;
-    opts += '<option value="' + escHtml(id) + '"' + (id === currentValue ? ' selected' : '') + '>' + escHtml(label) + '</option>';
-  }
-  // Preserve unknown saved values so a user-set custom ID survives the next save.
-  if (currentValue && !models.some(m => (m.id || m.name) === currentValue)) {
-    opts += '<option value="' + escHtml(currentValue) + '" selected>' + escHtml(currentValue) + ' (custom — invalid for ' + escHtml(runtimeName) + '?)</option>';
+    const label = m.name && m.name !== id ? m.name : '';
+    opts += '<option value="' + escHtml(id) + '"' + (label ? ' label="' + escHtml(label) + '"' : '') + '></option>';
   }
   // eslint-disable-next-line no-unsanitized/property -- reason: structural HTML is a string literal; all user data wrapped in escHtml() (fields: agentId, model id, model label, currentValue, runtimeName)
-  cell.innerHTML = '<select ' + baseAttrs + ' style="' + baseStyle + '">' + opts + '</select>';
+  cell.innerHTML = '<input ' + baseAttrs + ' list="' + escHtml(listId) + '" value="' + escHtml(currentValue || '') + '" placeholder="' + escHtml(runtimeName) + ' default" autocomplete="off" style="' + baseStyle + '"><datalist id="' + escHtml(listId) + '">' + opts + '</datalist>';
 }
 
 function settingsToggle(label, id, checked, hint) {
@@ -1191,6 +1189,7 @@ async function saveSettings() {
       claudeFallbackModel: (document.getElementById('set-claudeFallbackModel')?.value ?? '').trim(),
       copilotFallbackModel: (document.getElementById('set-copilotFallbackModel')?.value ?? '').trim(),
       copilotDisableBuiltinMcps: !!document.getElementById('set-copilotDisableBuiltinMcps')?.checked,
+      propagateClaudeMdForNonClaudeRuntimes: !!document.getElementById('set-propagateClaudeMdForNonClaudeRuntimes')?.checked,
       copilotStreamMode: document.getElementById('set-copilotStreamMode')?.value || 'on',
       copilotReasoningSummaries: !!document.getElementById('set-copilotReasoningSummaries')?.checked,
       claudePreApproveWorkspaceMcps: !!document.getElementById('set-claudePreApproveWorkspaceMcps')?.checked,

package/dashboard/pages/engine.html

@@ -26,6 +26,12 @@
         </h2>
         <div id="keep-processes-content"><p class="empty">No agents have left processes running. Set <code>meta.keep_processes: true</code> on a work item to enable.</p></div>
       </section>
+      <section id="worktree-quarantine-refs-section">
+        <h2>Quarantined Work <span class="count" id="worktree-quarantine-refs-count">0</span>
+          <span class="qa-section-subtitle">local backup refs available for manual recovery</span>
+        </h2>
+        <div id="worktree-quarantine-refs-content"><p class="empty">No quarantined work refs found.</p></div>
+      </section>
       <section id="managed-processes-section">
         <h2>Managed Processes <span class="count" id="managed-processes-count">0</span>
           <span class="qa-section-subtitle">engine-managed long-running services</span>

package/dashboard.js

@@ -26,7 +26,7 @@ const fs = require('fs');
 const path = require('path');
 const v8 = require('v8');
 const llm = require('./engine/llm');
-const { resolveRuntime } = require('./engine/runtimes');
+const { resolveRuntime, shouldSuppressPostMutationError } = require('./engine/runtimes');
 
 // Dashboard version stamp — captured at module load so it reflects the code actually running.
 // codeCommit is read via _readGitHeadShort (defined below — function declarations
@@ -1655,13 +1655,23 @@ const PLANS_DIR = path.join(MINIONS_DIR, 'plans');
 // W-mpetru8a000s123a — /api/plans cache. Dashboard auto-polls every 4s; the
 // pre-cache cold path walked 4 directories (plans/, prd/, archive variants),
 // sync-stat'd every file, and parsed/regex-scanned each .md → 2-3s blocking.
-// 5s TTL means external .md edits surface within 5s. Mutation handlers must
-// call invalidatePlansCache() for immediate visibility.
+// 30s TTL keeps the full markdown/SQL rollup off the 4s browser poll cadence.
+// Mutation handlers call invalidatePlansCache() for immediate visibility;
+// out-of-process edits surface within 30s.
 let _plansCache = null;
 let _plansCacheTs = 0;
-const PLANS_CACHE_TTL_MS = 5000;
+const PLANS_CACHE_TTL_MS = 30000;
 function invalidatePlansCache() { _plansCache = null; _plansCacheTs = 0; }
 
+async function _mapInBatches(items, batchSize, mapper) {
+  const result = [];
+  for (let start = 0; start < items.length; start += batchSize) {
+    result.push(...await Promise.all(items.slice(start, start + batchSize).map(mapper)));
+    if (start + batchSize < items.length) await _yieldEventLoop();
+  }
+  return result;
+}
+
 function statePathExists(filePath) {
   return fs.existsSync(filePath);
 }
@@ -1964,11 +1974,19 @@ function _countWorktrees() {
   try {
     const config = queries.getConfig();
     const projects = shared.getProjects(config);
-    let count = 0;
+    const worktreeRoots = new Map();
     for (const p of projects) {
-      const root = p.localPath ? path.resolve(p.localPath) : null;
-      if (!root) continue;
-      const wtRoot = path.resolve(root, config.engine?.worktreeRoot || shared.ENGINE_DEFAULTS.worktreeRoot);
+      if (!p.localPath) continue;
+      const wtRoot = path.resolve(
+        p.localPath,
+        config.engine?.worktreeRoot || shared.ENGINE_DEFAULTS.worktreeRoot,
+      );
+      const rootKey = shared._normalizeWorktreePath(wtRoot);
+      if (!worktreeRoots.has(rootKey)) worktreeRoots.set(rootKey, wtRoot);
+    }
+
+    let count = 0;
+    for (const wtRoot of worktreeRoots.values()) {
       try {
         for (const dir of fs.readdirSync(wtRoot)) {
           const dirPath = path.join(wtRoot, dir);
@@ -2961,15 +2979,35 @@ async function _freshnessEntryMtimeMs(fp, depth) {
   return max;
 }
 
+const FRESHNESS_MTIME_CACHE_TTL_MS = 1000;
+const _freshnessMtimeCache = new Map();
+
 async function _maxInputMtimeMs(inputs) {
+  const key = inputs.map(fp => path.resolve(fp)).sort().join('\0');
+  const now = Date.now();
+  const cached = _freshnessMtimeCache.get(key);
+  if (cached && now - cached.createdAt < FRESHNESS_MTIME_CACHE_TTL_MS) {
+    return cached.promise;
+  }
   // Directory mtime only advances on add/remove, not in-place edits. Walk two
   // levels so prd/<plan>.json and agents/<id>/live-output.log both bust ETags.
   // Deeper steering edits still rely on add/remove cadence, matching the prior
   // bounded walk.
-  const mtimes = await Promise.all(
+  const promise = Promise.all(
     inputs.map(fp => _freshnessEntryMtimeMs(fp, 2)),
-  );
-  return Math.floor(mtimes.reduce((max, mtime) => Math.max(max, mtime), 0));
+  ).then(mtimes => Math.floor(mtimes.reduce((max, mtime) => Math.max(max, mtime), 0)));
+  _freshnessMtimeCache.set(key, { createdAt: now, promise });
+  if (_freshnessMtimeCache.size > 100) {
+    for (const [cacheKey, entry] of _freshnessMtimeCache) {
+      if (now - entry.createdAt >= FRESHNESS_MTIME_CACHE_TTL_MS) _freshnessMtimeCache.delete(cacheKey);
+    }
+  }
+  try {
+    return await promise;
+  } catch (err) {
+    if (_freshnessMtimeCache.get(key)?.promise === promise) _freshnessMtimeCache.delete(key);
+    throw err;
+  }
 }
 async function serveFreshJson(req, res, opts) {
   const inputs = Array.isArray(opts && opts.inputs) ? opts.inputs : [];
@@ -3161,7 +3199,20 @@ function handleStateRead(req, res) {
   res.setHeader('Content-Type', _stateReadContentType(path.extname(resolved)));
   try {
     const stream = fs.createReadStream(resolved);
+    // HANDLE-LEAK GUARD (#858): destroy the read stream if the client aborts or
+    // the connection closes before the pipe drains. Without this, an aborted
+    // GET /state/notes.md leaks the open file handle indefinitely (confirmed
+    // via handle64: dashboard held a handle on notes.md for 2+ hours). On
+    // Windows that lingering handle makes the engine's consolidation
+    // renameSync throw EPERM, which used to crash-loop the whole daemon.
+    const destroyStream = () => { if (!stream.destroyed) stream.destroy(); };
+    if (typeof res.on === 'function') res.on('close', destroyStream);
+    if (typeof req.on === 'function') {
+      req.on('close', destroyStream);
+      req.on('aborted', destroyStream);
+    }
     stream.on('error', (err) => {
+      destroyStream();
       if (!res.headersSent) {
         res.statusCode = 500;
         res.setHeader('Content-Type', 'application/json');
@@ -4635,6 +4686,7 @@ function _invokeDocChatViaPool({ prompt, model, effort, engineConfig, systemProm
   (async () => {
     try {
       sessionHandle = await ccWorkerPool.getSession({
+        runtime: llm._resolveRuntimeFor({ engineConfig }),
         tabId: tabKey,
         model,
         effort,
@@ -5302,13 +5354,15 @@ function _recoverPartialDocChatResponse(result, sessionKey) {
 function _shouldSuppressDocChatPostPatchError(ccError, finalize) {
   if (!finalize || finalize.edited !== true) return false;
   if (!ccError) return false;
-  // W-mpmwxni2000c25c7-a — accept both the legacy 'unknown-model' errorClass
-  // (still emitted by the dashboard preflight at _preflightModelCheck) and
-  // the new 'model-unavailable' code returned by copilot.parseError for
-  // invalid-model responses. Suppress in either case — the edit already
-  // landed, so the stale model error shouldn't surface to the user.
-  if (ccError.errorClass !== 'unknown-model' && ccError.errorClass !== 'model-unavailable') return false;
-  return String(ccError.runtime || '').toLowerCase() === 'copilot';
+  try {
+    const runtime = resolveRuntime(ccError.runtime);
+    return shouldSuppressPostMutationError(runtime, {
+      mutationApplied: true,
+      error: ccError,
+    });
+  } catch {
+    return false;
+  }
 }
 
 function _buildDocChatResponsePayload({
@@ -7688,7 +7742,7 @@ const server = http.createServer(async (req, res) => {
       { dir: path.join(PLANS_DIR, 'archive'), archived: true },
     ]) {
       const allFiles = (await fsp.readdir(dir).catch(() => [])).filter(f => f.endsWith('.md'));
-      const dirResults = await Promise.all(allFiles.map(async f => {
+      const dirResults = await _mapInBatches(allFiles, 25, async f => {
         const filePath = path.join(dir, f);
         const [content, stat] = await Promise.all([
           fsp.readFile(filePath, 'utf8').catch(() => ''),
@@ -7725,10 +7779,20 @@ const server = http.createServer(async (req, res) => {
           revisionFeedback: null,
           version: versionMatch ? parseInt(versionMatch[1]) : null,
         };
-      }));
+      });
       for (const r of dirResults) if (r) plans.push(r);
     }
 
+    const sourcePlanMtimes = new Map();
+    const sourcePlanNames = [...new Set(prdRows
+      .filter(row => !row.archived && row.plan?.source_plan)
+      .map(row => row.plan.source_plan))];
+    const sourceStats = await _mapInBatches(sourcePlanNames, 25, async sourcePlan => {
+      const stat = await fsp.stat(path.join(PLANS_DIR, sourcePlan)).catch(() => null);
+      return [sourcePlan, stat ? Math.floor(stat.mtimeMs) : null];
+    });
+    for (const [sourcePlan, mtimeMs] of sourceStats) sourcePlanMtimes.set(sourcePlan, mtimeMs);
+
     // --- PRD JSON records (prd/*.json + prd/archive/*.json, SQL-backed) ---
     for (const row of prdRows) {
       const plan = row.plan;
@@ -7742,11 +7806,9 @@ const server = http.createServer(async (req, res) => {
       // so the Plans tab does not silently mirror a stale-but-cached false.
       let freshStale = false;
       if (!archived && plan.source_plan) {
-        try {
-          const sourceMtime = Math.floor(fs.statSync(path.join(PLANS_DIR, plan.source_plan)).mtimeMs);
-          const recorded = plan.sourcePlanModifiedAt ? new Date(plan.sourcePlanModifiedAt).getTime() : null;
-          if (recorded && sourceMtime > recorded) freshStale = true;
-        } catch { /* source plan may have been deleted/renamed */ }
+        const sourceMtime = sourcePlanMtimes.get(plan.source_plan);
+        const recorded = plan.sourcePlanModifiedAt ? new Date(plan.sourcePlanModifiedAt).getTime() : null;
+        if (recorded && sourceMtime != null && sourceMtime > recorded) freshStale = true;
       }
       // P-e8d49105 — _projects rollup feeds the plan-card multi-badge
       // path in dashboard/js/render-plans.js. For PRD JSONs, walk
@@ -9396,6 +9458,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     if (!shared.resolveCcUseWorkerPool(CONFIG.engine)) return { skipped: 'pool-disabled' };
     if (!tabId) throw new Error('tabId required');
     const result = await ccWorkerPool.warmTab({
+      runtime: resolveRuntime(shared.resolveCcCli(CONFIG.engine)),
       tabId,
       model: CONFIG.engine?.ccModel || shared.ENGINE_DEFAULTS.ccModel,
       effort: CONFIG.engine?.ccEffort || shared.ENGINE_DEFAULTS.ccEffort,
@@ -9772,6 +9835,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     (async () => {
       try {
         sessionHandle = await ccWorkerPool.getSession({
+          runtime: llm._resolveRuntimeFor({ engineConfig }),
           tabId: resolvedTabId,
           model,
           effort,
@@ -11762,6 +11826,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
             age_minutes: ageMinutes,
           };
         }
+
         return {
           agentId: rec.agentId,
           valid: true,
@@ -11785,6 +11850,18 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     }
   }
 
+  async function handleWorktreeQuarantineRefs(req, res) {
+    try {
+      const { listQuarantineRefs } = require('./engine/quarantine-refs');
+      return jsonReply(res, 200, {
+        items: await listQuarantineRefs(PROJECTS),
+        generatedAt: new Date().toISOString(),
+      }, req);
+    } catch (e) {
+      return jsonReply(res, 500, { error: e.message }, req);
+    }
+  }
+
   async function handleKeepProcessesKill(req, res) {
     try {
       const body = await readBody(req);
@@ -13179,6 +13256,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     }},
     { method: 'GET', path: '/api/health', desc: 'Lightweight health check for monitoring', handler: handleHealth },
     { method: 'GET', path: '/api/keep-processes', desc: 'List all active agents/<id>/keep-pids.json entries (W-mp68q6ke0010de68)', handler: handleKeepProcessesList },
+    { method: 'GET', path: '/api/worktree-quarantine-refs', desc: 'List recoverable refs/minions/quarantine/* and quarantine-wip/* refs across configured projects', handler: handleWorktreeQuarantineRefs },
     { method: 'POST', path: '/api/keep-processes/kill', desc: 'Kill a single kept PID and remove it from the agent\'s keep-pids.json', params: 'agentId, pid', handler: handleKeepProcessesKill },
     // P-4b8d2e57 (managed-spawn item 4): engine-managed long-running services.
     // List/by-name return ETag + honor If-None-Match → 304. Kill removes from
@@ -13549,6 +13627,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           status: 'enrolled',
           prId: linkResult.id,
           autoManaged,
+          resurrected: linkResult.resurrected === true,
           contextOnly: false,
           project: linkResult.targetProject?.name || 'central',
           projectName: plan.projectName || linkResult.targetProject?.name || null,
@@ -14767,7 +14846,8 @@ if (require.main === module) {
     // supervisor) discovers it instead of guessing 7331. The original
     // server.on('error') one-shot exit is replaced by the retry loop — only
     // non-EADDRINUSE errors abort.
-    const maxScan = shared.DASHBOARD_PORT_SCAN_MAX || 100;
+    const requireRequestedPort = process.env.MINIONS_REQUIRE_DASHBOARD_PORT === '1';
+    const maxScan = requireRequestedPort ? 1 : (shared.DASHBOARD_PORT_SCAN_MAX || 100);
     let listenErr = null;
     for (let attempt = 0; attempt < maxScan; attempt++) {
       const tryPort = REQUESTED_PORT + attempt;
@@ -14793,7 +14873,10 @@ if (require.main === module) {
     }
     if (listenErr) {
       if (listenErr.code === 'EADDRINUSE') {
-        console.error(`\n  No free port in [${REQUESTED_PORT}..${REQUESTED_PORT + maxScan - 1}]. Free one and retry.\n`);
+        const range = requireRequestedPort
+          ? String(REQUESTED_PORT)
+          : `[${REQUESTED_PORT}..${REQUESTED_PORT + maxScan - 1}]`;
+        console.error(`\n  No free dashboard port at ${range}. Free it and retry.\n`);
       } else {
         console.error(listenErr);
       }

package/docs/README.md

@@ -29,6 +29,7 @@ Hands-on stories and distribution guides for people running or evaluating Minion
 Architecture, design proposals, and lifecycle references for people working on the engine, dashboard, or playbooks.
 
 - [branch-derivation.md](branch-derivation.md) — Engine-side branch fallback (`work/<wi-id>`) vs. agent-authored long form, the structured-vs-loose PR-pointer extractors, and the canonical PR-fix duplication incident.
+- [claude-md-propagation.md](claude-md-propagation.md) — Propagating repo-authored `CLAUDE.md` instructions to runtimes that don't auto-load it (Copilot/Codex): the `claudeMdNativeDiscovery` capability flag, the bounded nearest-applicable walk-up discovery, the `propagateClaudeMdForNonClaudeRuntimes` config knob, and why it's orthogonal to each runtime's native `AGENTS.md` discovery.
 - [command-center.md](command-center.md) — Command Center (CC) chat panel: configured-runtime sessions, resume semantics, system-prompt invalidation, and per-tab session storage.
 - [specs/agent-rename.md](specs/agent-rename.md) — Design spec for **agent rename & name decoupling** — the prerequisite for the Role/Agent Library. Formalizes the stable opaque agent id, makes charters name-agnostic, and adds `POST /api/agents/rename` (display name + emoji). Feature-flagged (`agent-rename`) and fully backward-compatible.
 - [specs/agent-configurability.md](specs/agent-configurability.md) — Design spec for the user-configurable Role / Agent Library, feature-flagged behind `agent-library` and fully backward-compatible. Builds on `agent-rename.md`. Role = the reusable durable charter; agent = a thin instance (identity + variable expertise + role pointer). Phase 0 renames `skills`→`expertise`; Phase 1 exposes/edits role charters + per-agent expertise; Phase 2 adds role/agent CRUD with builtin delete-protection.