@yemi33/minions 0.1.2179 → 0.1.2180

package/dashboard.js

@@ -14,6 +14,7 @@ const http = require('http');
 const zlib = require('zlib');
 const fs = require('fs');
 const path = require('path');
+const v8 = require('v8');
 const llm = require('./engine/llm');
 const { resolveRuntime } = require('./engine/runtimes');
 
@@ -48,7 +49,7 @@ const os = require('os');
 
 const { safeRead, safeReadOrNull, safeReadDir, safeWrite, safeJson, safeJsonObj, safeJsonArr, safeJsonNoRestore, safeUnlink, mutateJsonFileLocked, mutateTextFileLocked, mutateControl, mutateCooldowns, mutateWorkItems, getProjects: _getProjects, DONE_STATUSES, WI_STATUS, WORK_TYPE, WORKTREE_REQUIRING_TYPES, reopenWorkItem } = shared;
 const { getAgents, getAgentDetail, getPrdInfo, getWorkItems, getDispatchQueue,
-  getSkills, getInbox, getNotesWithMeta, getPullRequests,
+  getSkills, getCommands, getInbox, getNotesWithMeta, getPullRequests,
   getEngineLog, getMetrics, getKnowledgeBaseEntries, getKnowledgeBaseEntriesSnapshot, getProjectGitStatus, timeSince,
   MINIONS_DIR, AGENTS_DIR, ENGINE_DIR, INBOX_DIR, DISPATCH_PATH, PRD_DIR } = queries;
 
@@ -174,6 +175,53 @@ function _resetDiagnosticsMemoryForTesting() {
   try { diagnosticsMemory._resetForTest(); } catch { /* ignore */ }
 }
 
+// P-e5f6a7b8 — operator-driven heap snapshot capture for both dashboard
+// and engine processes. v8.writeHeapSnapshot stalls the calling process
+// for several seconds and emits a 50–200 MB file; the endpoint is
+// guarded by a literal confirm token + per-process rate limit + retention
+// cap so a runaway operator can't fill the disk or pin the engine.
+const DIAGNOSTICS_DIR = path.join(ENGINE_DIR, 'diagnostics');
+const HEAP_SNAPSHOT_REQUEST_PATH = path.join(DIAGNOSTICS_DIR, 'heap-snapshot-request.json');
+const HEAP_SNAPSHOT_CONFIRM_TOKEN = 'YES_I_UNDERSTAND_THIS_STALLS_THE_ENGINE';
+const HEAP_SNAPSHOT_RATE_LIMIT_MS = 60_000;
+const HEAP_SNAPSHOT_ENGINE_TIMEOUT_MS = 30_000;
+const HEAP_SNAPSHOT_ENGINE_POLL_MS = 250;
+const HEAP_SNAPSHOT_RETAIN_COUNT = 5;
+let _heapSnapshotLastCapturedAt = 0;
+
+// Pure: compose the on-disk path for a heap snapshot. ISO timestamps
+// contain colons (and a dot before the millis), which are illegal in
+// NTFS filenames — replace both with `-` so Windows isn't surprised.
+function _heapSnapshotPathFor(processLabel, iso) {
+  const safeIso = String(iso).replace(/[:.]/g, '-');
+  return path.join(DIAGNOSTICS_DIR, `heap-${processLabel}-${safeIso}.heapsnapshot`);
+}
+
+// Prune `heap-<processLabel>-*.heapsnapshot` files in `dir` down to the
+// most-recent `retain` by mtime. Best-effort: missing dir / unreadable
+// stat / failed unlink are swallowed (the next successful capture
+// retries the prune).
+function _heapSnapshotPrune(dir, processLabel, retain) {
+  let names;
+  try { names = fs.readdirSync(dir); }
+  catch { return; }
+  const prefix = `heap-${processLabel}-`;
+  const candidates = names.filter(n => n.startsWith(prefix) && n.endsWith('.heapsnapshot'));
+  if (candidates.length <= retain) return;
+  const stamped = candidates.map(n => {
+    try { return { n, mtime: fs.statSync(path.join(dir, n)).mtimeMs }; }
+    catch { return { n, mtime: 0 }; }
+  });
+  stamped.sort((a, b) => b.mtime - a.mtime); // newest first
+  for (const s of stamped.slice(retain)) {
+    try { fs.unlinkSync(path.join(dir, s.n)); } catch { /* best effort */ }
+  }
+}
+
+function _resetHeapSnapshotRateLimitForTesting() {
+  _heapSnapshotLastCapturedAt = 0;
+}
+
 function ensureConfiguredProjectStateFiles() {
   for (const p of PROJECTS) {
     const root = p.localPath ? path.resolve(p.localPath) : null;
@@ -1133,6 +1181,251 @@ function _resolveSkillReadPath({ file, dir, source, config, skillFiles } = {}) {
   return null;
 }
 
+// ── Harness propagation diagnostic (P-c601f9a2) ──────────────────────────────
+// Per-runtime view of where the CLI looks for skills/commands/MCPs, what the
+// engine actually attaches via --add-dir, which assets are explicitly
+// suppressed (e.g. AGENTS.md auto-load, Copilot's bundled github-mcp-server),
+// and the canonical footgun: per-project assets that live as uncommitted files
+// in the operator's main checkout but won't propagate to fresh worktrees.
+//
+// Surfaced via GET /api/harness/diagnostics and rendered on the Tools page so
+// operators can spot a missing or unpropagated harness asset without leaving
+// the dashboard. See docs/harness-propagation.md for the full contract.
+const HARNESS_FOOTGUN_DIRS = [
+  '.claude/skills',
+  '.claude/commands',
+  '.copilot/skills',
+  '.copilot/commands',
+  '.agents/skills',
+  '.agents/commands',
+];
+const HARNESS_FOOTGUN_FILES = [
+  '.claude/.mcp.json',
+  '.copilot/.mcp.json',
+  '.mcp.json',
+];
+
+const _PROJECT_LOCAL_FOOTGUN_WARNING =
+  'These files exist in your main checkout but are uncommitted or untracked in ' +
+  'git. A fresh `git worktree add` for a mutating dispatch will NOT see them, so ' +
+  'the dispatched agent silently underperforms. Fix: commit them, move them to ' +
+  'user scope (~/.claude/skills/..., ~/.copilot/skills/...), or flip the project ' +
+  'to live-checkout mode (worktreeMode: live).';
+
+function _walkUncommittedHarnessAssets(absStart, rootDir, projectName) {
+  const results = [];
+  const stack = [absStart];
+  let count = 0;
+  while (stack.length > 0 && count < 500) {
+    const cur = stack.pop();
+    let entries;
+    try { entries = fs.readdirSync(cur, { withFileTypes: true }); }
+    catch { continue; }
+    for (const ent of entries) {
+      if (ent.name === '.git' || ent.name === 'node_modules') continue;
+      const full = path.join(cur, ent.name);
+      if (ent.isDirectory()) { stack.push(full); continue; }
+      if (!ent.isFile()) continue;
+      const rel = path.relative(rootDir, full);
+      const normalized = rel.replace(/\\/g, '/');
+      let kind = null;
+      if (
+        normalized.startsWith('.claude/skills/') ||
+        normalized.startsWith('.copilot/skills/') ||
+        normalized.startsWith('.agents/skills/')
+      ) kind = 'skill';
+      else if (
+        normalized.startsWith('.claude/commands/') ||
+        normalized.startsWith('.copilot/commands/') ||
+        normalized.startsWith('.agents/commands/')
+      ) kind = 'command';
+      else if (
+        normalized === '.mcp.json' ||
+        normalized === '.claude/.mcp.json' ||
+        normalized === '.copilot/.mcp.json'
+      ) kind = 'mcp';
+      if (!kind) continue;
+      results.push({ file: rel, kind, scope: `project:${projectName}` });
+      count++;
+      if (count >= 500) break;
+    }
+  }
+  return results;
+}
+
+function _scanProjectLocalHarnessFootgun(project) {
+  const out = {
+    project: project && project.name ? project.name : '',
+    localPath: project && project.localPath ? project.localPath : '',
+    uncommittedAssets: [],
+    footgunWarning: _PROJECT_LOCAL_FOOTGUN_WARNING,
+  };
+  if (!project || !project.localPath) return out;
+  let raw = '';
+  try {
+    const { execFileSync } = require('child_process');
+    raw = execFileSync('git', ['status', '--porcelain', '-z'], {
+      cwd: project.localPath,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 10000,
+    });
+  } catch { return out; }
+  if (!raw) return out;
+  const records = raw.split('\0').filter(Boolean);
+  const seen = new Set();
+  for (const rec of records) {
+    if (rec.length < 4) continue;
+    const filePath = rec.slice(3);
+    const normalized = filePath.replace(/\\/g, '/');
+    const isDirRecord = normalized.endsWith('/');
+    const trimmed = isDirRecord ? normalized.slice(0, -1) : normalized;
+    let overlaps = false;
+    for (const dir of HARNESS_FOOTGUN_DIRS) {
+      if (
+        trimmed === dir ||
+        trimmed.startsWith(dir + '/') ||
+        dir.startsWith(trimmed + '/')
+      ) { overlaps = true; break; }
+    }
+    if (!overlaps) {
+      for (const file of HARNESS_FOOTGUN_FILES) {
+        if (trimmed === file || file.startsWith(trimmed + '/')) { overlaps = true; break; }
+      }
+    }
+    if (!overlaps) continue;
+
+    const absStart = path.join(project.localPath, filePath);
+    let stat;
+    try { stat = fs.statSync(absStart); } catch { continue; }
+    if (stat.isDirectory()) {
+      for (const asset of _walkUncommittedHarnessAssets(absStart, project.localPath, out.project)) {
+        if (seen.has(asset.file)) continue;
+        seen.add(asset.file);
+        out.uncommittedAssets.push(asset);
+      }
+    } else {
+      let kind = 'other';
+      if (normalized.includes('/skills/')) kind = 'skill';
+      else if (normalized.includes('/commands/')) kind = 'command';
+      else if (normalized.endsWith('.mcp.json')) kind = 'mcp';
+      if (seen.has(filePath)) continue;
+      seen.add(filePath);
+      out.uncommittedAssets.push({ file: filePath, kind, scope: `project:${out.project}` });
+    }
+  }
+  return out;
+}
+
+function _buildHarnessDiagnostics(opts = {}) {
+  const homeDir = opts.homeDir || os.homedir();
+  const engineConfig = opts.engineConfig || (CONFIG && CONFIG.engine) || {};
+  const projects = (opts.projects || PROJECTS || []).filter(
+    p => p && p.name && p.localPath && !String(p.name).startsWith('YOUR_'),
+  );
+  const existsFn = fs.existsSync;
+
+  let preflight, registry;
+  try { preflight = require('./engine/preflight'); }
+  catch { preflight = null; }
+  try { registry = require('./engine/runtimes'); }
+  catch { registry = null; }
+
+  const fleetDefaultCli = shared.resolveAgentCli(null, engineConfig);
+  const runtimeNames = registry ? registry.listRuntimes() : [];
+  const runtimes = [];
+  const missingDirs = [];
+
+  const slimRow = r => ({ path: r.path, scope: r.scope, exists: !!r.exists });
+  const collectMissing = (rows, runtimeName, kind) => {
+    for (const r of rows) {
+      if (r && !r.exists) {
+        missingDirs.push({ runtime: runtimeName, path: r.path, scope: r.scope, kind });
+      }
+    }
+  };
+
+  for (const runtimeName of runtimeNames) {
+    if (!preflight) break;
+    let runtime;
+    try { runtime = registry.resolveRuntime(runtimeName); }
+    catch { continue; }
+    if (!runtime) continue;
+    let rows;
+    try { rows = preflight._runtimeHarnessRows(runtime, { homeDir, projects, existsFn }); }
+    catch { continue; }
+    const userAssetDirs = rows.userAssetDirs.map(slimRow);
+    const skillRoots = [...rows.skillRootsUser, ...rows.skillRootsProject].map(slimRow);
+    const skillWriteTargets = rows.skillWriteTargets.map(slimRow);
+    const commandRoots = [...rows.commandRootsUser, ...rows.commandRootsProject].map(slimRow);
+    const mcpConfigPaths = [...rows.mcpConfigUser, ...rows.mcpConfigProject].map(slimRow);
+
+    runtimes.push({
+      name: runtimeName,
+      userAssetDirs,
+      skillRoots,
+      skillWriteTargets,
+      commandRoots,
+      mcpConfigPaths,
+    });
+
+    collectMissing(userAssetDirs, runtimeName, 'asset');
+    collectMissing(skillRoots, runtimeName, 'skill');
+    collectMissing(skillWriteTargets, runtimeName, 'skill-write');
+    collectMissing(commandRoots, runtimeName, 'command');
+    collectMissing(mcpConfigPaths, runtimeName, 'mcp');
+  }
+
+  let addDirSnapshot = [];
+  if (preflight && registry) {
+    let fleetRuntime = null;
+    try { fleetRuntime = registry.resolveRuntime(fleetDefaultCli); }
+    catch { fleetRuntime = null; }
+    if (fleetRuntime) {
+      const snapshot = preflight._computeAddDirSnapshot(fleetRuntime, {
+        minionsHome: MINIONS_DIR,
+        homeDir,
+        existsFn,
+      });
+      if (Array.isArray(snapshot)) addDirSnapshot = snapshot.map(slimRow);
+    }
+  }
+
+  const suppressed = [];
+  if (engineConfig.copilotSuppressAgentsMd !== false) {
+    suppressed.push({
+      flag: 'copilotSuppressAgentsMd',
+      value: true,
+      effect: 'Copilot --no-custom-instructions: in-tree AGENTS.md is NOT auto-loaded, so Minions playbook prompts are not overridden by repo-local instructions.',
+    });
+  }
+  if (engineConfig.copilotDisableBuiltinMcps !== false) {
+    suppressed.push({
+      flag: 'copilotDisableBuiltinMcps',
+      value: true,
+      effect: 'Copilot --disable-builtin-mcps: bundled github-mcp-server is stripped so dispatched agents do not open a parallel PR alongside the Minions PR.',
+    });
+  }
+  if (engineConfig.hermeticHarness === true) {
+    suppressed.push({
+      flag: 'hermeticHarness',
+      value: true,
+      effect: 'Hermetic harness mode: only the engine playbook + system prompt are surfaced; user-scope skills, commands, and MCP configs are NOT propagated to this dispatch.',
+    });
+  }
+
+  const projectLocalOnMain = projects.map(_scanProjectLocalHarnessFootgun);
+
+  return {
+    fleetDefaultCli,
+    runtimes,
+    addDirSnapshot,
+    suppressed,
+    projectLocalOnMain,
+    missingDirs,
+  };
+}
+
 function _agentSessionIsDraining(agentId) {
   const activeForAgent = (getDispatchQueue().active || []).some(d => d.agent === agentId);
   if (!activeForAgent) return false;
@@ -2040,6 +2333,7 @@ function _buildStatusSlowState() {
   // initialized + installId, and the version banner.
   return {
     skills: getSkills(),
+    commands: getCommands(CONFIG),
     mcpServers: getMcpServers(),
     projects: PROJECTS.map(p => {
       const status = getProjectGitStatus(p.localPath, p.mainBranch);
@@ -5877,11 +6171,24 @@ const server = http.createServer(async (req, res) => {
         if (!followupCheck.valid) {
           return jsonReply(res, 400, { error: followupCheck.error });
         }
+        // P-714ef144 — per-WI meta.workdir override validation. Same shape
+        // contract the engine enforces at dispatch time (shared.validateWorkItemWorkdir);
+        // running it here means the operator gets an immediate 400 instead
+        // of a deferred non-retryable INVALID_WORKDIR failure at dispatch.
+        const workdirCheck = shared.validateWorkItemWorkdir(body.meta.workdir);
+        if (!workdirCheck.valid) {
+          return jsonReply(res, 400, { error: `meta.workdir: ${workdirCheck.error}` });
+        }
         item.meta = { ...body.meta };
         if (followupCheck.value) {
           item.meta.pr_followup = followupCheck.value;
           validatedFollowup = followupCheck.value;
         }
+        if (workdirCheck.value === null) {
+          delete item.meta.workdir;
+        } else {
+          item.meta.workdir = workdirCheck.value;
+        }
       }
       // PR follow-up traceability headers (W-mpej3cox00099466).
       const originAgent = extractMinionsAgentHeader(req);
@@ -5962,6 +6269,24 @@ const server = http.createServer(async (req, res) => {
         if (!Array.isArray(body.depends_on)) return jsonReply(res, 400, { error: 'depends_on must be an array of strings' });
         if (!body.depends_on.every(s => typeof s === 'string')) return jsonReply(res, 400, { error: 'depends_on entries must be strings' });
       }
+      // P-714ef144 — pre-validate meta.workdir on the request body (same
+      // contract the engine enforces). Operators get an immediate 400
+      // instead of a deferred INVALID_WORKDIR at dispatch time. We tolerate
+      // three shapes here:
+      //   - body.workdir: "packages/foo"  (top-level convenience)
+      //   - body.meta: { workdir: "..." } (full meta replace — currently
+      //     never sent by the UI, but kept for symmetry with create)
+      //   - neither: no change to existing item.meta.workdir
+      let workdirUpdate; // undefined = no change, null = unset, string = set
+      if (body.workdir !== undefined) {
+        const wdCheck = shared.validateWorkItemWorkdir(body.workdir);
+        if (!wdCheck.valid) return jsonReply(res, 400, { error: `workdir: ${wdCheck.error}` });
+        workdirUpdate = wdCheck.value; // null or normalized string
+      } else if (body.meta && typeof body.meta === 'object' && 'workdir' in body.meta) {
+        const wdCheck = shared.validateWorkItemWorkdir(body.meta.workdir);
+        if (!wdCheck.valid) return jsonReply(res, 400, { error: `meta.workdir: ${wdCheck.error}` });
+        workdirUpdate = wdCheck.value;
+      }
 
       const target = resolveProjectSourceTarget(source, PROJECTS);
       if (target.error) return jsonReply(res, 404, { error: target.error });
@@ -5988,6 +6313,21 @@ const server = http.createServer(async (req, res) => {
         if (Array.isArray(body.depends_on)) {
           item.depends_on = body.depends_on.map(s => s.trim()).filter(Boolean);
         }
+        if (workdirUpdate !== undefined) {
+          // P-714ef144 — apply the workdir update. null clears the field
+          // (and the meta object if it becomes empty after the delete);
+          // a string value writes onto item.meta.workdir creating meta if
+          // it doesn't already exist.
+          if (workdirUpdate === null) {
+            if (item.meta && typeof item.meta === 'object') {
+              delete item.meta.workdir;
+              if (Object.keys(item.meta).length === 0) delete item.meta;
+            }
+          } else {
+            if (!item.meta || typeof item.meta !== 'object') item.meta = {};
+            item.meta.workdir = workdirUpdate;
+          }
+        }
         item.updatedAt = new Date().toISOString();
         result = { code: 200, body: { ok: true, item } };
         return items;
@@ -8056,6 +8396,15 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     return;
   }
 
+  async function handleHarnessDiagnostics(req, res) {
+    try {
+      const out = _buildHarnessDiagnostics();
+      return jsonReply(res, 200, out, req);
+    } catch (e) {
+      return jsonReply(res, 500, { error: e && e.message ? e.message : String(e) }, req);
+    }
+  }
+
   async function handleProjectsBrowse(req, res) {
     try {
       // Async child_process helpers — the picker dialog can sit on screen
@@ -10281,6 +10630,105 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     }
   }
 
+  // P-e5f6a7b8 — POST /api/diagnostics/heap-snapshot.
+  // Guarded by a literal confirm token + a 60s rate limit. On a valid
+  // request the handler synchronously calls v8.writeHeapSnapshot for the
+  // dashboard process (stalls THIS process for seconds, writes 50–200 MB),
+  // then drops a sentinel JSON in engine/diagnostics/ that engine.js
+  // consumes on its next tick to capture the engine-side snapshot. The
+  // handler polls for the engine snapshot for up to 30 s (sentinel
+  // removal + new file appearance) before returning. Retains the 5
+  // most-recent snapshots per process; oldest are auto-pruned on every
+  // successful capture.
+  async function handleDiagnosticsHeapSnapshot(req, res) {
+    try {
+      const u = new URL(req.url, 'http://x');
+      const confirm = (u.searchParams.get('confirm') || '').trim();
+      if (confirm !== HEAP_SNAPSHOT_CONFIRM_TOKEN) {
+        return jsonReply(res, 400, {
+          error: 'confirm token required',
+          hint:
+            `POST again with ?confirm=${HEAP_SNAPSHOT_CONFIRM_TOKEN}. ` +
+            `WARNING: capturing a heap snapshot stalls each process for several ` +
+            `seconds and writes a 50–200 MB file per process under engine/diagnostics/.`,
+        }, req);
+      }
+      const now = Date.now();
+      if (_heapSnapshotLastCapturedAt && (now - _heapSnapshotLastCapturedAt) < HEAP_SNAPSHOT_RATE_LIMIT_MS) {
+        const retryAfter = Math.ceil((HEAP_SNAPSHOT_RATE_LIMIT_MS - (now - _heapSnapshotLastCapturedAt)) / 1000);
+        res.setHeader('Retry-After', String(Math.max(1, retryAfter)));
+        return jsonReply(res, 429, {
+          error: `rate limit: at most 1 successful heap snapshot per ${HEAP_SNAPSHOT_RATE_LIMIT_MS / 1000}s`,
+          retryAfterSeconds: Math.max(1, retryAfter),
+        }, req);
+      }
+
+      try { fs.mkdirSync(DIAGNOSTICS_DIR, { recursive: true }); }
+      catch (e) { return jsonReply(res, 500, { error: `mkdir diagnostics dir failed: ${e.message}` }, req); }
+
+      const iso = new Date().toISOString();
+      const dashboardSnapshotPath = _heapSnapshotPathFor('dashboard', iso);
+      const expectedEnginePath = _heapSnapshotPathFor('engine', iso);
+
+      // Dashboard side — synchronous; this stalls the event loop for seconds.
+      try { v8.writeHeapSnapshot(dashboardSnapshotPath); }
+      catch (e) { return jsonReply(res, 500, { error: `dashboard writeHeapSnapshot failed: ${e.message}` }, req); }
+
+      // Sentinel for engine.js. Engine reads its own ISO from the sentinel
+      // so the engine snapshot lands at the predictable predicted path.
+      try {
+        fs.writeFileSync(HEAP_SNAPSHOT_REQUEST_PATH, JSON.stringify({ requestedAt: iso }));
+      } catch (e) {
+        return jsonReply(res, 500, { error: `sentinel write failed: ${e.message}` }, req);
+      }
+
+      // Poll for engine snapshot — sentinel removed AND the predicted file
+      // exists. Fall back to the newest engine snapshot if the predicted
+      // path isn't there (engine wrote a different ISO somehow).
+      const deadline = Date.now() + HEAP_SNAPSHOT_ENGINE_TIMEOUT_MS;
+      let engineSnapshotPath = null;
+      while (Date.now() < deadline) {
+        let sentinelGone = false;
+        try { sentinelGone = !fs.existsSync(HEAP_SNAPSHOT_REQUEST_PATH); } catch { sentinelGone = false; }
+        if (sentinelGone) {
+          if (fs.existsSync(expectedEnginePath)) {
+            engineSnapshotPath = expectedEnginePath;
+            break;
+          }
+          try {
+            const newest = fs.readdirSync(DIAGNOSTICS_DIR)
+              .filter(n => n.startsWith('heap-engine-') && n.endsWith('.heapsnapshot'))
+              .map(n => ({ n, m: (() => { try { return fs.statSync(path.join(DIAGNOSTICS_DIR, n)).mtimeMs; } catch { return 0; } })() }))
+              .sort((a, b) => b.m - a.m)[0];
+            if (newest) {
+              engineSnapshotPath = path.join(DIAGNOSTICS_DIR, newest.n);
+              break;
+            }
+          } catch { /* directory race */ }
+        }
+        await new Promise(r => setTimeout(r, HEAP_SNAPSHOT_ENGINE_POLL_MS));
+      }
+      const engineTimedOut = !engineSnapshotPath;
+
+      // Stamp the rate-limit window on completion, regardless of engine
+      // timeout — the operator already paid the dashboard-stall cost.
+      _heapSnapshotLastCapturedAt = Date.now();
+
+      // Prune oldest snapshots per process down to the retention cap.
+      try { _heapSnapshotPrune(DIAGNOSTICS_DIR, 'dashboard', HEAP_SNAPSHOT_RETAIN_COUNT); } catch { /* best effort */ }
+      try { _heapSnapshotPrune(DIAGNOSTICS_DIR, 'engine', HEAP_SNAPSHOT_RETAIN_COUNT); } catch { /* best effort */ }
+
+      return jsonReply(res, 200, {
+        dashboardSnapshot: path.resolve(dashboardSnapshotPath),
+        engineSnapshot: engineSnapshotPath ? path.resolve(engineSnapshotPath) : null,
+        engineTimedOut,
+        timeoutMs: HEAP_SNAPSHOT_ENGINE_TIMEOUT_MS,
+      }, req);
+    } catch (e) {
+      return jsonReply(res, e.statusCode || 500, { error: e.message }, req);
+    }
+  }
+
   // Slim UX surface for the experimental redesigned dashboard.
   // The markup/CSS/JS live as fragments under dashboard/slim/ (layout.html +
   // styles.css + body.html + js/*.js) and are assembled by buildSlimHtml() —
@@ -11783,8 +12231,8 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     { method: 'POST', path: '/api/qa/runners/reload', desc: 'Clear the in-process runner registry, re-register built-ins, and re-scan qa-runners.d/ for plugin edits.', handler: handleQaRunnersReload },
 
     // Work items
-    { method: 'POST', path: '/api/work-items', desc: 'Create a new work item', params: 'title, type?, description?, priority?, project?, agent?, agents?, scope?, references?, acceptanceCriteria?, skipPr?, oneShot?, meta?, meta.pr_followup?, X-Minions-Agent?, X-Minions-Origin-Wi?', handler: handleWorkItemsCreate },
-    { method: 'POST', path: '/api/work-items/update', desc: 'Edit a pending/failed work item', params: 'id, source?, title?, description?, type?, priority?, agent?, references?, acceptanceCriteria?', handler: handleWorkItemsUpdate },
+    { method: 'POST', path: '/api/work-items', desc: 'Create a new work item', params: 'title, type?, description?, priority?, project?, agent?, agents?, scope?, references?, acceptanceCriteria?, skipPr?, oneShot?, meta?, meta.pr_followup?, meta.workdir?, X-Minions-Agent?, X-Minions-Origin-Wi?', handler: handleWorkItemsCreate },
+    { method: 'POST', path: '/api/work-items/update', desc: 'Edit a pending/failed work item', params: 'id, source?, title?, description?, type?, priority?, agent?, references?, acceptanceCriteria?, depends_on?, workdir?, meta?', handler: handleWorkItemsUpdate },
     { method: 'POST', path: '/api/work-items/retry', desc: 'Reset a failed/dispatched item to pending', params: 'id, source?', handler: handleWorkItemsRetry },
     { method: 'POST', path: '/api/work-items/delete', desc: 'Remove a work item, kill agent, clear dispatch', params: 'id, source?', handler: handleWorkItemsDelete },
     { method: 'POST', path: '/api/work-items/cancel', desc: 'Cancel a work item, kill agent, clear dispatch', params: 'id, source?, reason?', handler: handleWorkItemsCancel },
@@ -12358,6 +12806,9 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     // Skills
     { method: 'GET', path: '/api/skill', desc: 'Read a skill file', params: 'file, source?, dir?', handler: handleSkillRead },
 
+    // Harness propagation diagnostic (P-c601f9a2)
+    { method: 'GET', path: '/api/harness/diagnostics', desc: 'Per-runtime harness diagnostic (add-dirs, suppressed flags, project-local-on-main footgun, missing dirs)', handler: handleHarnessDiagnostics },
+
     // Projects
     { method: 'POST', path: '/api/projects/browse', desc: 'Open folder picker dialog, return selected path', handler: handleProjectsBrowse },
     { method: 'POST', path: '/api/projects/scan', desc: 'Scan a directory for git repos', params: 'path?, depth?', handler: handleProjectsScan },
@@ -12660,6 +13111,8 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     // Diagnostics — engine + dashboard memory baseline (P-c3d4e5f6).
     { method: 'GET', path: '/api/diagnostics/memory', desc: 'Latest in-process dashboard memory sample plus the most-recent engine sample read from engine/diagnostics-memory.json. engineStale=true when the sidecar is missing or its capturedAt is > 5 min old.', handler: handleDiagnosticsMemory },
     { method: 'GET', path: '/api/diagnostics/memory/history', desc: 'In-memory ring buffer of memory samples. process=dashboard returns the dashboard\'s own collector (populated by startPeriodicSampling on boot). process=engine returns the dashboard\'s polled accumulation of engine/diagnostics-memory.json — engine.js only persists the latest sample to the sidecar, so engine-side history is rebuilt by the dashboard poller (dedup by capturedAt). Optional limit caps returned newest-N samples.', params: 'process (engine|dashboard), limit?', handler: handleDiagnosticsMemoryHistory },
+    // Diagnostics — operator-driven heap snapshot capture (P-e5f6a7b8).
+    { method: 'POST', path: '/api/diagnostics/heap-snapshot', desc: 'Capture v8 heap snapshots for both the dashboard and engine processes. Requires ?confirm=YES_I_UNDERSTAND_THIS_STALLS_THE_ENGINE because v8.writeHeapSnapshot stalls each process for several seconds and writes a 50–200 MB file. Rate-limited to 1 successful call per 60s; retains the 5 most-recent snapshots per process under engine/diagnostics/.', params: 'confirm=YES_I_UNDERSTAND_THIS_STALLS_THE_ENGINE', handler: handleDiagnosticsHeapSnapshot },
   ];
 
   // ── Route Dispatcher ────────────────────────────────────────────────────────
@@ -12817,6 +13270,7 @@ module.exports = {
   _linkPullRequestForTracking: linkPullRequestForTracking,
   _updatePullRequestObserveFlag: updatePullRequestObserveFlag,
   _resolveSkillReadPath,
+  _buildHarnessDiagnostics,
   // exported for testing — see test/unit/plans-archive-warnings.test.js
   _archivePrdPostProcess,
   // Per-CC-turn correlation surface
@@ -12897,6 +13351,15 @@ module.exports = {
   DIAGNOSTICS_MEMORY_STALE_MS,
   DIAGNOSTICS_MEMORY_SAMPLE_INTERVAL_MS,
   DIAGNOSTICS_MEMORY_ENGINE_RING_CAP,
+  // P-e5f6a7b8 — heap snapshot helpers exposed for direct unit testing.
+  _heapSnapshotPathFor,
+  _heapSnapshotPrune,
+  _resetHeapSnapshotRateLimitForTesting,
+  HEAP_SNAPSHOT_REQUEST_PATH,
+  HEAP_SNAPSHOT_CONFIRM_TOKEN,
+  HEAP_SNAPSHOT_RATE_LIMIT_MS,
+  HEAP_SNAPSHOT_ENGINE_TIMEOUT_MS,
+  HEAP_SNAPSHOT_RETAIN_COUNT,
 };
 
 // Start the HTTP server only when run directly (node dashboard.js).