@yemi33/minions 0.1.2178 → 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');
 
@@ -43,11 +44,12 @@ const steeringStore = require('./engine/steering-store');
 const projectDiscovery = require('./engine/project-discovery');
 const features = require('./engine/features');
 const ccWorkerPool = require('./engine/cc-worker-pool');
+const diagnosticsMemory = require('./engine/diagnostics-memory');
 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;
 
@@ -104,6 +106,122 @@ const KB_PINS_PATH = shared.PINNED_ITEMS_PATH;
 const DASHBOARD_BROWSER_PRESENCE_PATH = path.join(ENGINE_DIR, 'dashboard-browser.json');
 const DASHBOARD_BROWSER_PRESENCE_MAX_AGE_MS = 45000;
 
+// P-c3d4e5f6 — diagnostics-memory dashboard surface.
+// The engine writes its latest sample to engine/diagnostics-memory.json on
+// every memoryBaselineEveryTicks ticks; the dashboard reads it for
+// /api/diagnostics/memory and accumulates polled engine samples into its
+// own ring buffer (separate from diagnosticsMemory's own dashboard-self
+// buffer) for /api/diagnostics/memory/history?process=engine. Both rings
+// are in-process — restarting the dashboard zeroes them.
+const DIAGNOSTICS_MEMORY_SIDECAR_PATH = path.join(ENGINE_DIR, 'diagnostics-memory.json');
+const DIAGNOSTICS_MEMORY_STALE_MS = 5 * 60 * 1000;
+const DIAGNOSTICS_MEMORY_SAMPLE_INTERVAL_MS = 60000;
+const DIAGNOSTICS_MEMORY_ENGINE_RING_CAP = 1440;
+const _engineMemoryRing = [];
+let _lastEngineSampleCapturedAt = 0;
+let _memorySamplerStop = null;
+
+// Pure: assemble the /api/diagnostics/memory payload from already-read
+// inputs. Exported for direct unit testing — handler callers feed it the
+// live dashboard sample + the sidecar contents + Date.now().
+function _buildMemoryDiagnostics({ dashboardSample, engineSample, now } = {}) {
+  const _now = Number.isFinite(now) ? now : Date.now();
+  const dashboard = dashboardSample && typeof dashboardSample === 'object' ? dashboardSample : null;
+  // engineSample may be the literal object from the sidecar OR null/{} when
+  // the sidecar is missing/unparseable. Treat anything without a finite
+  // capturedAt as stale (covers both "file missing" and "ancient sample").
+  let engine = null;
+  let engineStale = true;
+  if (engineSample && typeof engineSample === 'object' && Number.isFinite(engineSample.capturedAt)) {
+    engine = engineSample;
+    engineStale = (_now - engineSample.capturedAt) > DIAGNOSTICS_MEMORY_STALE_MS;
+  }
+  return { dashboard, engine, engineStale };
+}
+
+// Pure: slice the requested ring buffer. Returns up to `limit` newest
+// samples (oldest first). `limit` defaults to the full buffer when missing
+// or non-positive (matches diagnosticsMemory.getHistory semantics).
+function _buildMemoryHistory({ ring, limit } = {}) {
+  if (!Array.isArray(ring)) return [];
+  const n = ring.length;
+  if (!Number.isInteger(limit) || limit <= 0 || limit >= n) return ring.slice();
+  return ring.slice(n - limit);
+}
+
+// Read the engine sidecar and, when it carries a never-seen-before
+// capturedAt, push it onto the engine-side ring buffer. Dedup is by
+// capturedAt so re-reads between engine baseline ticks don't bloat the
+// ring. Best-effort: any failure leaves the ring untouched.
+function _pollAndAccumulateEngineSample() {
+  let sample;
+  try { sample = safeJsonObj(DIAGNOSTICS_MEMORY_SIDECAR_PATH); }
+  catch { return; }
+  if (!sample || typeof sample !== 'object') return;
+  if (!Number.isFinite(sample.capturedAt)) return;
+  if (sample.capturedAt === _lastEngineSampleCapturedAt) return;
+  _lastEngineSampleCapturedAt = sample.capturedAt;
+  _engineMemoryRing.push(sample);
+  while (_engineMemoryRing.length > DIAGNOSTICS_MEMORY_ENGINE_RING_CAP) _engineMemoryRing.shift();
+}
+
+function _resetDiagnosticsMemoryForTesting() {
+  _engineMemoryRing.length = 0;
+  _lastEngineSampleCapturedAt = 0;
+  if (_memorySamplerStop) {
+    try { _memorySamplerStop(); } catch { /* ignore */ }
+    _memorySamplerStop = null;
+  }
+  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;
@@ -387,6 +505,25 @@ function inferActionPrRecord(action, prs, project = null) {
 }
 
 function copyWorkItemPrFields(item, input, pr = null) {
+  // W-mqbaby2a000pa8ee: Gate the LOOSE description/title scan in
+  // `shared.extractWorkItemPrRef` on `type: "fix"`. Without this gate,
+  // an implement/explore/test WI that merely mentions an existing PR
+  // in prose ("Class bug surfaced today on pull request 130") gets
+  // `targetPr` / `pr_id` / `prNumber` stamped, the engine then treats
+  // the WI as a fix against that PR, the PR-branch lookup fails, and
+  // the dispatch silently skips with `_pendingReason: null` forever.
+  //
+  // Structured PR pointers (`targetPr` / `pr_id` / `prUrl` / `prNumber` /
+  // `references[].url` / `meta.pr_followup.parent_pr_url`) are explicit
+  // operator intent — they stamp on EVERY type. An explicit `pr` record
+  // (caller already resolved the PR) also bypasses the gate. Only the
+  // last-resort description/title regex scan is type-gated.
+  if (!pr) {
+    const structuredRef = shared.extractStructuredWorkItemPrRef(input);
+    if (!structuredRef && String(item?.type || '').toLowerCase() !== WORK_TYPE.FIX) {
+      return;
+    }
+  }
   const prRef = getWorkItemPrRef(input);
   if (!prRef && !pr) return;
   const prNumber = pr ? shared.getPrNumber(pr) : shared.getPrNumber(prRef);
@@ -1044,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;
@@ -1951,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);
@@ -1958,6 +2341,7 @@ function _buildStatusSlowState() {
       const branchMismatch = !!(mainBranch && status.remoteDefaultBranch && mainBranch !== status.remoteDefaultBranch);
       return {
         name: p.name,
+        displayName: shared.projectDisplayName(p),
         path: p.localPath,
         description: p.description || '',
         ...status,
@@ -3497,13 +3881,25 @@ function getWorkItemPrRef(input) {
   // the dispatch to the existing PR branch instead of a fresh `work/<wi-id>`
   // parallel branch (issue #2999 / W-mpx6i5kh000ac040).
   //
-  // ASYMMETRY (W-mq18ec6h000p7b87): the engine's pr_not_found *gate* uses
-  // the strict `shared.extractStructuredWorkItemPrRef` — gate uses
-  // structured-only; stamp uses loose. Rationale: operators creating fix
-  // WIs via API often paste the PR URL in description prose and expect
-  // `targetPr` to get auto-stamped here (best-effort, reversible). The gate
-  // blocks dispatch and must require explicit operator intent (a structured
-  // field) before doing so.
+  // STRUCTURED-vs-LOOSE SPLIT (W-mq18ec6h000p7b87): two extractors exist —
+  //   - `shared.extractStructuredWorkItemPrRef`: structured fields +
+  //     `references[].url` + `meta.pr_followup.parent_pr_url`. NO scan.
+  //   - `shared.extractWorkItemPrRef` (this helper): structured walk + a
+  //     last-resort first-paragraph/title scan.
+  // The engine's `pr_not_found` dispatch gate uses the structured-only
+  // variant. The original design intent was that the stamp path could
+  // afford to be loose because gating would still require explicit
+  // operator intent.
+  //
+  // FIX-TYPE GATE on the stamp path (W-mqbaby2a000pa8ee): in practice
+  // the asymmetry leaked — the loose stamp writes to `item.pr_id` (a
+  // canonical structured field), and the strict gate later reads
+  // `item.pr_id` and sees the loose stamp AS IF it were structured
+  // intent. To stop that leak without changing the loose detector
+  // (which has other legitimate callers), `copyWorkItemPrFields` now
+  // gates the loose result on `item.type === "fix"`. Non-fix WIs only
+  // get stamped from structured fields (incl. references/follow-up).
+  // See the comment block on `copyWorkItemPrFields` above for details.
   return shared.extractWorkItemPrRef(input);
 }
 
@@ -5775,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);
@@ -5860,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 });
@@ -5886,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;
@@ -7954,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
@@ -9548,6 +9999,12 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       for (const key of Object.keys(childEnv)) {
         if (key === 'CLAUDECODE' || key.startsWith('CLAUDE_CODE') || key.startsWith('CLAUDECODE_')) delete childEnv[key];
       }
+      // W-mqb9y83o — suppress auto-open in the respawned dashboard. The
+      // restart endpoint is fired by CC or the dashboard UI; the operator
+      // already has a tab open (that's how they hit the button), so the
+      // post-restart hook must not pop a second one. Hard kill-switch read
+      // by bin/minions.js#spawnFullStackAndVerify.
+      childEnv.MINIONS_NO_AUTO_OPEN = '1';
       const proc = cpSpawn(process.execPath, [minionsBin, 'restart'], {
         cwd: MINIONS_DIR, stdio: 'ignore', detached: true, env: childEnv, windowsHide: true,
       });
@@ -10121,6 +10578,157 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     } catch (e) { return jsonReply(res, e.statusCode || 500, { error: e.message }); }
   }
 
+  // P-c3d4e5f6 — /api/diagnostics/memory.
+  // Returns the latest in-process dashboard sample, the latest engine
+  // sample (read fresh from engine/diagnostics-memory.json via safeJsonObj),
+  // and an engineStale boolean. Engine staleness is true when the sidecar
+  // is missing/unparseable OR its capturedAt is > 5 min old. The handler
+  // does one small JSON read and one in-process sample — < 10ms warm.
+  function handleDiagnosticsMemory(req, res) {
+    try {
+      let dashboardSample = null;
+      try { dashboardSample = diagnosticsMemory.sampleSelf({ label: 'dashboard' }); }
+      catch { /* leave dashboardSample null on sampler failure */ }
+      const engineSample = safeJsonObj(DIAGNOSTICS_MEMORY_SIDECAR_PATH);
+      const payload = _buildMemoryDiagnostics({
+        dashboardSample,
+        engineSample,
+        now: Date.now(),
+      });
+      return jsonReply(res, 200, payload, req);
+    } catch (e) {
+      return jsonReply(res, 500, { error: e.message }, req);
+    }
+  }
+
+  // P-c3d4e5f6 — /api/diagnostics/memory/history?process=engine|dashboard&limit=N.
+  // process=dashboard returns the diagnosticsMemory module's own ring
+  // buffer (populated by startPeriodicSampling on dashboard boot).
+  // process=engine returns the dashboard's accumulated polled snapshots
+  // of engine/diagnostics-memory.json — engine.js only persists the
+  // latest sample to the sidecar, so engine-side history is rebuilt by
+  // the dashboard's poller (dedup by capturedAt). Limit defaults to the
+  // full buffer when missing / non-positive.
+  function handleDiagnosticsMemoryHistory(req, res) {
+    try {
+      const u = new URL(req.url, 'http://x');
+      const proc = (u.searchParams.get('process') || '').trim().toLowerCase();
+      const limitRaw = u.searchParams.get('limit');
+      const limitParsed = limitRaw == null || limitRaw === '' ? null : parseInt(limitRaw, 10);
+      const limit = Number.isInteger(limitParsed) && limitParsed > 0 ? limitParsed : null;
+      let samples;
+      if (proc === 'dashboard') {
+        samples = diagnosticsMemory.getHistory(limit ? { limit } : {});
+      } else if (proc === 'engine') {
+        samples = _buildMemoryHistory({ ring: _engineMemoryRing, limit });
+      } else {
+        return jsonReply(res, 400, { error: 'process must be one of: engine, dashboard' }, req);
+      }
+      return jsonReply(res, 200, { process: proc, count: samples.length, samples }, req);
+    } catch (e) {
+      return jsonReply(res, 500, { error: e.message }, req);
+    }
+  }
+
+  // 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() —
@@ -11623,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 },
@@ -12198,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 },
@@ -12497,6 +13108,11 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     { method: 'POST', path: '/api/diagnostics/refresh', desc: 'Append a dashboard refresh-diagnostic ring buffer batch to engine/dashboard-diagnostics.log (rotated at 1 MB)', params: 'entries[]', handler: handleDiagnosticsRefresh },
     // Diagnostics — per-org ADO throttle state (W-mq03l6zh0006f0a1-d).
     { method: 'GET', path: '/api/diagnostics/ado-throttle', desc: 'Snapshot of per-org ADO throttle tracker state — { orgs: { [orgBase]: { throttled, retryAfter, consecutiveHits } } }. Falls back to a single `global` key when running against pre-per-org engines.', handler: handleDiagnosticsAdoThrottle },
+    // 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 ────────────────────────────────────────────────────────
@@ -12654,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
@@ -12695,6 +13312,11 @@ module.exports = {
   refreshStatusAsync,
   handleStatus: _handleStatusRequest,
   invalidateStatusCache,
+  // exported for testing — see test/unit/status-snapshot-budget.test.js (P-f2a3b4c5).
+  // The slim snapshot builder is the synchronous assembler used by getStatusJson()
+  // and refreshStatusAsync(); the budget test calls it directly to measure byte
+  // size and rebuild-time without standing up an HTTP server.
+  getStatus,
   // Raw state-file passthrough — exported for direct unit testing.
   handleStateRead,
   STATE_READ_ALLOWED_DIRS,
@@ -12717,6 +13339,27 @@ module.exports = {
   // route's `builder` closure (getWorkItems().map(slimWorkItemForList)).
   _slimWorkItemForList: slimWorkItemForList,
   _WORK_ITEMS_SLIM_DESCRIPTION_CAP: WORK_ITEMS_SLIM_DESCRIPTION_CAP,
+  // P-c3d4e5f6 — diagnostics-memory dashboard surface (handlers live in
+  // the request-dispatch closure; expose the pure builders + constants so
+  // unit tests can exercise the staleness gate and history slicing
+  // without binding a server.)
+  _buildMemoryDiagnostics,
+  _buildMemoryHistory,
+  _pollAndAccumulateEngineSample,
+  _resetDiagnosticsMemoryForTesting,
+  DIAGNOSTICS_MEMORY_SIDECAR_PATH,
+  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).
@@ -12807,15 +13450,19 @@ if (require.main === module) {
     Promise.resolve(queries.getKnowledgeBaseEntries())
       .catch(err => console.warn(`[dashboard] KB cache warm failed: ${err && err.message}`));
 
-    // Auto-open the browser unless suppressed. `minions restart` and the
-    // upgrade path set MINIONS_NO_AUTO_OPEN=1 because the CLI orchestrates the
-    // open itself after observing whether an existing tab reconnected.
-    if (!process.env.MINIONS_NO_AUTO_OPEN) {
-      const result = shared.openUrlInBrowser(`http://localhost:${PORT}`);
-      if (!result.ok) {
-        console.log(`  Could not auto-open browser: ${result.error}`);
-        console.log(`  Please open http://localhost:${PORT} manually.`);
-      }
+    // Auto-open the browser. `minions restart` and the upgrade path set
+    // MINIONS_NO_AUTO_OPEN=1 because the CLI orchestrates the open itself
+    // after observing whether an existing tab reconnected; the primitive
+    // (engine/shared.js#openUrlInBrowser) now owns the env-var check and
+    // emits a debug-level SUPPRESSED log entry so we can prove the kill-
+    // switch is firing.
+    const result = shared.openUrlInBrowser(`http://localhost:${PORT}`, {
+      reason: 'dashboard-self-open',
+      callerHint: 'dashboard.js:13124',
+    });
+    if (!result.ok && !result.suppressed) {
+      console.log(`  Could not auto-open browser: ${result.error}`);
+      console.log(`  Please open http://localhost:${PORT} manually.`);
     }
 
     // Warm the CC runtime binary cache off the request path so the first CC /
@@ -12871,12 +13518,39 @@ if (require.main === module) {
       }
     }, 30000).unref();
     console.log(`  Engine watchdog: active (checks every 30s)`);
+
+    // ─── Diagnostics: dashboard memory sampler (P-c3d4e5f6) ─────────────────
+    // Drive the diagnosticsMemory ring buffer for /api/diagnostics/memory and
+    // /api/diagnostics/memory/history?process=dashboard. The internal
+    // setInterval already calls recordSample for us; the onSample callback
+    // doubles as the engine-sidecar poller so /…/history?process=engine
+    // accumulates one entry per fresh engine MEMORY_BASELINE write
+    // (deduplicated by capturedAt).
+    try {
+      _memorySamplerStop = diagnosticsMemory.startPeriodicSampling({
+        intervalMs: DIAGNOSTICS_MEMORY_SAMPLE_INTERVAL_MS,
+        onSample: () => { try { _pollAndAccumulateEngineSample(); } catch { /* swallow */ } },
+      });
+      // Seed the engine ring immediately so the first call to
+      // /api/diagnostics/memory/history?process=engine right after boot
+      // already returns the latest sidecar sample without waiting a full
+      // sampling interval.
+      try { _pollAndAccumulateEngineSample(); } catch { /* swallow */ }
+    } catch (e) {
+      console.warn(`[dashboard] memory sampler failed to start: ${e && e.message}`);
+    }
   })();
 
   // ── Graceful shutdown: flush debounced writes + clear runtime port file ──
   function _gracefulShutdown() {
     try { flushPendingDocSessions(); } catch {}
     try { shared.clearDashboardPortFile(MINIONS_DIR); } catch {}
+    // P-c3d4e5f6 — stop the diagnostics-memory sampler cleanly so the
+    // setInterval handle doesn't keep the event loop alive on SIGTERM.
+    if (_memorySamplerStop) {
+      try { _memorySamplerStop(); } catch { /* swallow */ }
+      _memorySamplerStop = null;
+    }
   }
   server.on('close', () => _gracefulShutdown());
   process.on('SIGTERM', () => { _gracefulShutdown(); process.exit(0); });