@yemi33/minions 0.1.1774 → 0.1.1776

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.1.1776 (2026-05-07)
+
+### Fixes
+- refuse worktree paths nested in any project root
+
 ## 0.1.1774 (2026-05-07)
 
 ### Features

package/bin/minions.js

@@ -39,6 +39,7 @@ const os = require('os');
 const { spawn, spawnSync, execSync } = require('child_process');
 
 const PKG_ROOT = path.resolve(__dirname, '..');
+const shared = require(path.join(PKG_ROOT, 'engine', 'shared'));
 const DASH_PORT = 7331;
 const DASHBOARD_BROWSER_PRESENCE_MAX_AGE_MS = 45000;
 
@@ -152,8 +153,6 @@ function spawnDashboard(suppressOpen) {
   return proc;
 }
 
-const DEFAULT_MINIONS_HOME = path.join(os.homedir(), '.minions');
-const ROOT_POINTER_PATH = path.join(os.homedir(), '.minions-root');
 const LEGACY_DEFAULT_SQUAD_HOME = path.join(os.homedir(), '.squad');
 const LEGACY_ROOT_POINTER_PATH = path.join(os.homedir(), '.squad-root');
 
@@ -171,13 +170,6 @@ function isLegacyInstalledRoot(dir) {
     fs.existsSync(path.join(dir, 'squad.js'));
 }
 
-function readRootPointer() {
-  try {
-    const p = fs.readFileSync(ROOT_POINTER_PATH, 'utf8').trim();
-    return p ? path.resolve(p) : null;
-  } catch { return null; }
-}
-
 function readLegacyRootPointer() {
   try {
     const p = fs.readFileSync(LEGACY_ROOT_POINTER_PATH, 'utf8').trim();
@@ -186,7 +178,7 @@ function readLegacyRootPointer() {
 }
 
 function saveRootPointer(root) {
-  try { fs.writeFileSync(ROOT_POINTER_PATH, root); } catch {}
+  shared.saveMinionsRootPointer(root);
 }
 
 function findLegacySquadRoot() {
@@ -254,17 +246,7 @@ function migrateLegacyInstallIfNeeded(targetHome) {
 }
 
 function resolveMinionsHome(forInit = false) {
-  const envHome = process.env.MINIONS_HOME ? path.resolve(process.env.MINIONS_HOME) : null;
-  if (envHome) return envHome;
-
-  if (forInit) return DEFAULT_MINIONS_HOME;
-
-  const pointerRoot = readRootPointer();
-  if (isInstalledRoot(pointerRoot)) return pointerRoot;
-
-  if (isInstalledRoot(DEFAULT_MINIONS_HOME)) return DEFAULT_MINIONS_HOME;
-
-  return DEFAULT_MINIONS_HOME;
+  return shared.resolveMinionsHome(forInit);
 }
 
 const [cmd, ...rest] = process.argv.slice(2);

package/dashboard.js

@@ -1334,13 +1334,116 @@ const PREAMBLE_TTL = 30000; // 30s — longer TTL since preamble is lightweight
 // captures no-op via the truthy guard.
 let _ccApiRoutesMeta = null;
 
+function _routePathForMeta(route) {
+  if (!route) return '';
+  if (typeof route.path === 'string') return route.path;
+  return route.template || route.pathTemplate || String(route.path);
+}
+
+function _parseRouteParamHint(paramHint, method) {
+  if (!paramHint || typeof paramHint !== 'string') return [];
+  const paramLocation = ['GET', 'HEAD', 'DELETE'].includes(String(method || '').toUpperCase()) ? 'query' : 'body';
+  const parts = [];
+  let current = '';
+  let parenDepth = 0;
+  for (const ch of paramHint) {
+    if (ch === '(') parenDepth++;
+    if (ch === ')' && parenDepth > 0) parenDepth--;
+    if (ch === ',' && parenDepth === 0) {
+      parts.push(current);
+      current = '';
+      continue;
+    }
+    current += ch;
+  }
+  if (current) parts.push(current);
+  return parts
+    .map(part => {
+      const raw = part.trim();
+      if (!raw) return null;
+      let text = raw;
+      let description = '';
+      text = text.replace(/\(([^)]*)\)/g, (_, desc) => {
+        description = desc.trim();
+        return '';
+      }).trim();
+      const required = !text.includes('?');
+      const array = text.includes('[]');
+      const name = text
+        .replace(/\?/g, '')
+        .replace(/\[\]/g, '')
+        .trim()
+        .split(/\s+/)[0];
+      if (!name) return null;
+      return {
+        name,
+        in: paramLocation,
+        required,
+        ...(description ? { description } : {}),
+        ...(array ? { type: 'array' } : {}),
+      };
+    })
+    .filter(Boolean);
+}
+
+function _routePathParams(pathTemplate) {
+  if (!pathTemplate || typeof pathTemplate !== 'string') return [];
+  const params = [];
+  for (const match of pathTemplate.matchAll(/:([A-Za-z][A-Za-z0-9_]*)/g)) {
+    params.push({ name: match[1], in: 'path', required: true });
+  }
+  return params;
+}
+
+function _routeParametersForMeta(route, pathTemplate) {
+  const seen = new Set();
+  const params = [..._routePathParams(pathTemplate), ..._parseRouteParamHint(route.params, route.method)];
+  return params.filter(param => {
+    const key = `${param.in}:${param.name}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function _routeReadOnly(route) {
+  if (typeof route.readOnly === 'boolean') return route.readOnly;
+  return ['GET', 'HEAD', 'OPTIONS'].includes(String(route.method || '').toUpperCase());
+}
+
+function _routeDestructive(route, pathTemplate, readOnly) {
+  if (typeof route.destructive === 'boolean') return route.destructive;
+  if (readOnly) return false;
+  if (String(route.method || '').toUpperCase() === 'DELETE') return true;
+  const haystack = `${pathTemplate || ''} ${route.desc || ''}`.toLowerCase();
+  return /\b(delete|remove|cancel|kill|reset|restart|archive|unarchive|abort|purge|reject|pause|unlink|clear)\b/.test(haystack);
+}
+
+function _routeGenericFallback(route, pathTemplate) {
+  if (typeof route.genericFallback === 'boolean') return route.genericFallback;
+  if (!pathTemplate || !pathTemplate.startsWith('/api/')) return false;
+  if (String(route.method || '').toUpperCase() !== 'POST') return false;
+  const haystack = `${pathTemplate} ${route.desc || ''}`.toLowerCase();
+  if (haystack.includes('sse') || /\bstreaming\b/.test(haystack) || /\/stream(?:$|[/?#])/.test(pathTemplate)) return false;
+  return true;
+}
+
 function _routesAsMeta(routes) {
-  return routes.map(r => ({
-    method: r.method,
-    path: typeof r.path === 'string' ? r.path : String(r.path),
-    desc: r.desc || '',
-    params: r.params || null,
-  }));
+  return routes.map(r => {
+    const pathTemplate = _routePathForMeta(r);
+    const readOnly = _routeReadOnly(r);
+    const destructive = _routeDestructive(r, pathTemplate, readOnly);
+    return {
+      method: r.method,
+      path: pathTemplate,
+      desc: r.desc || '',
+      params: r.params || null,
+      parameters: _routeParametersForMeta(r, pathTemplate),
+      readOnly,
+      destructive,
+      genericFallback: _routeGenericFallback(r, pathTemplate),
+    };
+  });
 }
 
 function _captureApiRoutesMeta(routes) {
@@ -1354,7 +1457,13 @@ function _formatCcApiRoutesIndex() {
     .filter(r => r.path.startsWith('/api/'))
     .map(r => {
       const params = r.params ? ` — params: ${r.params}` : '';
-      return `- \`${r.method} ${r.path}\` — ${r.desc}${params}`;
+      const flags = [
+        r.readOnly ? 'read-only' : null,
+        r.destructive ? 'destructive' : null,
+        r.genericFallback ? 'generic-fallback' : null,
+      ].filter(Boolean);
+      const flagText = flags.length ? ` — flags: ${flags.join(', ')}` : '';
+      return `- \`${r.method} ${r.path}\` — ${r.desc}${params}${flagText}`;
     })
     .join('\n');
 }
@@ -1405,7 +1514,7 @@ ${apiIndex || '(routes not yet captured — first request still pending)'}
 ### CLI Index (auto-generated from engine/cli.js CLI_COMMAND_DOCS — single source of truth)
 ${cliIndex || '(unavailable)'}
 
-For any \`/api/...\` endpoint not covered by a named CC action, use the generic fallback:
+For \`POST /api/...\` endpoints marked \`generic-fallback\` and not covered by a named CC action, use the generic fallback:
 \`{"type":"<descriptive>","endpoint":"/api/...","params":{...}}\`.` : '';
 
   const result = `### Agents
@@ -7152,8 +7261,8 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     { method: 'POST', path: '/api/plans/unarchive', desc: 'Restore a plan/PRD from archive', params: 'file', handler: handlePlansUnarchive },
     { method: 'POST', path: '/api/plans/revise', desc: 'Request revision with feedback, dispatches agent to revise', params: 'file, feedback, requestedBy?', handler: handlePlansRevise },
     { method: 'POST', path: '/api/plans/discuss', desc: 'Generate a plan discussion session script for Claude CLI', params: 'file', handler: handlePlansDiscuss },
-    { method: 'GET', path: /^\/api\/plans\/archive\/([^?]+)$/, desc: 'Read an archived plan file', handler: handlePlansArchiveRead },
-    { method: 'GET', path: /^\/api\/plans\/([^?]+)$/, desc: 'Read a full plan (JSON from prd/ or markdown from plans/)', handler: handlePlansRead },
+    { method: 'GET', path: /^\/api\/plans\/archive\/([^?]+)$/, template: '/api/plans/archive/:file', desc: 'Read an archived plan file', handler: handlePlansArchiveRead },
+    { method: 'GET', path: /^\/api\/plans\/([^?]+)$/, template: '/api/plans/:file', desc: 'Read a full plan (JSON from prd/ or markdown from plans/)', handler: handlePlansRead },
 
     // PRD items
     { method: 'POST', path: '/api/prd-items', desc: 'Create a PRD item as a plan file in prd/ (auto-approved)', params: 'name, description?, priority?, estimated_complexity?, project?, id?', handler: handlePrdItemsCreate },
@@ -7325,13 +7434,13 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       });
     }},
     { method: 'POST', path: '/api/agents/cancel', desc: 'Cancel an active agent by ID or task substring', params: 'agent?, task?', handler: handleAgentsCancel },
-    { method: 'POST', path: /^\/api\/agent\/([\w-]+)\/kill$/, desc: 'Kill a running agent: stop process, clear dispatch, reset work items to pending', handler: handleAgentKill },
-    { method: 'GET', path: /^\/api\/agent\/([\w-]+)\/live-stream(?:\?.*)?$/, desc: 'SSE real-time live output streaming', handler: handleAgentLiveStream },
-    { method: 'GET', path: /^\/api\/agent\/([\w-]+)\/live(?:\?.*)?$/, desc: 'Tail live output for a working agent', params: 'tail? (bytes, default 8192)', handler: handleAgentLive },
-    { method: 'GET', path: /^\/api\/agent\/([\w-]+)\/live-output(?:\?.*)?$/, desc: 'Tail live output for a working agent (alias for /live)', params: 'tail? (bytes, default 8192)', handler: handleAgentLive },
-    { method: 'GET', path: /^\/api\/agent\/([\w-]+)\/output(?:\?.*)?$/, desc: 'Fetch final output.log for an agent', handler: handleAgentOutput },
-    { method: 'GET', path: /^\/api\/agent\/([\w-]+)$/, desc: 'Get detailed agent info', handler: handleAgentDetail },
-    { method: 'GET', path: /^\/api\/dispatch\/([\w.-]+)\/completion-report$/, desc: 'Read structured completion report for a dispatch', handler: (req, res, match) => {
+    { method: 'POST', path: /^\/api\/agent\/([\w-]+)\/kill$/, template: '/api/agent/:id/kill', desc: 'Kill a running agent: stop process, clear dispatch, reset work items to pending', handler: handleAgentKill },
+    { method: 'GET', path: /^\/api\/agent\/([\w-]+)\/live-stream(?:\?.*)?$/, template: '/api/agent/:id/live-stream', desc: 'SSE real-time live output streaming', handler: handleAgentLiveStream },
+    { method: 'GET', path: /^\/api\/agent\/([\w-]+)\/live(?:\?.*)?$/, template: '/api/agent/:id/live', desc: 'Tail live output for a working agent', params: 'tail? (bytes, default 8192)', handler: handleAgentLive },
+    { method: 'GET', path: /^\/api\/agent\/([\w-]+)\/live-output(?:\?.*)?$/, template: '/api/agent/:id/live-output', desc: 'Tail live output for a working agent (alias for /live)', params: 'tail? (bytes, default 8192)', handler: handleAgentLive },
+    { method: 'GET', path: /^\/api\/agent\/([\w-]+)\/output(?:\?.*)?$/, template: '/api/agent/:id/output', desc: 'Fetch final output.log for an agent', handler: handleAgentOutput },
+    { method: 'GET', path: /^\/api\/agent\/([\w-]+)$/, template: '/api/agent/:id', desc: 'Get detailed agent info', handler: handleAgentDetail },
+    { method: 'GET', path: /^\/api\/dispatch\/([\w.-]+)\/completion-report$/, template: '/api/dispatch/:id/completion-report', desc: 'Read structured completion report for a dispatch', handler: (req, res, match) => {
       const id = match && match[1];
       const payload = queries.getDispatchCompletionReport(id);
       if (!payload) return jsonReply(res, 404, { error: 'completion report not found' }, req);
@@ -7367,7 +7476,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     }},
     { method: 'POST', path: '/api/knowledge/sweep', desc: 'Trigger async KB sweep (returns 202)', handler: handleKnowledgeSweep },
     { method: 'GET', path: '/api/knowledge/sweep/status', desc: 'Poll KB sweep status', handler: handleKnowledgeSweepStatus },
-    { method: 'GET', path: /^\/api\/knowledge\/([^/]+)\/([^?]+)/, desc: 'Read a specific knowledge base entry', handler: handleKnowledgeRead },
+    { method: 'GET', path: /^\/api\/knowledge\/([^/]+)\/([^?]+)/, template: '/api/knowledge/:category/:file', desc: 'Read a specific knowledge base entry', handler: handleKnowledgeRead },
 
     // Doc chat
     { method: 'POST', path: '/api/doc-chat', desc: 'Minions-aware doc Q&A + editing via CC session', params: 'message, document, title?, filePath?, selection?, contentHash?', handler: handleDocChat },
@@ -7398,7 +7507,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     { method: 'POST', path: '/api/command-center', desc: 'Conversational command center with full minions context', params: 'message, sessionId?', handler: handleCommandCenter },
     { method: 'POST', path: '/api/command-center/stream', desc: 'Streaming CC — SSE with text chunks as they arrive', params: 'message, tabId?', handler: handleCommandCenterStream },
     { method: 'GET', path: '/api/cc-sessions', desc: 'List CC session metadata for all tabs', handler: handleCCSessionsList },
-    { method: 'DELETE', path: /^\/api\/cc-sessions\/([\w-]+)$/, desc: 'Delete a CC session by tab ID', handler: handleCCSessionDelete },
+    { method: 'DELETE', path: /^\/api\/cc-sessions\/([\w-]+)$/, template: '/api/cc-sessions/:id', desc: 'Delete a CC session by tab ID', handler: handleCCSessionDelete },
 
     // Schedules
     { method: 'POST', path: '/api/schedules/parse-natural', desc: 'Parse natural language schedule text into cron expression', params: 'text', handler: handleSchedulesParseNatural },
@@ -7544,7 +7653,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       return jsonReply(res, 200, { meetings: getMeetings() });
     }},
 
-    { method: 'GET', path: /^\/api\/meetings\/(MTG-[\w]+)$/, desc: 'Get meeting detail', handler: async (req, res, match) => {
+    { method: 'GET', path: /^\/api\/meetings\/(MTG-[\w]+)$/, template: '/api/meetings/:id', desc: 'Get meeting detail', handler: async (req, res, match) => {
       const { getMeeting } = require('./engine/meeting');
       const meeting = getMeeting(match[1]);
       if (!meeting) return jsonReply(res, 404, { error: 'Meeting not found' });
@@ -7619,7 +7728,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       const md = require('./engine/model-discovery');
       return jsonReply(res, 200, { runtimes: md.listAllRuntimes() }, req);
     }},
-    { method: 'POST', path: /^\/api\/runtimes\/([\w-]+)\/models\/refresh$/, desc: 'Invalidate the models cache for a runtime and re-fetch', handler: async (req, res, match) => {
+    { method: 'POST', path: /^\/api\/runtimes\/([\w-]+)\/models\/refresh$/, template: '/api/runtimes/:runtime/models/refresh', desc: 'Invalidate the models cache for a runtime and re-fetch', handler: async (req, res, match) => {
       const md = require('./engine/model-discovery');
       const name = match[1];
       try {
@@ -7638,7 +7747,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       }
       return jsonReply(res, 200, payload, req);
     }},
-    { method: 'GET', path: /^\/api\/runtimes\/([\w-]+)\/models$/, desc: 'Get cached or fresh model list for a runtime', handler: async (req, res, match) => {
+    { method: 'GET', path: /^\/api\/runtimes\/([\w-]+)\/models$/, template: '/api/runtimes/:runtime/models', desc: 'Get cached or fresh model list for a runtime', handler: async (req, res, match) => {
       const md = require('./engine/model-discovery');
       const name = match[1];
       let payload;
@@ -7798,6 +7907,7 @@ module.exports = {
   _createPipelineFromAction: createPipelineFromAction,
   executeCCActions,
   buildCCStatePreamble,
+  _routesAsMeta,
   _buildTranscriptCarryover,
   _ccRuntimeNeedsResumeCarryover,
   _joinCcPromptParts,

package/engine/cleanup.js

@@ -366,6 +366,31 @@ async function runCleanup(config, verbose = false) {
     }
   }
 
+  // 2b. Detect git worktrees registered inside any linked project's working tree.
+  // Nested worktrees cause glob/grep tools running with cwd=projectRoot to match
+  // BOTH copies of every file; a single Edit/MultiEdit then writes the same
+  // change to both locations, producing "mirror dirty file" leaks (W-cc-doc-chat-continuity).
+  // We only WARN here — removing someone else's worktree without consent could
+  // destroy in-flight work. The operator runs `git worktree remove <path>`.
+  cleaned.nestedWorktrees = 0;
+  for (const project of projects) {
+    const root = project.localPath ? path.resolve(project.localPath) : null;
+    if (!root || !fs.existsSync(root)) continue;
+    let raw;
+    try {
+      raw = String(shared.execSilent('git worktree list --porcelain', { cwd: root, timeout: 10000, windowsHide: true }) || '');
+    } catch (e) { log('warn', `nested-worktree scan for ${project.name || root}: ${e.message}`); continue; }
+    for (const line of raw.split('\n')) {
+      if (!line.startsWith('worktree ')) continue;
+      const wt = line.slice('worktree '.length).trim();
+      if (!wt) continue;
+      if (path.resolve(wt) === root) continue; // main worktree — expected
+      if (!shared.isPathInsideOrEqual(wt, root)) continue;
+      cleaned.nestedWorktrees++;
+      log('warn', `Nested worktree in project "${project.name || root}": "${wt}" is inside "${root}". This causes glob tools to match both copies and produces mirror writes. Run: git worktree remove "${wt}"`);
+    }
+  }
+
   // 3. Clean git worktrees for merged/abandoned PRs
   const _attemptedWorktreePaths = new Set(); // dedup across projects sharing a worktreeRoot
   for (const project of projects) {
@@ -664,8 +689,8 @@ async function runCleanup(config, verbose = false) {
     }
   } catch (e) { log('warn', 'prune orphaned dispatches: ' + e.message); }
 
-  if (cleaned.tempFiles + cleaned.liveOutputs + cleaned.worktrees + cleaned.zombies + (cleaned.files || 0) + cleaned.orphanedDispatches > 0) {
-    log('info', `Cleanup: ${cleaned.tempFiles} temp, ${cleaned.liveOutputs} live outputs, ${cleaned.worktrees} worktrees, ${cleaned.zombies} zombies, ${cleaned.files || 0} archives, ${cleaned.orphanedDispatches} orphaned dispatches`);
+  if (cleaned.tempFiles + cleaned.liveOutputs + cleaned.worktrees + cleaned.zombies + (cleaned.files || 0) + cleaned.orphanedDispatches + (cleaned.nestedWorktrees || 0) > 0) {
+    log('info', `Cleanup: ${cleaned.tempFiles} temp, ${cleaned.liveOutputs} live outputs, ${cleaned.worktrees} worktrees, ${cleaned.zombies} zombies, ${cleaned.files || 0} archives, ${cleaned.orphanedDispatches} orphaned dispatches, ${cleaned.nestedWorktrees || 0} nested worktrees flagged`);
   }
 
   // 8. Clean swept KB files older than 7 days

package/engine/copilot-models.json

@@ -1,5 +1,5 @@
 {
   "runtime": "copilot",
   "models": null,
-  "cachedAt": "2026-05-07T21:34:32.453Z"
+  "cachedAt": "2026-05-07T23:06:07.639Z"
 }

package/engine/shared.js

@@ -5,9 +5,58 @@
 
 const fs = require('fs');
 const path = require('path');
+const os = require('os');
 const crypto = require('crypto');
 
-const MINIONS_DIR = process.env.MINIONS_TEST_DIR || (process.env.MINIONS_HOME ? path.resolve(process.env.MINIONS_HOME) : path.resolve(__dirname, '..'));
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+const DEFAULT_MINIONS_HOME = path.join(os.homedir(), '.minions');
+const ROOT_POINTER_PATH = path.join(os.homedir(), '.minions-root');
+
+function isInstalledRoot(dir) {
+  if (!dir) return false;
+  return fs.existsSync(path.join(dir, 'engine.js')) &&
+    fs.existsSync(path.join(dir, 'dashboard.js')) &&
+    fs.existsSync(path.join(dir, 'minions.js'));
+}
+
+function isSourceCheckoutRoot(dir) {
+  return !!dir && fs.existsSync(path.join(dir, '.git'));
+}
+
+function readMinionsRootPointer() {
+  try {
+    const p = fs.readFileSync(ROOT_POINTER_PATH, 'utf8').trim();
+    return p ? path.resolve(p) : null;
+  } catch { return null; }
+}
+
+function saveMinionsRootPointer(root) {
+  try { fs.writeFileSync(ROOT_POINTER_PATH, path.resolve(root)); } catch {}
+}
+
+function resolveMinionsHome(forInit = false, options = {}) {
+  const envHome = process.env.MINIONS_HOME ? path.resolve(process.env.MINIONS_HOME) : null;
+  if (envHome) return envHome;
+
+  if (forInit) return DEFAULT_MINIONS_HOME;
+
+  const packageRoot = options.packageRoot ? path.resolve(options.packageRoot) : PACKAGE_ROOT;
+  if (options.preferSourceCheckout && isSourceCheckoutRoot(packageRoot)) return packageRoot;
+
+  const pointerRoot = readMinionsRootPointer();
+  if (isInstalledRoot(pointerRoot)) return pointerRoot;
+
+  if (isInstalledRoot(DEFAULT_MINIONS_HOME)) return DEFAULT_MINIONS_HOME;
+
+  if (options.allowPackageRootFallback && isInstalledRoot(packageRoot)) return packageRoot;
+
+  return DEFAULT_MINIONS_HOME;
+}
+
+const MINIONS_DIR = process.env.MINIONS_TEST_DIR || resolveMinionsHome(false, {
+  allowPackageRootFallback: true,
+  preferSourceCheckout: true,
+});
 const ENGINE_DIR = path.join(MINIONS_DIR, 'engine');
 const CONTROL_PATH = path.join(ENGINE_DIR, 'control.json');
 const COOLDOWNS_PATH = path.join(ENGINE_DIR, 'cooldowns.json');
@@ -2072,6 +2121,49 @@ function buildWorktreeDirName({
   return `${projectSlug}-${sanitizeBranch(branchName || 'worktree')}-${suffix}`;
 }
 
+/**
+ * True when `childPath` is the same as or nested within `parentPath`. Uses
+ * `path.relative` so it's cross-platform and resilient to mixed separators
+ * (Windows worktree paths often arrive with forward slashes from git output).
+ * Returns false when paths refer to different roots/drives or `childPath`
+ * escapes via `..`.
+ *
+ * Why this helper exists: a git worktree placed inside the parent repo's
+ * working tree causes glob/grep tools running with `cwd = projectRoot` to
+ * match BOTH copies of every file. A single Edit/MultiEdit then writes the
+ * same change to both locations, producing the "mirror dirty file" pattern.
+ * Worktrees must always be siblings/cousins of the project root, never
+ * descendants.
+ */
+function isPathInsideOrEqual(childPath, parentPath) {
+  if (!childPath || !parentPath) return false;
+  const childAbs = path.resolve(String(childPath));
+  const parentAbs = path.resolve(String(parentPath));
+  const rel = path.relative(parentAbs, childAbs);
+  if (rel === '') return true;
+  if (rel.startsWith('..')) return false;
+  if (path.isAbsolute(rel)) return false;
+  return true;
+}
+
+/**
+ * Throws when `worktreePath` would land inside (or equal) `projectRoot`.
+ * Called by the engine spawn path before `git worktree add`, and by the
+ * cleanup sweep that audits already-registered worktrees per linked project.
+ * The thrown Error has `code: 'WORKTREE_NESTED_IN_PROJECT'` so callers can
+ * branch on it without parsing the message.
+ */
+function assertWorktreeOutsideProject(worktreePath, projectRoot) {
+  if (!isPathInsideOrEqual(worktreePath, projectRoot)) return;
+  const err = new Error(
+    `Refusing to use worktree path "${worktreePath}" — it is inside project root "${projectRoot}". ` +
+    `A worktree nested in its parent project causes glob/grep tools to match both copies and ` +
+    `produces "mirror" dirty files. Place worktrees outside the project (engine.worktreeRoot default: "../worktrees").`
+  );
+  err.code = 'WORKTREE_NESTED_IN_PROJECT';
+  throw err;
+}
+
 // ── HTTP Origin Allowlist & Security Headers ─────────────────────────────────
 // Pure helpers used by dashboard.js to gate mutating requests against an
 // explicit allowlist of local origins and to attach uniform security response
@@ -3055,6 +3147,8 @@ module.exports = {
   safeJson, safeJsonObj, safeJsonArr, safeJsonNoRestore,
   safeWrite,
   safeUnlink,
+  resolveMinionsHome,
+  saveMinionsRootPointer,
   neutralizeJsonBackupSidecar,
   PROMPT_CONTEXTS_DIR,
   dispatchPromptSidecarPath,
@@ -3141,6 +3235,8 @@ module.exports = {
   sanitizePath,
   sanitizeBranch,
   buildWorktreeDirName, // exported for testing
+  isPathInsideOrEqual,
+  assertWorktreeOutsideProject,
   isLiveCommandCenterPath,
   describeCcProtectedPaths,
   renderCcSystemPrompt,

package/engine.js

@@ -625,10 +625,18 @@ async function spawnAgent(dispatchItem, config) {
       branchName,
     });
     worktreePath = path.resolve(rootDir, engineConfig.worktreeRoot || '../worktrees', wtDirName);
+    // Refuse to spawn into a worktree path that's inside the project root —
+    // nested worktrees cause glob/grep to match both copies (mirror writes).
+    // Throws on violation; caught by the outer try/catch which fails dispatch.
+    shared.assertWorktreeOutsideProject(worktreePath, rootDir);
 
     // If branch is already checked out in an existing worktree, reuse it
     const existingWt = await findExistingWorktree(rootDir, branchName);
     if (existingWt) {
+      // Same guard for reuse — a previously-created bad worktree must not
+      // be silently reused either; the cleanup sweep flags these so the
+      // operator can remove them.
+      shared.assertWorktreeOutsideProject(existingWt, rootDir);
       worktreePath = existingWt;
       log('info', `Reusing existing worktree for ${branchName}: ${existingWt}`);
       // Probe origin first — locally-created branches that were never pushed
@@ -3543,6 +3551,7 @@ function discoverCentralWorkItems(config) {
   const items = safeJson(centralPath) || [];
   const projects = getProjects(config);
   const dispatchProjects = getCentralDispatchProjects(projects);
+  const projectsByName = new Map(dispatchProjects.map(p => [p.name, p]));
   const newWork = [];
   // Collect mutations to apply atomically inside lock callback (avoids TOCTOU)
   const mutations = new Map(); // item.id → { field: value, ... }
@@ -3673,6 +3682,8 @@ function discoverCentralWorkItems(config) {
       const agentName = config.agents[agentId]?.name || agentId;
       const agentRole = config.agents[agentId]?.role || 'Agent';
       const firstProject = dispatchProjects[0];
+      const requestedProjectName = typeof item.project === 'string' ? item.project : item.project?.name;
+      const targetProject = (requestedProjectName && projectsByName.get(requestedProjectName)) || firstProject;
 
       // Branch mutex: skip if target branch is locked by an active dispatch
       const centralBranch = item.branch || item.featureBranch || `work/${item.id}`;
@@ -3683,7 +3694,7 @@ function discoverCentralWorkItems(config) {
       }
 
       const vars = {
-        ...buildBaseVars(agentId, config, firstProject),
+        ...buildBaseVars(agentId, config, targetProject),
         item_id: item.id,
         item_name: item.title || item.id,
         item_priority: item.priority || 'medium',
@@ -3694,11 +3705,11 @@ function discoverCentralWorkItems(config) {
         work_type: workType,
         additional_context: item.prompt ? `## Additional Context\n\n${item.prompt}` : '',
         scope_section: buildProjectContext(dispatchProjects, null, false, agentName, agentRole),
-        project_path: firstProject?.localPath || '',
+        project_path: targetProject?.localPath || '',
         branch_name: centralBranch,
       };
-      const centralWtPath = firstProject?.localPath
-        ? path.resolve(firstProject.localPath, config.engine?.worktreeRoot || '../worktrees', centralBranch)
+      const centralWtPath = targetProject?.localPath
+        ? path.resolve(targetProject.localPath, config.engine?.worktreeRoot || '../worktrees', centralBranch)
         : '';
       const cpResult = buildWorkItemDispatchVars(item, vars, config, {
         worktreePath: centralWtPath || undefined,
@@ -3749,7 +3760,7 @@ function discoverCentralWorkItems(config) {
         }
         vars.plan_summary = (item.title || item.planFile).substring(0, 80);
         vars.plan_file = item.planFile || '';
-        vars.project_name_lower = (firstProject?.name || 'project').toLowerCase();
+        vars.project_name_lower = (targetProject?.name || 'project').toLowerCase();
         // Default empty string so the {{existing_prd_json}} token always resolves —
         // playbook treats empty as "no existing PRD, fresh run". Without this default
         // the renderPlaybook pass logs an "unresolved template variables" warning
@@ -3804,7 +3815,7 @@ function discoverCentralWorkItems(config) {
         agentRole,
         task: item.title || item.description?.slice(0, 80) || item.id,
         prompt,
-        meta: { dispatchKey: key, source: 'central-work-item', item: { ...item, ...mutations.get(item.id) }, planFileName: item.planFile || mutations.get(item.id)?._planFileName || null, branch: item.branch || item.featureBranch || `work/${item.id}`, project: { name: firstProject.name, localPath: firstProject.localPath } }
+        meta: { dispatchKey: key, source: 'central-work-item', item: { ...item, ...mutations.get(item.id) }, planFileName: item.planFile || mutations.get(item.id)?._planFileName || null, branch: item.branch || item.featureBranch || `work/${item.id}`, project: { name: targetProject.name, localPath: targetProject.localPath } }
       });
 
       setCooldown(key);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.1774",
+  "version": "0.1.1776",
   "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"

package/prompts/cc-system.md

@@ -159,8 +159,8 @@ Terms like schedules, pipelines, agents, inbox, work items, plans, PRD, PRs, dis
 ## API & CLI Index (auto-injected)
 Your state preamble (delivered alongside this prompt at session start) carries an auto-generated **API Index** rendered from `dashboard.js` `ROUTES` and a **CLI Index** rendered from `engine/cli.js` `CLI_COMMAND_DOCS`. Both are single-source-of-truth — adding a new HTTP endpoint or CLI command auto-surfaces it in your preamble; do not memorize the named action shorthand list above as exhaustive.
 
-For any `/api/...` endpoint that doesn't have a matching named action above, emit the generic fallback shape:
+For a `POST /api/...` endpoint marked `generic-fallback` in the API Index that doesn't have a matching named action above, emit the generic fallback shape:
 `{"type":"<short-descriptor>","endpoint":"/api/...","params":{...}}`
-The action runner accepts any local `/api/` path and POSTs `params` as JSON.
+The action runner POSTs `params` as JSON; do not use the fallback for read-only GET routes, DELETE routes, or endpoints not marked generic-fallback.
 
 For CLI commands (`minions <cmd>`), use Bash to invoke them when delegating would be heavier than just running the command.