@yemi33/minions 0.1.2179 → 0.1.2181

package/README.md

@@ -57,7 +57,7 @@ node ~/.minions/minions.js init
 | `minions remove <dir-or-name> [--keep-data \| --purge --force]` | Unlink a project: cancels pending work items, drains dispatch + kills active agents, cleans worktrees, disables linked schedules, archives `projects/<name>/` to `projects/.archived/<name>-YYYYMMDD/`. Use `--keep-data` to leave the data dir in place, or `--purge --force` to delete it. |
 | `minions list` | List all linked projects with descriptions |
 | `minions restart` | Start engine and dashboard together (recommended after reboot) |
-| `minions start` | Start engine daemon (ticks every 10s, auto-syncs MCP servers) |
+| `minions start` | Start engine daemon (ticks every 10s) |
 | `minions stop` | Stop the engine |
 | `minions status` | Show agents, projects, dispatch queue, quality metrics |
 | `minions pause` / `resume` | Pause/resume dispatching |
@@ -71,7 +71,7 @@ node ~/.minions/minions.js init
 | `minions kill` | Kill all active agents and reset their dispatches to pending |
 | `minions complete <dispatch-id>` | Manually mark a dispatch as completed |
 | `minions config set-cli <R> [--model M]` | Persist the default runtime/model without starting the engine |
-| `minions mcp-sync` | Sync MCP servers from `~/.claude.json` |
+| `minions mcp-sync` | Print harness propagation diagnostic (read-only; same source as `minions doctor --harness`) |
 | `minions cleanup` | Run cleanup manually (temp files, worktrees, zombies) |
 | `minions dash` | Open dashboard (starts if not already running, port 7331) |
 | `minions nuke --confirm` | Factory reset runtime state and reset config to defaults |
@@ -322,9 +322,11 @@ When dispatching agents, the engine reads each project's `CLAUDE.md` and injects
 
 Agents need repo-host tooling to create PRs, post review comments, check status, and handle review feedback. GitHub repos use `gh`. Azure DevOps repos should use the `az` CLI first and keep the Azure DevOps MCP server available only as a fallback when `az` is unavailable or does not support the required operation.
 
-Agents inherit MCP servers directly from `~/.claude.json` as Claude Code processes — add fallback servers there and they're immediately available to all agents on next spawn.
+Agents inherit MCP servers, skills, and slash-commands directly from each runtime's native config — Claude reads `~/.claude.json` + `~/.claude/{skills,commands}/`, Copilot reads `~/.copilot/` + `~/.agents/`, Codex reads `~/.codex/`. Add fallback servers, skills, or commands there and they're immediately available to all agents on next spawn. No sync step is required.
 
-Manually refresh with `minions mcp-sync`.
+**What your agent sees.** On every dispatch, the engine merges three layers around the agent's worktree: (1) **user-scope** MCP servers, skills, and slash-commands from the runtime's home dir (e.g. `~/.claude/`, `~/.copilot/`); (2) **project-scope** equivalents from `<repo>/.claude/`, `<repo>/.copilot/`, `<repo>/.mcp.json` — propagated even when the worktree is on a different branch than your live checkout (gate: `engine.harnessPropagateProjectLocal`, default on); (3) **workspace MCPs** from the worktree's `.mcp.json`, pre-approved for Claude so the agent never has to prompt (gate: `engine.claudePreApproveWorkspaceMcps`, default on). Per-agent opt-out via `agent.hermeticHarness: true` (or fleet-wide `engine.hermeticHarness: true`) strips everything except `minionsDir`, giving you a known-empty harness for reproducible runs.
+
+To audit which propagation surfaces (asset dirs, skill roots, slash-command dirs, MCP config files) each runtime sees on this host, run `minions mcp-sync` (or `minions doctor --harness` for the same diagnostic with a non-zero exit on registry errors). Both commands are read-only — they print the per-runtime survey without mutating any state. See [docs/harness-propagation.md](docs/harness-propagation.md) for the propagation contract.
 
 ### GitHub Users
 
@@ -346,7 +348,7 @@ az login
 az devops configure --defaults organization=https://dev.azure.com/YOUR_ORG project=YOUR_PROJECT
 ```
 
-Optionally add the [Azure DevOps MCP server](https://github.com/microsoft/azure-devops-mcp) to your Claude Code settings (`~/.claude.json`) as a fallback. The engine will auto-sync it to all agents on next start.
+Optionally add the [Azure DevOps MCP server](https://github.com/microsoft/azure-devops-mcp) to your Claude Code settings (`~/.claude.json`) as a fallback. Agents inherit it on next spawn — no sync step needed.
 
 ## Work Items
 

package/bin/minions.js

@@ -10,7 +10,7 @@
  *   minions list                     List linked projects
  *   minions update [--no-wait]       Update to latest version (--no-wait backgrounds the post-update restart)
  *   minions version                  Show installed and package versions
- *   minions doctor                   Check prerequisites and runtime health
+ *   minions doctor [--harness]       Check prerequisites and runtime health (--harness: print harness propagation diagnostic)
  *   minions restart [--open]         Stop + start engine + dashboard (--open forces a new browser tab)
  *   minions start [--open]           Start engine + dashboard if not already running (no-op when up)
  *   minions stop                     Stop the engine
@@ -29,7 +29,7 @@
  *   minions config set-cli <R> [--model M]  Persist default runtime/model
  *   minions bridge <subcmd>          Constellation bridge: status|health|enable|disable
  *   minions plan <file|text> [proj]  Run a plan
- *   minions mcp-sync                 Sync MCP servers from ~/.claude.json
+ *   minions mcp-sync                 Print harness propagation diagnostic (read-only; same source as `doctor --harness`)
  *   minions nuke --confirm           Factory reset runtime state/config
  *   minions uninstall --confirm      Remove Minions and uninstall package
  */
@@ -1100,7 +1100,7 @@ if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
     minions init                     Bootstrap ~/.minions/ (first time)
     minions update [--no-wait]       Update to latest version (--no-wait backgrounds the restart)
     minions version                  Show installed vs package version
-    minions doctor                   Check prerequisites and runtime health
+    minions doctor [--harness]       Check prerequisites and runtime health (--harness: print harness propagation diagnostic)
     minions add <project-dir>        Link a project (interactive)
     minions remove <project-dir>     Unlink a project
     minions list                     List linked projects
@@ -1123,7 +1123,7 @@ if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
     minions config set-cli <R> [--model M]
                                       Persist default runtime/model without starting
     minions bridge <subcmd>          Constellation bridge: status|health|enable|disable
-    minions mcp-sync                 Sync MCP servers from ~/.claude.json
+    minions mcp-sync                 Print harness propagation diagnostic (read-only; same source as 'doctor --harness')
     minions cleanup                  Clean temp files, worktrees, zombies
     minions pr comment <repo> <n>    Post a marker-prepended PR comment via gh
                                        --agent <id> --kind <k> [--wi <id>] (--body-file <f> | --body <text>)
@@ -1450,8 +1450,17 @@ ${fs.existsSync(path.join(PKG_ROOT, '.git')) ? `
   console.log('    npm install -g @yemi33/minions && minions init\n');
 } else if (cmd === 'doctor') {
   ensureInstalled();
-  const { doctor } = require(path.join(MINIONS_HOME, 'engine', 'preflight'));
-  doctor(MINIONS_HOME).then(ok => process.exit(ok ? 0 : 1));
+  const { doctor, runHarnessDoctor } = require(path.join(MINIONS_HOME, 'engine', 'preflight'));
+  if (rest.includes('--harness')) {
+    // P-a3f9b2c1 — print the harness propagation diagnostic and exit. The
+    // legacy `minions doctor` still runs the full preflight + runtime fleet
+    // sweep; `--harness` is a one-shot survey of the asset-propagation
+    // surfaces only (see docs/harness-propagation.md).
+    const ok = runHarnessDoctor(MINIONS_HOME);
+    process.exit(ok ? 0 : 1);
+  } else {
+    doctor(MINIONS_HOME).then(ok => process.exit(ok ? 0 : 1));
+  }
 } else if (cmd === 'watchdog') {
   // External recovery scheduled by the OS. Survives cluster-kill scenarios
   // the in-process supervisor can't (Windows job-object teardown when the

package/dashboard/js/memory-panel.js

@@ -211,6 +211,66 @@ async function _memRefreshHistory() {
   }));
 }
 
+// P-e5f6a7b8 — operator-driven heap snapshot capture button. Gates the
+// POST behind a window.confirm() that calls out the multi-second stall
+// and the 50–200 MB per-process disk write. Renders the resulting paths
+// (and any engine timeout) into #memory-heap-snapshot-result via
+// textContent so the XSS gate remains clean.
+const HEAP_SNAPSHOT_CONFIRM_TOKEN = 'YES_I_UNDERSTAND_THIS_STALLS_THE_ENGINE';
+const HEAP_SNAPSHOT_CONFIRM_MSG =
+  'Capture a heap snapshot from BOTH the engine and dashboard processes?\n\n' +
+  '⚠️ Each process will be stalled for several seconds and will write a 50–200 MB ' +
+  '.heapsnapshot file under engine/diagnostics/. Only do this when actively ' +
+  'debugging a leak. Rate-limited to 1 capture per 60 seconds.';
+
+function _memSetHeapResult(text) {
+  const el = document.getElementById('memory-heap-snapshot-result');
+  if (el) el.textContent = text;
+}
+
+async function _memCaptureHeapSnapshot() {
+  const btn = document.getElementById('memory-heap-snapshot-btn');
+  if (typeof window !== 'undefined' && typeof window.confirm === 'function') {
+    if (!window.confirm(HEAP_SNAPSHOT_CONFIRM_MSG)) return;
+  }
+  if (btn) { btn.disabled = true; }
+  _memSetHeapResult('Capturing… (engine + dashboard each stall for several seconds)');
+  try {
+    const res = await fetch(
+      '/api/diagnostics/heap-snapshot?confirm=' + encodeURIComponent(HEAP_SNAPSHOT_CONFIRM_TOKEN),
+      { method: 'POST' });
+    let data = null;
+    try { data = await res.json(); } catch { /* empty body */ }
+    if (!res.ok) {
+      const msg = (data && (data.error || data.hint)) || ('HTTP ' + res.status);
+      _memSetHeapResult('Capture failed: ' + msg);
+      return;
+    }
+    const lines = [];
+    lines.push('Dashboard snapshot: ' + (data && data.dashboardSnapshot ? data.dashboardSnapshot : '(none)'));
+    if (data && data.engineTimedOut) {
+      lines.push('Engine snapshot:    TIMED OUT after ' + ((data.timeoutMs || 30000) / 1000) + 's ' +
+        '— the engine may have captured it after the dashboard gave up; check engine/diagnostics/.');
+    } else {
+      lines.push('Engine snapshot:    ' + (data && data.engineSnapshot ? data.engineSnapshot : '(none)'));
+    }
+    lines.push('');
+    lines.push('Load these in Chrome DevTools → Memory → Load to inspect.');
+    _memSetHeapResult(lines.join('\n'));
+  } catch (e) {
+    _memSetHeapResult('Capture failed: ' + (e && e.message ? e.message : String(e)));
+  } finally {
+    if (btn) { btn.disabled = false; }
+  }
+}
+
+function _memWireHeapSnapshotButton() {
+  const btn = document.getElementById('memory-heap-snapshot-btn');
+  if (!btn || btn.dataset.heapSnapshotWired === '1') return;
+  btn.dataset.heapSnapshotWired = '1';
+  btn.addEventListener('click', _memCaptureHeapSnapshot);
+}
+
 function mountMemoryPanel() {
   if (_memoryPanelMounted) return;
   // No-op when the engine page hasn't been assembled yet (defensive — the
@@ -222,6 +282,7 @@ function mountMemoryPanel() {
   _memRefreshHistory();
   _memoryPanelLiveInterval = setInterval(_memRefreshLive, MEMORY_POLL_LIVE_MS);
   _memoryPanelHistoryInterval = setInterval(_memRefreshHistory, MEMORY_POLL_HISTORY_MS);
+  _memWireHeapSnapshotButton();
 }
 
 function unmountMemoryPanel() {
@@ -259,4 +320,5 @@ window.MinionsMemoryPanel = {
   mountMemoryPanel,
   unmountMemoryPanel,
   _buildSparkline: _memBuildSparkline,
+  _captureHeapSnapshot: _memCaptureHeapSnapshot,
 };

package/dashboard/js/refresh.js

@@ -149,7 +149,9 @@ const RENDER_VERSIONS = {
   metrics: 1,
   workItems: 3,
   skills: 1,
+  commands: 1,
   mcpServers: 1,
+  harnessDiag: 1,
   schedules: 1,
   watches: 2,
   meetings: 1,
@@ -854,8 +856,24 @@ function _processStatusUpdate(data, opts) {
   });
   _changed('skills', data.skills);
   _safeRender('skills', function() { renderSkills(data.skills || []); });
+  _changed('commands', data.commands);
+  _safeRender('commands', function() { renderCommands(data.commands || []); });
   _changed('mcpServers', data.mcpServers);
   _safeRender('mcpServers', function() { renderMcpServers(data.mcpServers || []); });
+  // Harness propagation diagnostic comes from /api/harness/diagnostics
+  // (rare-change, fetched on each /api/status refresh so the tools page is
+  // always up to date when an operator drops a project-local skill).
+  _safeRender('harnessDiag', function() {
+    fetch('/api/harness/diagnostics')
+      .then(function (r) { return r.ok ? r.json() : Promise.reject(); })
+      .then(function (fresh) {
+        window._lastHarnessDiag = fresh;
+        _safeRender('harnessDiag', function() { renderHarnessDiagnostics(fresh); });
+      })
+      .catch(function () {
+        if (window._lastHarnessDiag) _safeRender('harnessDiag', function() { renderHarnessDiagnostics(window._lastHarnessDiag); });
+      });
+  });
   // Schedule definitions stay on /api/status (config-derived), but the
   // _lastRun/_lastResult overlay is re-applied client-side from
   // /state/engine/schedule-runs.json so a freshly-fired schedule lights up
@@ -1149,21 +1167,16 @@ document.addEventListener('visibilitychange', function() {
 // Ring buffer capturing the last 50 /api/status poll cycles so a user
 // reporting "the dashboard didn't auto-update when X changed" can paste
 // `window._refreshDiagnostics()` from devtools or click the "diag" footer
-// chip to surface a table. Gated behind feature flag
-// `dashboard-refresh-diagnostics` (engine/features.js) — disabled in
-// production, enabled in dev. When disabled, the helpers below are no-ops
-// (the boolean check is the first line of every collection path) so the
-// steady-state poll loop is byte-identical to its pre-flag behaviour.
+// chip to surface a table. The capture is cheap (in-memory ring buffer,
+// no network, no DOM writes) and always on (P-c1d4e8b6 deleted the
+// per-flag gate that had shipped default ON since v0.1.2034) so the next
+// staleness complaint can be diagnosed immediately from
+// window._refreshDiagnostics without a settings flip.
 const _DIAG_RING_SIZE = 50;
 const _refreshDiagBuf = [];
 let _prevRefreshTs = 0;
 let _diagHiddenSinceMs = 0; // ts when tab last went hidden; 0 when visible
 let _lastVisibilityChangeAt = 0;
-function _isRefreshDiagOn() {
-  try {
-    return !!(window.MinionsFeatures && window.MinionsFeatures.isOn('dashboard-refresh-diagnostics'));
-  } catch { return false; }
-}
 function _pushDiagEntry(entry) {
   _refreshDiagBuf.push(entry);
   if (_refreshDiagBuf.length > _DIAG_RING_SIZE) _refreshDiagBuf.shift();
@@ -1173,7 +1186,6 @@ function _pushDiagEntry(entry) {
 window._refreshDiagnostics = function() { return _refreshDiagBuf.slice(); };
 window._refreshDiagnosticsClear = function() { _refreshDiagBuf.length = 0; };
 document.addEventListener('visibilitychange', function() {
-  if (!_isRefreshDiagOn()) return;
   const now = Date.now();
   const vs = document.visibilityState;
   let hiddenForMs = null;
@@ -1202,11 +1214,10 @@ async function refresh(opts) {
   // console-spam and adds load to whatever's wedged).
   if (_nextPollAllowedAt && Date.now() < _nextPollAllowedAt) return;
   _refreshInFlight = true;
-  const _diagOn = _isRefreshDiagOn();
-  const _t0 = _diagOn ? Date.now() : 0;
-  const _gap = _diagOn && _prevRefreshTs ? _t0 - _prevRefreshTs : null;
-  if (_diagOn) _prevRefreshTs = _t0;
-  const _diagEntry = _diagOn ? {
+  const _t0 = Date.now();
+  const _gap = _prevRefreshTs ? _t0 - _prevRefreshTs : null;
+  _prevRefreshTs = _t0;
+  const _diagEntry = {
     ts: _t0,
     kind: 'refresh',
     gap_since_prev_ms: _gap,
@@ -1221,7 +1232,7 @@ async function refresh(opts) {
     changed: null,
     render_duration_ms: null,
     error_message: null,
-  } : null;
+  };
   try {
     const headers = {};
     if (_lastStatusEtag) headers['If-None-Match'] = _lastStatusEtag;
@@ -1235,16 +1246,14 @@ async function refresh(opts) {
     if (res.status === 304 && _lastStatusData) {
       // Cache hit — reuse last payload, skip parsing entirely.
       data = _lastStatusData;
-      if (_diagEntry) {
-        _diagEntry.response_status = '304';
-        _diagEntry.bytes_received = 0;
-        // D2: capture etag on 304 so the diag table can show whether the
-        // server's ETag advanced even when we're reusing the cached body.
-        // Without this the "etag↓" column is blank on every 304 row and the
-        // operator can't tell server-side advancement from a pinned cache.
-        const etag304 = res.headers && (res.headers.get ? res.headers.get('etag') : null);
-        if (etag304) _diagEntry.etag_received = etag304;
-      }
+      _diagEntry.response_status = '304';
+      _diagEntry.bytes_received = 0;
+      // D2: capture etag on 304 so the diag table can show whether the
+      // server's ETag advanced even when we're reusing the cached body.
+      // Without this the "etag↓" column is blank on every 304 row and the
+      // operator can't tell server-side advancement from a pinned cache.
+      const etag304 = res.headers && (res.headers.get ? res.headers.get('etag') : null);
+      if (etag304) _diagEntry.etag_received = etag304;
     } else {
       data = await res.json();
       const etag = res.headers && (res.headers.get ? res.headers.get('etag') : null);
@@ -1252,12 +1261,10 @@ async function refresh(opts) {
         _lastStatusEtag = etag;
         _lastStatusData = data;
       }
-      if (_diagEntry) {
-        _diagEntry.response_status = String(res.status);
-        _diagEntry.etag_received = etag || null;
-        const cl = res.headers && (res.headers.get ? res.headers.get('content-length') : null);
-        _diagEntry.bytes_received = cl != null && cl !== '' ? Number(cl) : null;
-      }
+      _diagEntry.response_status = String(res.status);
+      _diagEntry.etag_received = etag || null;
+      const cl = res.headers && (res.headers.get ? res.headers.get('content-length') : null);
+      _diagEntry.bytes_received = cl != null && cl !== '' ? Number(cl) : null;
     }
     // Auto-reload policy (2026-05-29):
     //   - dashboardStartedAt change → reload  (covers `minions restart`)
@@ -1284,31 +1291,26 @@ async function refresh(opts) {
     _consecutiveStatusFails = 0;
     _nextPollAllowedAt = 0;
     if (_unreachableSince) _markDashboardReachable();
-    const _renderStart = _diagOn ? Date.now() : 0;
-    let _diagChanges = null;
-    if (_diagOn) {
-      _diagChanges = {};
-      _lastChangedFlags = _diagChanges;
-    }
+    const _renderStart = Date.now();
+    const _diagChanges = {};
+    _lastChangedFlags = _diagChanges;
     try {
       _processStatusUpdate(data, opts);
     } finally {
-      if (_diagOn) {
-        _lastChangedFlags = null;
-        _diagEntry.render_duration_ms = Date.now() - _renderStart;
-        _diagEntry.changed = _diagChanges;
-        _diagEntry.workItems_changed = !!(_diagChanges && _diagChanges.workItems);
-        // Post-slim, data.workItems is undefined; read from the dedicated
-        // endpoint cache.
-        _diagEntry.workItems_count = (window._lastWorkItems || []).length;
-        _diagEntry.statusCacheVersion = (data.version && data.version.statusCacheVersion) != null
-          ? data.version.statusCacheVersion
-          : null;
-      }
+      _lastChangedFlags = null;
+      _diagEntry.render_duration_ms = Date.now() - _renderStart;
+      _diagEntry.changed = _diagChanges;
+      _diagEntry.workItems_changed = !!(_diagChanges && _diagChanges.workItems);
+      // Post-slim, data.workItems is undefined; read from the dedicated
+      // endpoint cache.
+      _diagEntry.workItems_count = (window._lastWorkItems || []).length;
+      _diagEntry.statusCacheVersion = (data.version && data.version.statusCacheVersion) != null
+        ? data.version.statusCacheVersion
+        : null;
     }
   } catch(e) {
     console.error('refresh error', e);
-    if (_diagEntry && !_diagEntry.response_status) {
+    if (!_diagEntry.response_status) {
       _diagEntry.response_status = (e && e.name === 'AbortError') ? 'abort' : 'error';
       _diagEntry.error_message = String((e && e.message) || e);
     }
@@ -1328,7 +1330,7 @@ async function refresh(opts) {
   }
   finally {
     _refreshInFlight = false;
-    if (_diagEntry) _pushDiagEntry(_diagEntry);
+    _pushDiagEntry(_diagEntry);
   }
 }
 
@@ -1376,15 +1378,11 @@ switchPage(currentPage);
 window.MinionsRefresh = { refresh };
 
 // ── Refresh-diagnostic footer chip + modal (W-mphejzx100081972) ───────────
-// Injected only when the dashboard-refresh-diagnostics feature flag is on
-// (engine/features.js → MINIONS_FEATURES.flags). The chip floats bottom-right
-// and opens a simple table view of the ring buffer plus a "send to engine"
-// button that POSTs the snapshot to /api/diagnostics/refresh. No DOM is
-// touched (and no listeners installed beyond the visibilitychange handler
-// above, which itself short-circuits when the flag is off) when the flag is
-// disabled — production behaviour stays untouched.
+// Always installed (P-c1d4e8b6 deleted the per-flag gate that previously
+// guarded this). The chip floats bottom-left and opens a simple table view
+// of the ring buffer plus a "send to engine" button that POSTs the
+// snapshot to /api/diagnostics/refresh.
 (function installRefreshDiagChip() {
-  if (!_isRefreshDiagOn()) return;
   try {
     const chip = document.createElement('button');
     chip.id = 'refresh-diag-chip';

package/dashboard/js/render-other.js

@@ -523,7 +523,148 @@ async function _addSelectedProjects() {
   }
 }
 
-window.MinionsOther = { renderProjects, optimisticallyAddProject, projectChipRemove, renderMcpServers, renderMetrics, renderLlmPerf, renderTokenUsage, _aggregateEngineUsageForTokenTile, openScanProjectsModal };
+function _scopeBadge(scope, projectName, pluginName) {
+  // PRD-shaped scope label (user|project:<name>|plugin|agent-skill). The
+  // commands feed today only emits user-roots (per-runtime), plugin, and
+  // project; agent-skill is reserved so when a runtime starts shipping
+  // agent-scoped commands they don't need a new badge style.
+  let label = scope;
+  let color = 'var(--muted)';
+  if (scope === 'project' && projectName) { label = 'project:' + projectName; color = 'var(--blue)'; }
+  else if (scope === 'plugin') { label = pluginName ? 'plugin:' + pluginName : 'plugin'; color = 'var(--purple)'; }
+  else if (scope === 'agent-skill') { color = 'var(--orange)'; }
+  else if (scope === 'claude-code' || scope === 'copilot' || scope === 'codex') {
+    label = 'user:' + scope;
+  }
+  return '<span style="font-size:var(--text-xs);color:' + color + ';margin-left:6px;font-weight:500">[' + escHtml(label) + ']</span>';
+}
+
+function renderCommands(commands) {
+  const el = document.getElementById('commands-list');
+  const countEl = document.getElementById('commands-count');
+  const arr = Array.isArray(commands) ? commands : [];
+  if (countEl) countEl.textContent = arr.length;
+  if (!el) return;
+  if (!arr.length) {
+    el.innerHTML = '<p class="empty">No slash commands found. Drop a <code>.md</code> file into <code>~/.claude/commands/</code>, <code>~/.copilot/commands/</code>, a plugin\'s commands dir, or a registered project\'s <code>.claude/commands/</code> — they\'ll appear here automatically.</p>';
+    return;
+  }
+
+  // Group by scope bucket so the list reads "user roots first, then plugins, then projects".
+  const buckets = new Map();
+  for (const c of arr) {
+    const key = c.scope === 'project' ? 'project:' + (c.projectName || '?')
+              : c.scope === 'plugin' ? 'plugin:' + (c.pluginName || '?')
+              : c.scope; // user-roots use their runtime name
+    if (!buckets.has(key)) buckets.set(key, []);
+    buckets.get(key).push(c);
+  }
+
+  const sections = [];
+  for (const [key, list] of buckets) {
+    const header = '<div style="font-size:var(--text-sm);color:var(--muted);text-transform:uppercase;letter-spacing:0.04em;margin:10px 0 4px">' + escHtml(key) + ' <span style="color:var(--muted);text-transform:none;letter-spacing:0">(' + list.length + ')</span></div>';
+    const rows = list.map(c =>
+      '<div style="font-size:var(--text-base);padding:4px 10px;background:var(--surface2);border:1px solid var(--border);border-radius:6px;color:var(--text);display:inline-flex;align-items:center;gap:6px;margin:2px 4px 2px 0" title="' + escHtml((c.title || '') + (c.rel ? '  •  ' + c.rel : '')) + '">' +
+        '<code style="color:var(--blue);background:transparent;padding:0">/' + escHtml(c.commandName || '') + '</code>' +
+        _scopeBadge(c.scope, c.projectName, c.pluginName) +
+      '</div>'
+    ).join('');
+    sections.push(header + '<div style="display:flex;flex-wrap:wrap;gap:4px">' + rows + '</div>');
+  }
+  // eslint-disable-next-line no-unsanitized/property -- reason: structural HTML is a string literal; all user data wrapped in escHtml() (fields: scope key, command name, project name, plugin name, title, rel path)
+  el.innerHTML = sections.join('') +
+    '<p style="font-size:var(--text-sm);color:var(--muted);margin:10px 0 0">Mirrors the runtime-native command roots that adapters expose via <code>getCommandRoots()</code>. Projects and plugins are aggregated alongside user-scope dirs.</p>';
+}
+
+function _harnessRowsBlock(label, rows) {
+  if (!rows || !rows.length) {
+    return '<div style="font-size:var(--text-sm);color:var(--muted);margin:4px 0 0 12px">' + escHtml(label) + ': <em>(adapter does not expose this)</em></div>';
+  }
+  const body = rows.map(r => {
+    const marker = r.exists ? '<span style="color:var(--green)">✓</span>' : '<span style="color:var(--orange)">⚠</span>';
+    const missing = r.exists ? '' : ' <span style="color:var(--orange);font-size:var(--text-xs)">(missing on disk)</span>';
+    return '<div style="font-family:monospace;font-size:var(--text-sm);margin-left:18px;display:flex;gap:8px;align-items:baseline">' +
+      marker + ' <span>' + escHtml(r.path) + '</span> <span style="color:var(--muted)">[' + escHtml(r.scope) + ']</span>' + missing +
+    '</div>';
+  }).join('');
+  return '<div style="margin:4px 0 0 12px"><div style="font-size:var(--text-sm);color:var(--muted);margin-bottom:2px">' + escHtml(label) + ':</div>' + body + '</div>';
+}
+
+function renderHarnessDiagnostics(diag) {
+  const el = document.getElementById('harness-diag');
+  if (!el) return;
+  if (!diag || typeof diag !== 'object') {
+    el.innerHTML = '<p class="empty">Harness diagnostics unavailable.</p>';
+    return;
+  }
+  const parts = [];
+  parts.push('<div style="font-size:var(--text-sm);color:var(--muted);margin-bottom:8px">Fleet-default runtime: <code style="color:var(--blue)">' + escHtml(diag.fleetDefaultCli || '?') + '</code></div>');
+
+  // Per-runtime adapter rows
+  for (const r of diag.runtimes || []) {
+    parts.push('<details style="margin:6px 0;border:1px solid var(--border);border-radius:6px;padding:8px 10px;background:var(--surface2)"><summary style="font-weight:600;cursor:pointer">Runtime: ' + escHtml(r.name) + '</summary>' +
+      _harnessRowsBlock('User asset dirs (--add-dir)', r.userAssetDirs) +
+      _harnessRowsBlock('Skill roots (CLI native discovery)', r.skillRoots) +
+      _harnessRowsBlock('Skill write targets', r.skillWriteTargets) +
+      _harnessRowsBlock('Slash command roots', r.commandRoots) +
+      _harnessRowsBlock('MCP config files', r.mcpConfigPaths) +
+    '</details>');
+  }
+
+  // --add-dir snapshot for fleet default
+  const snap = diag.addDirSnapshot || [];
+  parts.push('<details open style="margin:6px 0;border:1px solid var(--border);border-radius:6px;padding:8px 10px;background:var(--surface2)"><summary style="font-weight:600;cursor:pointer">--add-dir snapshot for ' + escHtml(diag.fleetDefaultCli || 'fleet default') + ' <span style="color:var(--muted);font-weight:400">(' + snap.length + ' dir' + (snap.length === 1 ? '' : 's') + ')</span></summary>' +
+    (snap.length === 0
+      ? '<div style="font-size:var(--text-sm);color:var(--muted);margin:6px 0 0 12px"><em>(no dirs attached — engine/spawn-agent.js unavailable or adapter has no asset dirs)</em></div>'
+      : snap.map(d =>
+          '<div style="font-family:monospace;font-size:var(--text-sm);margin-left:18px;display:flex;gap:8px;align-items:baseline"><span style="color:var(--green)">✓</span> <span>' + escHtml(d.path) + '</span> <span style="color:var(--muted)">[' + escHtml(d.scope) + ']</span></div>'
+        ).join('')
+    ) +
+  '</details>');
+
+  // Suppressed assets
+  const suppressed = diag.suppressed || [];
+  if (suppressed.length > 0) {
+    parts.push('<details open style="margin:6px 0;border:1px solid var(--border);border-radius:6px;padding:8px 10px;background:var(--surface2)"><summary style="font-weight:600;cursor:pointer">Suppressed assets <span style="color:var(--muted);font-weight:400">(' + suppressed.length + ')</span></summary>' +
+      suppressed.map(s =>
+        '<div style="margin:6px 0 0 12px"><code style="color:var(--orange)">' + escHtml(s.flag) + '</code> <span style="color:var(--muted);font-size:var(--text-sm)">(' + escHtml(String(s.value)) + ')</span>' +
+        '<div style="font-size:var(--text-sm);color:var(--muted);margin-left:18px">' + escHtml(s.effect || '') + '</div></div>'
+      ).join('') +
+    '</details>');
+  }
+
+  // Project-local-on-main footgun
+  const footgun = (diag.projectLocalOnMain || []).filter(e => e && e.uncommittedAssets && e.uncommittedAssets.length > 0);
+  if (footgun.length > 0) {
+    parts.push('<details open style="margin:6px 0;border:1px solid var(--orange);border-radius:6px;padding:8px 10px;background:var(--surface2)"><summary style="font-weight:600;cursor:pointer;color:var(--orange)">⚠ Project-local assets on main checkout (won\'t propagate to worktree)</summary>' +
+      footgun.map(entry =>
+        '<div style="margin:8px 0 0 12px">' +
+          '<div style="font-weight:600">' + escHtml(entry.project) + ' <span style="font-family:monospace;color:var(--muted);font-weight:400">' + escHtml(entry.localPath) + '</span></div>' +
+          '<div style="font-size:var(--text-sm);color:var(--muted);margin:4px 0 6px">' + escHtml(entry.footgunWarning || '') + '</div>' +
+          entry.uncommittedAssets.map(a =>
+            '<div style="font-family:monospace;font-size:var(--text-sm);margin-left:12px;display:flex;gap:8px;align-items:baseline"><span style="color:var(--orange)">⚠</span> <span>' + escHtml(a.file) + '</span> <span style="color:var(--muted)">[' + escHtml(a.kind) + ']</span></div>'
+          ).join('') +
+        '</div>'
+      ).join('') +
+    '</details>');
+  }
+
+  // Missing dirs summary (aggregate)
+  const missing = diag.missingDirs || [];
+  if (missing.length > 0) {
+    parts.push('<details style="margin:6px 0;border:1px solid var(--border);border-radius:6px;padding:8px 10px;background:var(--surface2)"><summary style="font-weight:600;cursor:pointer">Missing on-disk dirs <span style="color:var(--muted);font-weight:400">(' + missing.length + ')</span></summary>' +
+      '<div style="font-size:var(--text-sm);color:var(--muted);margin:4px 0 6px 12px">Adapters declare these paths but they do not exist on this host. Warnings, not failures — create them if the runtime should look there.</div>' +
+      missing.map(m =>
+        '<div style="font-family:monospace;font-size:var(--text-sm);margin-left:18px"><span style="color:var(--orange)">⚠</span> ' + escHtml(m.path) + ' <span style="color:var(--muted)">[' + escHtml(m.scope) + ' · ' + escHtml(m.kind) + ' · ' + escHtml(m.runtime) + ']</span></div>'
+      ).join('') +
+    '</details>');
+  }
+
+  // eslint-disable-next-line no-unsanitized/property -- reason: structural HTML is a string literal; all user data wrapped in escHtml() (fields: runtime name, path, scope, flag, effect, project name, localPath, file, kind)
+  el.innerHTML = parts.join('');
+}
+
+window.MinionsOther = { renderProjects, optimisticallyAddProject, projectChipRemove, renderMcpServers, renderCommands, renderHarnessDiagnostics, renderMetrics, renderLlmPerf, renderTokenUsage, _aggregateEngineUsageForTokenTile, openScanProjectsModal };
 
 // ─── keep_processes panel (W-mp68q6ke0010de68) ─────────────────────────────
 // Polls /api/keep-processes every refresh (engine page only) and renders a

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

@@ -372,6 +372,10 @@ async function editWorkItem(id, source) {
       '<label style="color:var(--text);font-size:var(--text-md)">Depends On (work-item ids, comma- or newline-separated)' +
         '<textarea id="wi-edit-depends-on" rows="2" placeholder="W-foo, W-bar" style="display:block;width:100%;margin-top:4px;padding:6px 8px;background:var(--bg);border:1px solid var(--border);border-radius:var(--radius-sm);color:var(--text);font-size:var(--text-md);font-family:inherit;resize:vertical">' + escapeHtml((Array.isArray(item.depends_on) ? item.depends_on : []).join(', ')) + '</textarea>' +
       '</label>' +
+      '<label style="color:var(--text);font-size:var(--text-md)">Working directory (subpath, optional)' +
+        '<input id="wi-edit-workdir" placeholder="packages/foo" value="' + escapeHtml((item.meta && item.meta.workdir) || '') + '" style="display:block;width:100%;margin-top:4px;padding:6px 8px;background:var(--bg);border:1px solid var(--border);border-radius:var(--radius-sm);color:var(--text);font-size:var(--text-md);font-family:inherit">' +
+        '<small style="display:block;margin-top:4px;color:var(--muted);font-size:var(--text-sm)">Relative POSIX subpath under the project root (or worktree, for code-mutating types). Leave empty to dispatch at the project root. Examples: <code>packages/foo</code>, <code>apps/dashboard</code>. Absolute paths and <code>..</code> segments are rejected.</small>' +
+      '</label>' +
       '<div style="display:flex;justify-content:flex-end;gap:8px;margin-top:8px">' +
         '<button onclick="closeModal()" class="pr-pager-btn" style="padding:6px 16px;font-size:var(--text-md)">Cancel</button>' +
         '<button onclick="submitWorkItemEdit(\'' + escapeHtml(id) + '\',\'' + escapeHtml(source || '') + '\',event)" class="btn-primary-lg">Save</button>' +
@@ -396,13 +400,14 @@ async function submitWorkItemEdit(id, source, e) {
   const acceptanceCriteria = acRaw.split('\n').filter(function(l) { return l.trim(); });
   const dependsRaw = document.getElementById('wi-edit-depends-on')?.value || '';
   const depends_on = dependsRaw.split(/[\n,]/).map(function(s) { return s.trim(); }).filter(Boolean);
+  const workdirRaw = (document.getElementById('wi-edit-workdir')?.value || '').trim();
   if (!title) { if (btn) { btn.disabled = false; btn.textContent = 'Save'; } alert('Title is required'); return; }
   try { closeModal(); } catch { /* may not be open */ }
   showToast('cmd-toast', 'Work item updated', true);
   try {
     const res = await fetch('/api/work-items/update', {
       method: 'POST', headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ id, source: source || undefined, title, description, type, priority, agent, references, acceptanceCriteria, depends_on })
+      body: JSON.stringify({ id, source: source || undefined, title, description, type, priority, agent, references, acceptanceCriteria, depends_on, workdir: workdirRaw || null })
     });
     if (res.ok) { refresh(); } else { const d = await res.json().catch(() => ({})); alert('Update failed: ' + (d.error || 'unknown')); editWorkItem(id, source); }
   } catch (e) { alert('Update error: ' + e.message); editWorkItem(id, source); }
@@ -592,6 +597,9 @@ function openCreateWorkItemModal() {
       '<label style="color:var(--text);font-size:var(--text-md)">Acceptance Criteria <textarea id="wi-new-ac" rows="2" style="' + inputStyle + ';resize:vertical" placeholder="One criterion per line (optional)"></textarea></label>' +
       '<label style="color:var(--text);font-size:var(--text-md)">Depends On <textarea id="wi-new-depends-on" rows="2" style="' + inputStyle + ';resize:vertical" placeholder="W-foo, W-bar — comma- or newline-separated work-item ids (optional)"></textarea></label>' +
       '<label style="color:var(--text);font-size:var(--text-md)">References <textarea id="wi-new-refs" rows="2" style="' + inputStyle + ';resize:vertical" placeholder="url | title | type — one per line (optional)"></textarea></label>' +
+      '<label style="color:var(--text);font-size:var(--text-md)">Working directory (subpath, optional) <input id="wi-new-workdir" style="' + inputStyle + '" placeholder="packages/foo — leave empty for project root">' +
+        '<small style="display:block;margin-top:4px;color:var(--muted);font-size:var(--text-sm)">Relative subpath under the project root. Use for monorepo subpackage dispatches so the agent\'s cwd lands inside <code>packages/foo</code> instead of the project root.</small>' +
+      '</label>' +
       '<label id="wi-new-skippr-row" style="color:var(--text);font-size:var(--text-md);display:flex;gap:8px;align-items:center;cursor:pointer"><input type="checkbox" id="wi-new-skippr"> Skip PR creation (push branch only)</label>' +
       '<div style="display:flex;justify-content:flex-end;gap:8px;margin-top:4px">' +
         '<button onclick="closeModal()" class="pr-pager-btn">Cancel</button>' +
@@ -629,6 +637,7 @@ async function _submitCreateWorkItem(e) {
     const parts = l.split('|').map(s => s.trim());
     return { url: parts[0] || '', title: parts[1] || parts[0] || '', type: parts[2] || 'link' };
   }).filter(r => r.url);
+  const workdir = (document.getElementById('wi-new-workdir')?.value || '').trim();
 
   try {
     const body = { title, description: desc, type, priority };
@@ -637,6 +646,7 @@ async function _submitCreateWorkItem(e) {
     if (acceptanceCriteria.length) body.acceptanceCriteria = acceptanceCriteria;
     if (references.length && references[0].url) body.references = references;
     if (depends_on.length) body.depends_on = depends_on;
+    if (workdir) body.meta = Object.assign({}, body.meta, { workdir: workdir });
     const skipPr = document.getElementById('wi-new-skippr')?.checked || false;
     if (skipPr) body.skipPr = true;
 
@@ -707,6 +717,13 @@ function _wiRenderDetail(item) {
   html += field('Description', '<div id="wi-detail-desc" style="font-size:var(--text-md);max-height:320px;overflow-y:auto;padding:8px 10px;background:var(--surface2);border:1px solid var(--border);border-radius:var(--radius-sm)">' + _descHtml + '</div>');
   html += field('Agent', escapeHtml(item.dispatched_to || item.agent || 'Auto'));
   html += field('Source', escapeHtml(item._source || 'central'));
+  // P-714ef144 — surface meta.workdir in the detail modal so operators can
+  // confirm the agent's actual cwd. Renders nothing when unset (which is
+  // the back-compat default = project root). Code-tagged so the path is
+  // visually clearly distinct from prose fields.
+  if (item.meta && typeof item.meta.workdir === 'string' && item.meta.workdir) {
+    html += field('Working directory', '<code style="font-size:var(--text-sm);background:var(--surface2);padding:2px 6px;border-radius:var(--radius-sm)">' + escapeHtml(item.meta.workdir) + '</code>');
+  }
   if (item.created) html += field('Created', escapeHtml(formatLocalDateTime(item.created)));
   if (item.dispatched_at) html += field('Dispatched', escapeHtml(formatLocalDateTime(item.dispatched_at)) + ' to ' + escapeHtml(item.dispatched_to || '?'));
   if (item.completedAt) html += field('Completed', escapeHtml(formatLocalDateTime(item.completedAt)));