@yemi33/minions 0.1.2381 → 0.1.2382

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 —

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

@@ -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);
 }
@@ -2961,15 +2971,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 +3191,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');
@@ -7688,7 +7731,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 +7768,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 +7795,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
@@ -11762,6 +11813,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 +11837,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 +13243,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
@@ -14767,7 +14832,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 +14859,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.

package/docs/claude-md-propagation.md

@@ -0,0 +1,118 @@
+# CLAUDE.md propagation to non-Claude runtimes
+
+**Work item:** W-mrdon0pe000l045a
+**Config flag:** `engine.propagateClaudeMdForNonClaudeRuntimes` (default `true`)
+**Per-project override:** `project.propagateClaudeMdForNonClaudeRuntimes`
+**Module:** `engine/claude-md-context.js` · **Injection:** `engine/playbook.js`
+
+## Problem
+
+`CLAUDE.md` auto-discovery is a **Claude-Code-CLI-only** convention — the `claude`
+binary reads repo-authored `CLAUDE.md` files itself at startup (unless `--bare`).
+The **Copilot** and **Codex** runtimes have **no equivalent auto-load** for
+`CLAUDE.md` at all. So repo-authored `CLAUDE.md` files — which frequently carry
+load-bearing "must be kept in sync" instructions and name blessed tooling — are
+structurally invisible to a Copilot/Codex-based fleet.
+
+### Motivating incident
+
+`W-mrdkv6zc00071fef` (a `fluidclientframework.android` dependency bump in
+`office/src`) missed a **third** sync-point file (`settings.gradle.kts:116`) that
+`loop/app/android/android/CLAUDE.md` explicitly warns about, and that
+`updateDeps.bat` (named in that same `CLAUDE.md`) would have caught via its build
+verification step. Neither the implementer nor the reviewer ever saw that file's
+content because Copilot has no `CLAUDE.md` auto-load mechanism. Propagating
+`CLAUDE.md` content directly addresses recurrence of this bug class.
+
+## Relationship to Copilot's native `AGENTS.md` discovery (NOT the same gap)
+
+Copilot has its **own native `AGENTS.md` auto-load**, which (post-#817, "Delegate
+repository harness discovery to native runtimes") Minions leaves to the runtime
+CLI itself rather than suppressing or synthesizing.
+
+`CLAUDE.md` propagation is **independent and additive**:
+
+- `CLAUDE.md` carries **zero split-brain risk** for Copilot/Codex, because those
+  runtimes **never read it themselves** — there is nothing to conflict with.
+- Therefore propagation is **orthogonal** to Copilot's native `AGENTS.md`
+  discovery: whether or not the runtime loads its own `AGENTS.md` has **no
+  effect** on `CLAUDE.md` propagation.
+
+| Concern | Owner | What governs it |
+|---------|-------|-----------------|
+| Copilot's OWN `AGENTS.md` auto-load | the Copilot CLI (native) | delegated to the runtime; Minions does not suppress or synthesize it |
+| Repo `CLAUDE.md` invisible to non-Claude runtimes | `propagateClaudeMdForNonClaudeRuntimes` | injects a "Project instructions (CLAUDE.md)" prompt layer |
+
+## Capability flag
+
+Each runtime adapter (`engine/runtimes/<name>.js`) declares
+`capabilities.claudeMdNativeDiscovery`:
+
+| Runtime | `claudeMdNativeDiscovery` | Propagation |
+|---------|---------------------------|-------------|
+| `claude` | `true` | **skipped** — the Claude CLI already reads CLAUDE.md; re-injecting would double it |
+| `copilot` | `false` | **injected** |
+| `codex` | `false` | **injected** |
+
+Unknown runtimes are treated as **not** auto-discovering (propagate), since an
+unrecognized runtime is far more likely to lack native CLAUDE.md loading than to
+have it. Engine code gates on the capability flag, never on `runtime.name`.
+
+## Bounded discovery algorithm
+
+`office/src` is a huge monorepo — a full tree walk collecting every `CLAUDE.md`
+is not viable. Instead the module mirrors how a human/tool resolves "nearest
+applicable instructions":
+
+1. **Collect path hints** for the dispatch (`engine.js#_deriveClaudeMdPathHints`):
+   `item.meta.workdir` and `item.references[*].path`.
+2. **Walk UP** from each hint directory toward the **project root**, `stat`-ing
+   `CLAUDE.md` at each ancestor level (`discoverClaudeMdFiles`).
+3. **Always include the project-root `CLAUDE.md`** as a fallback — if there are
+   no path hints, at minimum the project root is checked (discovery is never
+   skipped entirely).
+4. **Nearest-wins ordering:** deepest directory first, project root last, so the
+   most specific instructions lead.
+5. **Bounds (cheap by construction):**
+   - `MAX_WALK_DEPTH = 24` ancestor levels per hint (deep-path guard),
+   - `MAX_FILES = 8` total collected files,
+   - path-traversal guard — hints that escape the project root are dropped,
+   - the walk **never ascends above the project root**.
+
+This only `stat`s `CLAUDE.md` at a small number of ancestor directories, so it
+does not meaningfully slow dispatch even in a monorepo.
+
+## Injection & byte cap
+
+`engine/playbook.js#renderPlaybook` adds `CLAUDE.md` propagation as a context
+layer alongside the existing `pinned.md` → `notes.md` →
+`knowledge/agents/<agentId>.md` layers:
+
+- Header: `## Project instructions (CLAUDE.md)`, with a short provenance note so
+  the agent understands why it appears and that "keep in sync" rules are
+  authoritative.
+- Content is wrapped in an `<UNTRUSTED-INPUT>` fence (repo-authored, semi-trusted).
+- Each file is labeled by its repo-relative path (`### <relPath>`).
+- The whole block is capped at `ENGINE_DEFAULTS.maxNotesPromptBytes` (the same
+  budget the sibling notes / agent-memory layers use), so it can never balloon a
+  prompt on a large monorepo. Individual files are truncated with a
+  "read the full file if needed" marker when they exceed the remaining budget.
+
+Injection only happens when **all** hold:
+
+1. the resolved runtime's `claudeMdNativeDiscovery` is falsy (Copilot/Codex),
+2. `resolvePropagateClaudeMdForNonClaudeRuntimes(project, engine)` returns true,
+3. the project has a `localPath`, and
+4. at least one non-empty `CLAUDE.md` was discovered.
+
+## Config resolution
+
+`shared.resolvePropagateClaudeMdForNonClaudeRuntimes(project, engine)`:
+
+1. per-project boolean `project.propagateClaudeMdForNonClaudeRuntimes`, else
+2. fleet-wide boolean `engine.propagateClaudeMdForNonClaudeRuntimes`, else
+3. hardcoded default `true`.
+
+Only an explicit boolean counts as "set" at either level (undefined/null/string
+fall through). Editable from **Settings → Copilot Tuning → "Propagate CLAUDE.md
+to non-Claude runtimes"** or via `POST /api/settings`.