@yemi33/minions 0.1.2179 → 0.1.2180

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.2180",
   "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"