@yemi33/minions 0.1.2179 → 0.1.2181

package/engine/spawn-agent.js

@@ -55,6 +55,15 @@ function parseSpawnArgs(argv) {
   let runtimeName = 'claude';
   const opts = {};
   const passthrough = [];
+  // P-08b62d49 — accumulating array of project-local-on-main harness dirs that
+  // engine.js wants `computeAddDirs` to surface as additional `--add-dir`
+  // entries. Multiple `--project-harness-dir <path>` flags accumulate in
+  // declaration order; the dedup/exists filter happens inside `computeAddDirs`.
+  const projectHarnessDirs = [];
+  // P-49e1c8b7 — hermetic harness opt-out (boolean). Set by engine.js when
+  // shared.resolveAgentHermeticHarness(agent, engine) is true; propagates to
+  // computeAddDirs which then returns [minionsDir] only.
+  let hermetic = false;
 
   for (let i = 2; i < args.length; i++) {
     const a = args[i];
@@ -77,6 +86,17 @@ function parseSpawnArgs(argv) {
       case '--disable-builtin-mcps':       opts.disableBuiltinMcps = true; break;
       case '--no-custom-instructions':     opts.suppressAgentsMd = true; break;
       case '--enable-reasoning-summaries': opts.reasoningSummaries = true; break;
+      case '--project-harness-dir': {
+        const v = peek();
+        if (typeof v === 'string' && v) projectHarnessDirs.push(v);
+        break;
+      }
+      // P-49e1c8b7 — hermetic harness opt-out. When set, computeAddDirs in
+      // main() returns [minionsDir] only (user-scope asset dirs from
+      // runtime.getUserAssetDirs AND any forwarded --project-harness-dir
+      // entries are dropped). Engine.js gates this flag via
+      // shared.resolveAgentHermeticHarness(agent, engine).
+      case '--hermetic-harness':           hermetic = true; break;
       // LEGACY: dropped — the runtime adapter emits its own permission flag.
       // Pre-P-2a6d9c4f engine.js still passes `--permission-mode bypassPermissions`;
       // letting it through would duplicate the permission flag for Claude.
@@ -85,7 +105,7 @@ function parseSpawnArgs(argv) {
     }
   }
 
-  return { promptFile, sysPromptFile, runtimeName, opts, passthrough };
+  return { promptFile, sysPromptFile, runtimeName, opts, passthrough, projectHarnessDirs, hermetic };
 }
 
 /**
@@ -299,18 +319,39 @@ function createParentPipeForwarder(stream, outputPath, prefix = '') {
 
 /**
  * Build the `--add-dir` list passed to the runtime CLI. Pure: takes
- * `{ runtime, minionsDir, homeDir, exists }` and returns an ordered, deduped
- * array of dirs the agent should be able to read from outside its worktree.
+ * `{ runtime, minionsDir, homeDir, projectHarnessDirs, hermetic, exists }`
+ * and returns an ordered, deduped array of dirs the agent should be able to
+ * read from outside its worktree.
+ *
+ * Order:
+ *   1. minionsDir (always first, so playbooks/system-prompt are reachable).
+ *   2. Every existing dir from `runtime.getUserAssetDirs({ homeDir })` —
+ *      user-scope skill/command/MCP roots (`~/.claude`, `~/.copilot`,
+ *      `~/.agents`, …) so worktree-bound agents inherit user-installed
+ *      harnesses.
+ *   3. P-08b62d49 — Every existing dir in `projectHarnessDirs` (engine.js
+ *      passes the union of `queries.getProjectHarnesses(project).{skills,
+ *      commands}` dirs that live in `project.localPath` but NOT under the
+ *      worktree, so uncommitted `<repo>/.claude/skills/…` etc. on the main
+ *      checkout are reachable from worktree dispatches). See
+ *      `docs/harness-propagation.md` → "The worktree-uncommitted footgun".
  *
- * Order: minionsDir first (so playbooks/system-prompt are always reachable),
- * followed by every existing dir from `runtime.getUserAssetDirs({ homeDir })`.
- * Non-existent asset dirs are dropped — Claude CLI rejects unknown `--add-dir`
- * entries. The dedup compares resolved paths so we never emit minionsDir twice
- * (e.g. when runtime asset dir IS the minions repo in unusual setups).
+ * Non-existent dirs are dropped at every layer — Claude CLI rejects unknown
+ * `--add-dir` entries. The dedup compares resolved paths so we never emit a
+ * dir twice (e.g. when a runtime asset dir IS the minions repo in unusual
+ * setups, or when a project-harness dir duplicates a user-asset dir).
+ *
+ * P-49e1c8b7 — When `hermetic === true`, the result is exactly `[minionsDir]`:
+ * both the runtime adapter's user-asset dirs AND `projectHarnessDirs` are
+ * dropped so the spawned agent runs with a known-empty harness surface.
+ * Engine.js sets this via `shared.resolveAgentHermeticHarness(agent, engine)`
+ * and forwards `--hermetic-harness` to spawn-agent so the flag survives the
+ * subprocess hop.
  *
  * `exists` is injectable for tests; defaults to `fs.existsSync`.
  */
-function computeAddDirs({ runtime, minionsDir, homeDir, exists = fs.existsSync } = {}) {
+function computeAddDirs({ runtime, minionsDir, homeDir, projectHarnessDirs, hermetic, exists = fs.existsSync } = {}) {
+  if (hermetic) return [minionsDir];
   const out = [minionsDir];
   const seen = new Set([path.resolve(minionsDir)]);
   const assetDirs = typeof runtime?.getUserAssetDirs === 'function'
@@ -324,9 +365,121 @@ function computeAddDirs({ runtime, minionsDir, homeDir, exists = fs.existsSync }
     out.push(d);
     seen.add(resolved);
   }
+  if (Array.isArray(projectHarnessDirs)) {
+    for (const d of projectHarnessDirs) {
+      if (!d) continue;
+      const resolved = path.resolve(d);
+      if (seen.has(resolved)) continue;
+      if (!exists(d)) continue;
+      out.push(d);
+      seen.add(resolved);
+    }
+  }
   return out;
 }
 
+/**
+ * P-7d31a06b — Pre-approve a worktree's `.mcp.json` servers in `~/.claude.json`
+ * so Claude Code's first invocation in a fresh worktree cwd doesn't show the
+ * project-scoped "trust this MCP server?" prompt (which `--dangerously-skip-permissions`
+ * silently suppresses → the agent runs without the workspace MCPs).
+ *
+ * Writes to `projects[worktreePath].enabledMcpjsonServers` (the field Claude
+ * Code actually reads — confirmed against the live `~/.claude.json` schema:
+ * `enabledMcpjsonServers` / `disabledMcpjsonServers` are siblings of
+ * `mcpServers`, indexed by absolute project path). Notes on the PRD wording
+ * "mcpServers.approved": that's the intent label; `enabledMcpjsonServers` is
+ * the on-disk reality.
+ *
+ * Pure-ish: all I/O (fs reads, mutator) is injected for tests. Best-effort —
+ * callers MUST swallow errors and never block dispatch on this.
+ *
+ * Returns `{ wrote: boolean, reason: string, servers: string[] }`:
+ *   - reason ∈ { 'ok', 'flag-off', 'not-claude', 'no-worktree',
+ *                'no-workspace-mcp', 'invalid-workspace-mcp', 'no-servers' }
+ *   - servers: keys discovered in the workspace `.mcp.json` (regardless of write)
+ *
+ * Args:
+ *   runtimeName             — `runtime.name` from `resolveRuntime(...)`. Helper no-ops if !== 'claude'.
+ *   worktreePath            — absolute path to the agent's cwd (the worktree). Used as both the file location
+ *                             (`<worktreePath>/.mcp.json`) and the `projects[...]` key in `~/.claude.json`.
+ *   homeDir                 — `os.homedir()`. Injected for test isolation; helper does NOT call os.homedir directly.
+ *   engineConfig            — config.engine object; reads `claudePreApproveWorkspaceMcps` (default true via ENGINE_DEFAULTS).
+ *   mutateJsonFileLocked    — injected file-locked mutator (engine/shared.js#mutateJsonFileLocked).
+ *   existsSync, readFileSync — injectable fs primitives (default to node:fs).
+ */
+function preApproveWorkspaceMcps({
+  runtimeName,
+  worktreePath,
+  homeDir,
+  engineConfig,
+  mutateJsonFileLocked,
+  existsSync = fs.existsSync,
+  readFileSync = fs.readFileSync,
+} = {}) {
+  if (engineConfig && engineConfig.claudePreApproveWorkspaceMcps === false) {
+    return { wrote: false, reason: 'flag-off', servers: [] };
+  }
+  if (runtimeName !== 'claude') {
+    return { wrote: false, reason: 'not-claude', servers: [] };
+  }
+  if (!worktreePath || typeof worktreePath !== 'string') {
+    return { wrote: false, reason: 'no-worktree', servers: [] };
+  }
+  const workspaceMcpPath = path.join(worktreePath, '.mcp.json');
+  if (!existsSync(workspaceMcpPath)) {
+    return { wrote: false, reason: 'no-workspace-mcp', servers: [] };
+  }
+  let workspaceMcp;
+  try {
+    workspaceMcp = JSON.parse(readFileSync(workspaceMcpPath, 'utf8'));
+  } catch {
+    return { wrote: false, reason: 'invalid-workspace-mcp', servers: [] };
+  }
+  const serversObj = workspaceMcp && typeof workspaceMcp === 'object' ? workspaceMcp.mcpServers : null;
+  const servers = serversObj && typeof serversObj === 'object' && !Array.isArray(serversObj)
+    ? Object.keys(serversObj).filter((k) => typeof k === 'string' && k.length > 0)
+    : [];
+  if (servers.length === 0) {
+    return { wrote: false, reason: 'no-servers', servers: [] };
+  }
+  if (!homeDir || typeof mutateJsonFileLocked !== 'function') {
+    return { wrote: false, reason: 'no-home-or-mutator', servers };
+  }
+  const claudeJsonPath = path.join(homeDir, '.claude.json');
+  let didWrite = false;
+  mutateJsonFileLocked(claudeJsonPath, (data) => {
+    const root = data && typeof data === 'object' ? data : {};
+    if (!root.projects || typeof root.projects !== 'object') root.projects = {};
+    const projectKey = worktreePath;
+    const proj = root.projects[projectKey] && typeof root.projects[projectKey] === 'object'
+      ? root.projects[projectKey]
+      : {};
+    // enabledMcpjsonServers is Claude's actual on-disk approval field
+    const enabled = Array.isArray(proj.enabledMcpjsonServers) ? proj.enabledMcpjsonServers.slice() : [];
+    const disabled = Array.isArray(proj.disabledMcpjsonServers) ? proj.disabledMcpjsonServers.slice() : [];
+    const enabledSet = new Set(enabled.filter((s) => typeof s === 'string'));
+    let mutated = false;
+    for (const name of servers) {
+      if (!enabledSet.has(name)) {
+        enabledSet.add(name);
+        mutated = true;
+      }
+    }
+    // If a server was previously explicitly disabled, lift the disabled mark when we
+    // re-approve it — otherwise Claude treats the disabled entry as authoritative.
+    const nextDisabled = disabled.filter((s) => typeof s === 'string' && !servers.includes(s));
+    if (nextDisabled.length !== disabled.length) mutated = true;
+    if (!mutated) return data;
+    proj.enabledMcpjsonServers = [...enabledSet];
+    proj.disabledMcpjsonServers = nextDisabled;
+    root.projects[projectKey] = proj;
+    didWrite = true;
+    return root;
+  }, { defaultValue: {}, skipWriteIfUnchanged: true });
+  return { wrote: didWrite, reason: 'ok', servers };
+}
+
 // ─── Main script execution ──────────────────────────────────────────────────
 
 function _installHint(name, runtime) {
@@ -345,7 +498,7 @@ function main() {
     console.error('Usage: node spawn-agent.js <prompt-file> <sysprompt-file> [--runtime <name>] [args...]');
     process.exit(1);
   }
-  const { promptFile, sysPromptFile, runtimeName, opts, passthrough } = parsed;
+  const { promptFile, sysPromptFile, runtimeName, opts, passthrough, projectHarnessDirs, hermetic } = parsed;
 
   const env = cleanChildEnv();
   injectAdoTokenEnvForRepoHost(env);
@@ -382,8 +535,21 @@ function main() {
   // Skill discovery dirs — agents run with CWD set to an external repo
   // worktree, so runtime-native global assets would otherwise be invisible.
   // The adapter owns both where those assets live and how to surface them.
+  // P-08b62d49: engine.js also forwards uncommitted project-local harness
+  // dirs from the operator's main checkout via `--project-harness-dir <path>`
+  // (one per dir, accumulated in `projectHarnessDirs`) so worktree-bound
+  // agents inherit them too. See docs/harness-propagation.md.
+  // P-49e1c8b7: when engine.js passes `--hermetic-harness`, computeAddDirs
+  // returns [minionsDir] only — both user-asset dirs and project harness
+  // dirs are dropped for a known-empty harness surface.
   const minionsDir = path.resolve(__dirname, '..');
-  const addDirs = computeAddDirs({ runtime, minionsDir, homeDir: os.homedir() });
+  const addDirs = computeAddDirs({
+    runtime,
+    minionsDir,
+    homeDir: os.homedir(),
+    projectHarnessDirs,
+    hermetic,
+  });
 
   let resolved;
   try { resolved = runtime.resolveBinary({ env }); }
@@ -639,6 +805,6 @@ function main() {
   });
 }
 
-module.exports = { parseSpawnArgs, buildSpawnInvocation, normalizeRuntimeExit, shouldInjectAdoTokenEnv, injectAdoTokenEnv, injectAdoTokenEnvForRepoHost, writeProcessExitSentinel, computeAddDirs, createParentPipeForwarder, assertStaleHeadOk };
+module.exports = { parseSpawnArgs, buildSpawnInvocation, normalizeRuntimeExit, shouldInjectAdoTokenEnv, injectAdoTokenEnv, injectAdoTokenEnvForRepoHost, writeProcessExitSentinel, computeAddDirs, preApproveWorkspaceMcps, createParentPipeForwarder, assertStaleHeadOk };
 
 if (require.main === module) main();

package/engine.js

@@ -175,6 +175,13 @@ const { runPostCompletionHooks, updateWorkItemStatus, syncPrdItemStatus, reconci
 const diagnosticsMemory = require('./engine/diagnostics-memory');
 const DIAGNOSTICS_MEMORY_PATH = path.join(ENGINE_DIR, 'diagnostics-memory.json');
 
+// P-e5f6a7b8 — sentinel consumed each tick; dashboard.js writes it after
+// validating the operator confirm token. We pick up the iso the dashboard
+// chose so the engine snapshot file lands at a predictable path the
+// dashboard can directly poll for.
+const DIAGNOSTICS_DIR = path.join(ENGINE_DIR, 'diagnostics');
+const HEAP_SNAPSHOT_REQUEST_PATH = path.join(DIAGNOSTICS_DIR, 'heap-snapshot-request.json');
+
 // ─── Agent Spawner ──────────────────────────────────────────────────────────
 
 const activeProcesses = new Map(); // dispatchId → { proc, agentId, startedAt }
@@ -1701,9 +1708,54 @@ async function spawnAgent(dispatchItem, config) {
   // stages now short-circuit alongside any other read-only WI (see the gate at
   // `if (branchName && READ_ONLY_ROOT_TASK_TYPES.has(type))` below).
   const _preBranchName = meta?.branch ? sanitizeBranch(meta.branch) : null;
+
+  // ── Per-WI meta.workdir override (P-714ef144) ─────────────────────────
+  // Optional relative POSIX subpath on the work item that lands the agent
+  // at <base>/<workdir> instead of <base>. Used for monorepo subpackage
+  // dispatches so the runtime CLI's cwd-rooted skill discovery surfaces
+  // only the target package's `.claude/skills/<name>/SKILL.md` files.
+  // Validation runs at dispatch time (the dashboard also validates on
+  // create/update — this is defense-in-depth for ad-hoc dispatches and
+  // upgrades that re-dispatch pre-validator WIs). Containment escapes are
+  // non-retryable: the operator must fix the WI's meta.workdir or remove
+  // it before a retry would succeed.
+  const _rawWorkdir = meta?.item?.meta?.workdir;
+  const _wdValidation = shared.validateWorkItemWorkdir(_rawWorkdir);
+  if (!_wdValidation.valid) {
+    const _wiId = meta?.item?.id || meta?.workItemId || id;
+    log('warn', `spawnAgent: meta.workdir validation rejected dispatch ${id} (WI ${_wiId}): ${_wdValidation.error}`);
+    try {
+      writeInboxAlert(`invalid-workdir-${_wiId}`, [
+        `# Invalid meta.workdir on ${_wiId}`,
+        ``,
+        `Dispatch \`${id}\` for agent \`${agentId}\` was rejected before spawn.`,
+        ``,
+        `**Reason:** ${_wdValidation.error}`,
+        ``,
+        `**Submitted value:** \`${typeof _rawWorkdir === 'string' ? _rawWorkdir : JSON.stringify(_rawWorkdir)}\``,
+        ``,
+        `**Project:** \`${project?.name || '(unknown)'}\` (localPath: \`${project?.localPath || '(none)'}\`)`,
+        ``,
+        `meta.workdir must be a relative POSIX subpath under the project root (or worktree, for code-mutating types). Examples: \`packages/foo\`, \`apps/dashboard\`. Absolute paths, drive-letter prefixes, \`..\` segments, and null bytes are rejected.`,
+        ``,
+        `Fix the WI's \`meta.workdir\` field (or remove it to dispatch at the project root) and re-dispatch.`,
+      ].join('\n'));
+    } catch (e) { log('warn', `invalid-workdir inbox alert write failed: ${e.message}`); }
+    completeDispatch(
+      id,
+      DISPATCH_RESULT.ERROR,
+      _wdValidation.error.slice(0, 800),
+      'meta.workdir validation rejected this dispatch — fix the WI subpath or remove it before re-dispatch.',
+      { failureClass: FAILURE_CLASS.INVALID_WORKDIR, agentRetryable: false },
+    );
+    cleanupTempAgent(agentId);
+    return null;
+  }
+  const validatedWorkdir = _wdValidation.value;  // null when unset / empty
+
   let cwd, worktreeRootDir, liveMode = false;
   try {
-    ({ cwd, worktreeRootDir, liveMode = false } = shared.resolveSpawnPaths(project, type, MINIONS_DIR));
+    ({ cwd, worktreeRootDir, liveMode = false } = shared.resolveSpawnPaths(project, type, MINIONS_DIR, { workdir: validatedWorkdir }));
   } catch (rootErr) {
     if (rootErr?.code === 'WORKTREE_ROOTDIR_COLLAPSED_TO_DRIVE_ROOT' || rootErr?.code === 'WORKTREE_ROOTDIR_MISSING_BASE') {
       log('error', `spawnAgent: project rootDir resolution failed for ${id}: ${rootErr.message}`);
@@ -1718,6 +1770,38 @@ async function spawnAgent(dispatchItem, config) {
       cleanupTempAgent(agentId);
       return null;
     }
+    if (rootErr?.code === 'INVALID_WORKDIR') {
+      // Post-resolve containment escape from live or read-only branch (the
+      // pre-resolve validator above already caught the common cases; this
+      // catches symlink-style attacks where the literal subpath looks fine
+      // but path.resolve lands outside the base).
+      const _wiId = meta?.item?.id || meta?.workItemId || id;
+      log('warn', `spawnAgent: workdir post-resolve escape for ${id} (WI ${_wiId}): ${rootErr.message}`);
+      try {
+        writeInboxAlert(`invalid-workdir-${_wiId}`, [
+          `# Invalid meta.workdir on ${_wiId} (post-resolve escape)`,
+          ``,
+          `Dispatch \`${id}\` for agent \`${agentId}\` was rejected by the resolver containment guard.`,
+          ``,
+          `**Reason:** ${rootErr.message}`,
+          ``,
+          `**Submitted value:** \`${validatedWorkdir || ''}\``,
+          ``,
+          `**Project:** \`${project?.name || '(unknown)'}\` (localPath: \`${project?.localPath || '(none)'}\`)`,
+          ``,
+          `The literal subpath passed shape validation but path.resolve landed outside the base directory — usually a symlink in the project root pointing elsewhere. Fix the WI's meta.workdir or remove the offending symlink before re-dispatch.`,
+        ].join('\n'));
+      } catch (e) { log('warn', `invalid-workdir inbox alert write failed: ${e.message}`); }
+      completeDispatch(
+        id,
+        DISPATCH_RESULT.ERROR,
+        rootErr.message.slice(0, 800),
+        'meta.workdir resolved outside the project/worktree base — fix the subpath or remove it.',
+        { failureClass: FAILURE_CLASS.INVALID_WORKDIR, agentRetryable: false },
+      );
+      cleanupTempAgent(agentId);
+      return null;
+    }
     throw rootErr;
   }
   // Legacy local alias: downstream git ops (worktree add, prune, fetch) and
@@ -3086,6 +3170,15 @@ async function spawnAgent(dispatchItem, config) {
   // Other runtimes ignore the opt (their buildSpawnFlags don't read it), so no
   // runtime.name branch here.
   const resolvedDisabledMcpServers = shared.resolveCopilotAgentDisabledMcpServers(agentConfig, engineConfig);
+  // P-49e1c8b7 — hermetic harness opt-out (per-agent override allowed).
+  // When true, this dispatch:
+  //   - skips Claude workspace .mcp.json pre-approval (preApproveWorkspaceMcps),
+  //   - skips project-local-on-main `--project-harness-dir` propagation,
+  //   - forwards `--hermetic-harness` to spawn-agent.js so computeAddDirs
+  //     returns [minionsDir] only (user-asset dirs stripped from --add-dir).
+  // Independent of copilotDisableBuiltinMcps and copilotSuppressAgentsMd,
+  // which retain their existing semantics.
+  const resolvedHermetic = shared.resolveAgentHermeticHarness(agentConfig, engineConfig);
 
   // W-mpg6isvy000xca4d — On retry after FAILURE_CLASS.MODEL_UNAVAILABLE, swap
   // to the runtime-appropriate fallback model. Two paths gated on
@@ -3145,6 +3238,39 @@ async function spawnAgent(dispatchItem, config) {
 
   // MCP servers: agents inherit from ~/.claude.json directly as Claude Code processes.
   // No --mcp-config needed — avoids redundant config and ensures agents always have latest servers.
+  //
+  // P-7d31a06b — When the runtime is Claude AND the worktree has a `.mcp.json`,
+  // pre-warm `~/.claude.json` projects.<worktreePath>.enabledMcpjsonServers so
+  // Claude's first call doesn't show the project-MCP trust prompt (which
+  // --dangerously-skip-permissions silently suppresses → agent runs without the
+  // workspace MCPs connected). Helper internally no-ops for non-Claude runtimes
+  // and when engine.claudePreApproveWorkspaceMcps is false (no runtime.name
+  // check at this call site, per CLAUDE.md rule). Best-effort: NEVER block dispatch.
+  //
+  // P-49e1c8b7 — Skipped entirely when resolvedHermetic is true: a hermetic
+  // dispatch wants a known-empty harness surface, so the workspace .mcp.json
+  // approval must not be written.
+  if (resolvedHermetic) {
+    log('debug', `Hermetic harness: skipping workspace MCP pre-approval for ${id}`);
+  } else {
+    try {
+      const result = preApproveWorkspaceMcps({
+        runtimeName,
+        worktreePath,
+        homeDir: os.homedir(),
+        engineConfig,
+        mutateJsonFileLocked: shared.mutateJsonFileLocked,
+      });
+      if (result.wrote) {
+        log('info', `Pre-approved ${result.servers.length} workspace MCP server(s) in ~/.claude.json for ${worktreePath}: ${result.servers.join(', ')}`);
+      } else if (result.reason !== 'no-workspace-mcp' && result.reason !== 'not-claude' && result.reason !== 'no-worktree') {
+        log('debug', `Skipped workspace MCP pre-approval for ${id} (reason=${result.reason})`);
+      }
+    } catch (err) {
+      log('warn', `Workspace MCP pre-approval failed for ${id} (non-fatal): ${err.message}`);
+    }
+  }
+
   _phaseT.afterRuntime = Date.now();
 
   log('info', `Spawning agent: ${agentId} (${id}) in ${cwd}`);
@@ -3202,7 +3328,70 @@ async function spawnAgent(dispatchItem, config) {
   // Spawn via wrapper script — node directly (no bash intermediary)
   // spawn-agent.js handles CLAUDECODE env cleanup and claude binary resolution
   const spawnScript = path.join(ENGINE_DIR, 'spawn-agent.js');
-  const spawnArgs = [spawnScript, promptPath, sysPromptPath, ...args];
+
+  // ── P-08b62d49 — project-local-on-main harness propagation ──────────────
+  // The worktree-uncommitted footgun (docs/harness-propagation.md): when a
+  // mutating dispatch runs in a fresh `git worktree add` (worktreePath !==
+  // project.localPath), uncommitted `<repo>/.claude/skills/foo/SKILL.md` etc.
+  // on the operator's main checkout are invisible to the runtime CLI because
+  // its native discovery is rooted at cwd. Union the project-scope harness
+  // dirs (skills + commands) that exist under `project.localPath` but NOT
+  // under `worktreePath`, and forward them to spawn-agent as
+  // `--project-harness-dir <dir>` so `computeAddDirs` surfaces them via
+  // `--add-dir`. Gated by engine.harnessPropagateProjectLocal (default true).
+  // No-op for live-checkout mode (worktreePath === null) and read-only types
+  // (also worktreePath === null per resolveSpawnPaths).
+  //
+  // P-49e1c8b7 — Also skipped entirely when resolvedHermetic is true: hermetic
+  // dispatches want a known-empty harness surface so neither user-asset dirs
+  // (filtered inside computeAddDirs) nor project-local-on-main dirs (filtered
+  // here) reach the agent. We skip the queries.getProjectHarnesses(...) call
+  // too — saves the fs scan when the result will be discarded.
+  //
+  // P-714ef144 — when meta.workdir is set, the filter helper clips both the
+  // project-side and worktree-side anchors to <base>/<workdir>, so a
+  // `packages/foo` dispatch never sees harness dirs from sibling packages.
+  // The clipping is purely additive on top of the existing project-vs-worktree
+  // disjoint filter; when workdir is null the helper produces the same result
+  // as the legacy inline loop.
+  const projectHarnessArgs = [];
+  if (!resolvedHermetic
+      && engineConfig.harnessPropagateProjectLocal !== false
+      && worktreePath
+      && project?.localPath
+      && path.resolve(worktreePath) !== path.resolve(project.localPath)) {
+    try {
+      const harnesses = queries.getProjectHarnesses(project);
+      const candidateDirs = [
+        ...(harnesses.skills || []),
+        ...(harnesses.commands || []),
+      ]
+        .map((entry) => entry?.dir)
+        .filter((d) => typeof d === 'string' && d);
+      const filteredDirs = shared.filterProjectHarnessDirsForWorkdir(candidateDirs, {
+        projectLocalPath: project.localPath,
+        worktreePath,
+        workdir: validatedWorkdir,
+      });
+      for (const abs of filteredDirs) {
+        if (!fs.existsSync(abs)) continue;
+        projectHarnessArgs.push('--project-harness-dir', abs);
+      }
+      if (projectHarnessArgs.length) {
+        log('debug', `Project-local harness propagation: ${projectHarnessArgs.length / 2} dir(s) for ${id} (${worktreePath}${validatedWorkdir ? ', workdir=' + validatedWorkdir : ''})`);
+      }
+    } catch (err) {
+      log('warn', `Project-local harness propagation failed for ${id} (non-fatal): ${err.message}`);
+    }
+  }
+
+  // P-49e1c8b7 — hermetic harness opt-out forwarded to spawn-agent.js so
+  // computeAddDirs returns [minionsDir] only (user-asset dirs stripped).
+  // Append BEFORE projectHarnessArgs (which will be empty when hermetic, but
+  // ordering keeps the intent explicit in process listings).
+  const hermeticArgs = resolvedHermetic ? ['--hermetic-harness'] : [];
+
+  const spawnArgs = [spawnScript, promptPath, sysPromptPath, ...args, ...hermeticArgs, ...projectHarnessArgs];
 
   // Live output file — stamped BEFORE child process is spawned (#W-mo248lkjwgsu).
   // Writing the stub pre-spawn lets the orphan detector distinguish three failure modes
@@ -3589,7 +3778,12 @@ async function spawnAgent(dispatchItem, config) {
       let resumeProc;
       try {
         // detached so the resumed steering session also survives engine death (matches initial spawn)
-        resumeProc = runFile(process.execPath, [spawnScript, steerPromptPath, sysPromptPath, ...resumeArgs], {
+        // P-08b62d49 — also include projectHarnessArgs so the resumed runtime
+        // can still reach uncommitted project-local harness dirs (the runtime
+        // CLI re-indexes asset dirs on every spawn, including this resume).
+        // P-49e1c8b7 — same for --hermetic-harness so the resumed dispatch
+        // keeps the known-empty harness contract.
+        resumeProc = runFile(process.execPath, [spawnScript, steerPromptPath, sysPromptPath, ...resumeArgs, ...hermeticArgs, ...projectHarnessArgs], {
           cwd,
           stdio: ['pipe', 'pipe', 'pipe'],
           env: childEnv,
@@ -9237,6 +9431,41 @@ async function tickInner() {
   // cache (single-object latest sample) — gitignored and exempt from the
   // SQL-first state rule, same as engine/dashboard-port.json.
   safe('memoryBaseline', () => emitMemoryBaseline(tickCount));
+
+  // 7. Operator-driven heap snapshot capture (P-e5f6a7b8).
+  // Dashboard's POST /api/diagnostics/heap-snapshot drops a sentinel in
+  // engine/diagnostics/heap-snapshot-request.json after capturing its own
+  // heap. We pick it up on the next tick, write the engine-side
+  // .heapsnapshot, then remove the sentinel so the dashboard handler can
+  // detect completion. The v8.writeHeapSnapshot call stalls THIS process
+  // for several seconds — the dashboard polls with a 30s timeout.
+  safe('heapSnapshotRequest', () => processHeapSnapshotRequest());
+}
+
+function processHeapSnapshotRequest() {
+  if (!fs.existsSync(HEAP_SNAPSHOT_REQUEST_PATH)) return;
+  let req = null;
+  try {
+    req = JSON.parse(fs.readFileSync(HEAP_SNAPSHOT_REQUEST_PATH, 'utf8'));
+  } catch (e) {
+    log('warn', `heap-snapshot-request parse failed: ${e.message}`);
+    try { safeUnlink(HEAP_SNAPSHOT_REQUEST_PATH); } catch { /* best effort */ }
+    return;
+  }
+  const iso = (req && typeof req.requestedAt === 'string') ? req.requestedAt : new Date().toISOString();
+  const safeIso = String(iso).replace(/[:.]/g, '-');
+  const outPath = path.join(DIAGNOSTICS_DIR, `heap-engine-${safeIso}.heapsnapshot`);
+  const v8 = require('v8');
+  try {
+    fs.mkdirSync(DIAGNOSTICS_DIR, { recursive: true });
+    log('info', `HEAP_SNAPSHOT engine capturing -> ${outPath} (this stalls the engine for several seconds)`);
+    v8.writeHeapSnapshot(outPath);
+    log('info', `HEAP_SNAPSHOT engine wrote ${outPath}`);
+  } catch (e) {
+    log('warn', `heap-snapshot writeHeapSnapshot failed: ${e.message}`);
+  } finally {
+    try { safeUnlink(HEAP_SNAPSHOT_REQUEST_PATH); } catch { /* best effort */ }
+  }
 }
 
 function emitMemoryBaseline(tickN) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2179",
+  "version": "0.1.2181",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"