@yemi33/minions 0.1.1981 → 0.1.1983

package/dashboard/js/render-managed.js

@@ -13,6 +13,12 @@
 // about why the agent live tab moved off SSE).
 
 let _managedProcessesEtag = null;
+// Cache the last successfully-fetched items so 304 (no-op) ticks can still
+// re-render the time-derived columns (uptime, TTL) against the current
+// Date.now(). The server payload only changes on spawn/kill/restart, so
+// without this cache the strings would freeze between events
+// (W-mpbt3wfs002l3a09).
+let _managedProcessesLastItems = null;
 let _managedLogES = null;
 
 function _fmtAgo(ms) {
@@ -84,23 +90,27 @@ async function renderManagedProcesses() {
   if (!root) return;
   let items;
   let fetchErr = null;
-  let notModified = false;
   try {
     const headers = {};
     if (_managedProcessesEtag) headers['If-None-Match'] = _managedProcessesEtag;
     const res = await fetch('/api/managed-processes', { headers });
     if (res.status === 304) {
-      notModified = true;
+      // Server payload unchanged — reuse cached items so uptime/TTL columns
+      // recompute against the current Date.now(). Defensive null check: a
+      // first-tick 304 shouldn't happen (no prior ETag => no If-None-Match)
+      // but if it does, skip this frame rather than wiping the panel.
+      if (!_managedProcessesLastItems) return;
+      items = _managedProcessesLastItems;
     } else {
       const et = res.headers.get('ETag');
       if (et) _managedProcessesEtag = et;
       const data = await res.json();
       items = (data && Array.isArray(data.items)) ? data.items : [];
+      _managedProcessesLastItems = items;
     }
   } catch (e) {
     fetchErr = e;
   }
-  if (notModified) return; // nothing changed since last render
   let html;
   if (fetchErr) {
     if (countEl) countEl.textContent = '?';

package/docs/managed-spawn.md

@@ -35,7 +35,7 @@ The sidecar lives at `<MINIONS_DIR>/agents/<agentId>/managed-spawn.json` and is
       "name": "constellation-host",          // kebab-case, ≤64 chars, unique within file
       "cmd": "bun",                          // must be on engine.managedSpawn.executableAllowlist
       "args": ["run", "dev"],                // ≤64 entries
-      "cwd": "D:/repos/constellation",       // must be a real git worktree (requireGitWorkdir: true)
+      "cwd": "D:/repos/constellation",       // must be inside a real git worktree (requireGitWorkdir: true) — monorepo subdirs ok, ancestor walked up to gitWorktreeMaxParentDepth parents
       "env": { "CONSTELLATION_SERVER": "http://localhost:3000" },  // ≤32 keys; POSIX-shape + denylist enforced
       "ports": [3001],                       // 1024-65535; ≤20 per spec; advisory only (engine doesn't bind)
       "ttl_minutes": 240,                    // ≤1440 (24h hard cap); defaults to 240 (4h)
@@ -217,7 +217,8 @@ All knobs live under `engine.managedSpawn` in `engine/shared.js:1500` (`ENGINE_D
 | `logRotateBytes` | `10485760` | Rotation threshold for `<name>.log`. |
 | `bootReconcileMaxMs` | `2000` | Boot-time reconcile hard timeout. |
 | `promptContextMaxBytes` | `2048` | Auto-injected `## Live managed processes` block cap. |
-| `requireGitWorkdir` | `true` | Reject specs whose `cwd` isn't a git worktree. |
+| `requireGitWorkdir` | `true` | Reject specs whose `cwd` isn't inside a git worktree (root or any ancestor up to `gitWorktreeMaxParentDepth`). |
+| `gitWorktreeMaxParentDepth` | `6` | How many parent directories `shared.isValidGitWorktree` walks when probing for `.git`. Lets monorepo specs pin a per-package `cwd` (`<root>/packages/<pkg>/...`); set to `0` to disable the walk. |
 | `executableAllowlist` | `[node, bun, npm, …]` | Single global. Applies to `spec.cmd` AND `command` healthcheck `cmd`. |
 | `envKeyDenyPatterns` | `[^AWS_, ^AZURE_, _SECRET, _TOKEN, _API_KEY, …]` | Regex source strings, matched case-insensitively. Keys matching ANY pattern are rejected unless exact-listed in `envKeyDenyOverrides`. Threat model: credential leakage, not env-key enumeration — plain project vars (`CONSTELLATION_SERVER`, `DATABASE_URL`, …) pass with no config. |
 | `envKeyDenyOverrides` | `[AWS_REGION, AWS_DEFAULT_REGION, AZURE_REGION, GCP_REGION, AWS_PROFILE]` | Exact-match exemptions for known-safe keys that would otherwise be caught by a broad prefix pattern. Case-sensitive. |

package/engine/cli.js

@@ -818,6 +818,38 @@ const commands = {
       }
     })();
 
+    // W-mpbqhstz001lf518 — Boot reconcile for orphan worktrees (closes #2627).
+    // Walks each project's `<root>/<worktreeRoot>/` dir and removes any
+    // `W-*` (or posix `<proj>-<branch>-<hash>`) subdir whose dispatch id
+    // is NOT in dispatch.active/pending AND that is NOT a pool member.
+    // Such dirs are left over from a prior crash and block retries with
+    // `fatal: 'work/W-<id>' is already used by worktree at …`. Runs AFTER
+    // worktreePool.pruneStale so the pool snapshot we cross-reference is
+    // already settled (otherwise we could evict a dir whose pool entry was
+    // about to be pruned but still appeared as a pool member).
+    (function startupReconcileOrphanWorktrees() {
+      try {
+        const sharedMod = require('./shared');
+        const worktreeGc = require('./worktree-gc');
+        const dispatchSnap = require('./queries').getDispatch();
+        const cfg = require('./queries').getConfig();
+        const projects = sharedMod.getProjects(cfg);
+        if (projects.length === 0) return;
+        const worktreeRootRel = cfg?.engine?.worktreeRoot || sharedMod.ENGINE_DEFAULTS.worktreeRoot;
+        const result = worktreeGc.pruneOrphanWorktrees({
+          projects,
+          dispatchSnap,
+          worktreeRootRel,
+          log: (lvl, msg) => e.log(lvl, msg),
+        });
+        if (result.evicted > 0 || result.failed > 0) {
+          console.log(`  Worktree boot reconcile: evicted ${result.evicted} orphan worktree(s)${result.failed ? `, ${result.failed} failed` : ''} (scanned ${result.scanned}, kept ${result.kept})`);
+        }
+      } catch (err) {
+        e.log('warn', `Worktree boot reconcile failed: ${err.message}`);
+      }
+    })();
+
     // W-mp7gox8w000n8936 — Boot reconcile for kb-sweep state: clear stale
     // `in-flight`/`starting` records left over from a crashed runner (or a
     // legacy pre-pid runner). Without this, the record sits there clogging

package/engine/managed-spawn.js

@@ -286,9 +286,20 @@ function _validateSpec(spec, index, limits, opts) {
     return { ok: false, reason: 'cwd-too-long' };
   }
   if (_resolveRequireGitWorkdir(opts) && typeof spec.cwd === 'string' && spec.cwd.length > 0) {
-    const wt = shared.isValidGitWorktree(spec.cwd);
+    const wt = shared.isValidGitWorktree(spec.cwd, { memo: opts._gitWorktreeMemo });
     if (!wt.ok) {
-      return { ok: false, reason: INVALID_WORKDIR_REASON_PREFIX + wt.reason };
+      // W-mpbpa01y000qcdc2 — enrich the reject reason so the dispatcher prompt
+      // can distinguish a stale `cwd` (typoed / belonged to a torn-down
+      // worktree) from a real subdir whose `.git` lives at an ancestor. The
+      // legacy substring `invalid-workdir:` is preserved so the engine close-
+      // handler gate still matches.
+      const detail = [
+        wt.reason,
+        'cwd-exists:' + (wt.exists ? 'true' : 'false'),
+        'nearest-ancestor:' + (wt.nearestGitAncestor || 'null'),
+        'worktree-root:' + (wt.worktreeRoot || 'null'),
+      ].join(' | ');
+      return { ok: false, reason: INVALID_WORKDIR_REASON_PREFIX + detail };
     }
   }
 
@@ -420,10 +431,14 @@ function validateManagedSpawnRecord(parsed, opts) {
     try { projects = shared.getProjects(); }
     catch (_e) { projects = []; }
   }
-  const specOpts = Object.assign({}, opts, { projects: projects });
+  const specOpts = Object.assign({}, opts, { projects: projects, _gitWorktreeMemo: new Map() });
 
   const seen = new Set();
   const out = [];
+  // W-mpbpa01y000qcdc2 — share a memo across all specs in this file so
+  // adjacent `cwd`s under the same worktree root don't re-stat the same
+  // ancestors. Threaded through `opts._gitWorktreeMemo` into `_validateSpec`,
+  // then into `shared.isValidGitWorktree`.
   for (let i = 0; i < parsed.specs.length; i++) {
     const v = _validateSpec(parsed.specs[i], i, limits, specOpts);
     if (!v.ok) {
@@ -645,6 +660,22 @@ function buildManagedSpawnHint(opts) {
     '',
     'A passing smoke-test is the entry gate to writing the sidecar — not a nice-to-have. If you skip it, you are betting the WI completion against a command you never ran.',
     '',
+    '### Monorepo `cwd` tip (W-mpbpa01y000qcdc2)',
+    '',
+    '**Only worktree ROOTS have a `.git` entry.** In a multi-package repo (yarn workspaces, pnpm, bun workspaces, lerna, lage, turborepo), `packages/<pkg>/` does NOT contain its own `.git` — the engine\'s workdir validator walks up to ' + (limits.gitWorktreeMaxParentDepth || 6) + ' parent directories looking for one, so a per-package `cwd` IS accepted, but the **canonical recipe** is to keep `cwd` at the worktree root and target the package via the runtime\'s workspace flag:',
+    '',
+    '```jsonc',
+    '{',
+    '  "name": "constellation-host",',
+    '  "cmd": "bun",',
+    '  "args": ["-F", "@scope/server", "run", "dev"],   // bun workspace filter',
+    '  "cwd": "<worktree-root>",                         // NOT <worktree-root>/packages/server',
+    '  "healthcheck": { "type": "http", "url": "http://localhost:3001/health", "expect_status": 200, "interval_s": 1, "timeout_s": 60 }',
+    '}',
+    '```',
+    '',
+    'Equivalent flags for other runtimes: `pnpm --filter <pkg>`, `yarn workspace <pkg>`, `npm run -w <pkg>`, `lage run <task> --to <pkg>`. Keeping `cwd` at the root makes the spec portable across machines (no hard-coded package path) and avoids per-package `node_modules` resolution surprises.',
+    '',
     '### Verify before exit',
     '',
     'After you write the file, query the engine to confirm acceptance:',

package/engine/shared.js

@@ -1089,11 +1089,20 @@ function validateGhSlug(slug) {
   return slug;
 }
 
-// W-mp6k7ywi000fa33c — pure helper. Returns { ok: boolean, reason?: string }.
-// `ok: true` when `dirPath` exists AND contains either a `.git` directory OR
-// a `.git` worktree pointer file (a real file whose first line starts with
-// `gitdir:`). Anything else — missing dir, missing `.git`, `.git` as a
-// random non-pointer file — returns `ok: false` with a human-readable reason.
+// W-mp6k7ywi000fa33c — pure helper. Returns:
+//   { ok: boolean,
+//     reason?: string,
+//     exists: boolean,           // whether dirPath itself exists on disk
+//     nearestGitAncestor: string|null,  // path to nearest ancestor .git found
+//     worktreeRoot: string|null, // dir that owns the nearest .git
+//     depth: number              // 0 = dirPath itself; >0 = parents walked; -1 = not found
+//   }
+// `ok: true` when `dirPath` (or one of its ancestors up to a configurable
+// depth) contains either a `.git` directory OR a `.git` worktree pointer
+// file (a real file whose first line starts with `gitdir:`). The ancestor
+// walk lets monorepo agents pin a per-package `cwd` (e.g.
+// `<worktree-root>/packages/server`) — only the worktree root carries `.git`
+// but the package subdir is still inside a real worktree (W-mpbpa01y000qcdc2).
 //
 // No shelling out (no `git rev-parse`); just `fs.existsSync`/`fs.statSync`
 // and a tiny content sniff for the worktree pointer case. This catches the
@@ -1101,32 +1110,108 @@ function validateGhSlug(slug) {
 // `cp -r`) instead of `git worktree add`, which produced a directory that
 // looks file-by-file like a worktree but has no git linkage. See
 // W-mp6ha6q9000d58a5 for the real-world incident this prevents.
-function isValidGitWorktree(dirPath) {
-  if (typeof dirPath !== 'string' || dirPath.length === 0) {
-    return { ok: false, reason: 'cwd missing or not a string' };
-  }
+//
+// Options:
+//   maxParentDepth — number of parent directories to walk after the direct
+//     probe; defaults to ENGINE_DEFAULTS.managedSpawn.gitWorktreeMaxParentDepth
+//     (6). Pass 0 to disable the walk and restore the legacy behavior.
+//   memo — optional Map shared across multiple calls (e.g. validating N
+//     specs in one sidecar file) so adjacent paths don't re-stat the same
+//     ancestors. Keys are absolute path strings; values are result objects.
+function _probeGitAtDir(dirPath) {
   let dirStat;
   try { dirStat = fs.statSync(dirPath); }
-  catch (_e) { return { ok: false, reason: 'directory does not exist: ' + dirPath }; }
+  catch (_e) { return { ok: false, exists: false, reason: 'directory does not exist: ' + dirPath }; }
   if (!dirStat.isDirectory()) {
-    return { ok: false, reason: 'path is not a directory: ' + dirPath };
+    return { ok: false, exists: true, reason: 'path is not a directory: ' + dirPath };
   }
   const gitPath = path.join(dirPath, '.git');
   let gitStat;
   try { gitStat = fs.statSync(gitPath); }
-  catch (_e) { return { ok: false, reason: 'no .git directory or worktree pointer at ' + dirPath }; }
-  if (gitStat.isDirectory()) return { ok: true };
+  catch (_e) { return { ok: false, exists: true, reason: 'no .git directory or worktree pointer at ' + dirPath }; }
+  if (gitStat.isDirectory()) return { ok: true, exists: true, gitPath: gitPath };
   if (gitStat.isFile()) {
     // Worktree pointer files contain "gitdir: <abs path>" on the first line.
     // A `.git` file that doesn't match this shape is a normal file, not a
     // valid worktree linkage — reject it.
     let head = '';
     try { head = fs.readFileSync(gitPath, { encoding: 'utf8', flag: 'r' }).slice(0, 256); }
-    catch (e) { return { ok: false, reason: '.git file unreadable: ' + e.message }; }
-    if (/^gitdir:\s*\S/.test(head)) return { ok: true };
-    return { ok: false, reason: '.git file present but not a worktree pointer (no "gitdir:" prefix): ' + dirPath };
+    catch (e) { return { ok: false, exists: true, reason: '.git file unreadable: ' + e.message }; }
+    if (/^gitdir:\s*\S/.test(head)) return { ok: true, exists: true, gitPath: gitPath };
+    return { ok: false, exists: true, reason: '.git file present but not a worktree pointer (no "gitdir:" prefix): ' + dirPath };
+  }
+  return { ok: false, exists: true, reason: '.git entry is neither a file nor a directory: ' + gitPath };
+}
+
+function isValidGitWorktree(dirPath, opts) {
+  if (typeof dirPath !== 'string' || dirPath.length === 0) {
+    return { ok: false, exists: false, nearestGitAncestor: null, worktreeRoot: null, depth: -1, reason: 'cwd missing or not a string' };
+  }
+  opts = opts || {};
+  const limits = (ENGINE_DEFAULTS && ENGINE_DEFAULTS.managedSpawn) || {};
+  const defaultDepth = Number.isFinite(limits.gitWorktreeMaxParentDepth) ? limits.gitWorktreeMaxParentDepth : 6;
+  const maxDepth = Math.max(0, Number.isFinite(opts.maxParentDepth) ? opts.maxParentDepth : defaultDepth);
+  const memo = opts.memo instanceof Map ? opts.memo : null;
+
+  if (memo && memo.has(dirPath)) return memo.get(dirPath);
+
+  const direct = _probeGitAtDir(dirPath);
+  if (direct.ok) {
+    const out = { ok: true, exists: true, nearestGitAncestor: direct.gitPath, worktreeRoot: dirPath, depth: 0 };
+    if (memo) memo.set(dirPath, out);
+    return out;
   }
-  return { ok: false, reason: '.git entry is neither a file nor a directory: ' + gitPath };
+
+  // Don't walk ancestors when the path itself doesn't exist — that's a stale
+  // / typoed cwd, not a monorepo subdir, and walking would mask the real
+  // problem. The legacy "directory does not exist" reason is preserved.
+  if (!direct.exists) {
+    const out = { ok: false, exists: false, nearestGitAncestor: null, worktreeRoot: null, depth: -1, reason: direct.reason };
+    if (memo) memo.set(dirPath, out);
+    return out;
+  }
+
+  // Walk parents up to maxDepth, looking for any ancestor whose direct probe
+  // succeeds. Reuse the memo for previously-seen ancestors (matters when
+  // validating several specs that share a common worktree-root prefix).
+  let cur = dirPath;
+  let walked = 0;
+  for (let i = 1; i <= maxDepth; i++) {
+    const parent = path.dirname(cur);
+    if (parent === cur) break; // hit the filesystem root
+    walked = i;
+    if (memo && memo.has(parent)) {
+      const cached = memo.get(parent);
+      if (cached.ok) {
+        const out = { ok: true, exists: true, nearestGitAncestor: cached.nearestGitAncestor, worktreeRoot: cached.worktreeRoot, depth: i };
+        memo.set(dirPath, out);
+        return out;
+      }
+      cur = parent;
+      continue;
+    }
+    const probe = _probeGitAtDir(parent);
+    if (probe.ok) {
+      const ancestorResult = { ok: true, exists: true, nearestGitAncestor: probe.gitPath, worktreeRoot: parent, depth: 0 };
+      if (memo) memo.set(parent, ancestorResult);
+      const out = { ok: true, exists: true, nearestGitAncestor: probe.gitPath, worktreeRoot: parent, depth: i };
+      if (memo) memo.set(dirPath, out);
+      return out;
+    }
+    cur = parent;
+  }
+
+  // No ancestor satisfied the .git probe. Synthesize a reason that keeps the
+  // direct-probe detail (so legacy substring assertions like "no .git" and
+  // "not a worktree pointer" still match) AND adds the ancestor-walk context
+  // the dispatcher prompt needs to distinguish "stale path" from
+  // "real subdir of an unrelated dir".
+  const reason = direct.reason
+    + ' (and no .git directory or worktree pointer in any of '
+    + walked + ' parent directories up to depth ' + maxDepth + ')';
+  const out = { ok: false, exists: true, nearestGitAncestor: null, worktreeRoot: null, depth: -1, reason: reason };
+  if (memo) memo.set(dirPath, out);
+  return out;
 }
 
 function shellSafeGh(args, opts = {}) {
@@ -1513,6 +1598,12 @@ const ENGINE_DEFAULTS = {
     bootReconcileMaxMs: 2000,       // boot-time reconcile timeout (don't block engine boot)
     promptContextMaxBytes: 2048,    // cap on auto-injected `## Live managed processes` block
     requireGitWorkdir: true,        // reject specs whose `cwd` isn't a real git worktree
+    // W-mpbpa01y000qcdc2 — how many parent directories `isValidGitWorktree`
+    // walks before giving up. In monorepos only the worktree ROOT has `.git`;
+    // a per-package `cwd` like `<root>/packages/server` needs the walk to
+    // succeed. 6 covers `packages/<pkg>/src/<sub>/<sub>/<sub>` without
+    // walking out of any realistic project; set to 0 to disable.
+    gitWorktreeMaxParentDepth: 6,
     // Single global executable allowlist. Applies to both `spec.cmd` and any
     // `command` healthcheck's `cmd`. Keep narrow — adding a binary here lets
     // any agent's sidecar invoke it under engine ownership.

package/engine/worktree-gc.js

@@ -0,0 +1,360 @@
+// engine/worktree-gc.js — orphan-worktree garbage collection
+//
+// W-mpbqhstz001lf518 (closes yemi33/minions#2627). Two callers, one shared
+// decision surface:
+//
+//   1. On dispatch end (engine.js onAgentClose): remove the dispatch's
+//      worktree once the agent process has truly exited and all sidecar
+//      reads (keep_processes, managed_spawn) are done. Skip when the
+//      worktree was borrowed from the pool, returned to the pool, or is
+//      anchored by live keep_processes PIDs / managed_spawn cwds.
+//
+//   2. On engine boot (engine/cli.js): scan each project's worktree root
+//      for orphan W-* dirs whose dispatch is not in dispatch.json (active
+//      or pending) AND that are not pool entries. Such dirs are leftovers
+//      from a prior crash that block retries with
+//      `fatal: 'work/W-…' is already used by worktree at …`.
+//
+// All git ops route through `shared.removeWorktree` (which already runs
+// `git worktree remove --force` + `git worktree prune`). All git ops run
+// OUTSIDE `mutateJsonFileLocked` callbacks — per the lock-callback
+// contract in CLAUDE.md ("do not run network calls, git commands, process
+// kills, or `await` while holding a file lock").
+
+const fs = require('fs');
+const path = require('path');
+
+const shared = require('./shared');
+const worktreePool = require('./worktree-pool');
+
+let keepProcessSweep = null;
+function _keepProcessSweep() {
+  if (!keepProcessSweep) keepProcessSweep = require('./keep-process-sweep');
+  return keepProcessSweep;
+}
+
+let managedSpawn = null;
+function _managedSpawn() {
+  if (!managedSpawn) managedSpawn = require('./managed-spawn');
+  return managedSpawn;
+}
+
+const _noopLog = () => {};
+
+/**
+ * Decide whether a dispatch-end worktree should be GC'd.
+ *
+ * Inputs are explicit so callers can supply mocks. Returns
+ *   { gc: boolean, reason: string }
+ * where `reason` is a short tag suitable for logging.
+ *
+ * Skip rules (any one wins, in priority order):
+ *   - no-worktree-path         — worktreePath empty / null
+ *   - missing-on-disk          — worktreePath does not exist (already gone)
+ *   - pool-member              — worktree-pool currently owns this path
+ *                                (covers borrowed + idle + returned states;
+ *                                authoritative over the legacy in-memory
+ *                                borrowedFromPool/returnedToPool flags
+ *                                because the pool can evict between borrow
+ *                                and dispatch-end — see PR #2627 review)
+ *   - keep-processes-anchored  — agent declared keep_processes PIDs that are live
+ *   - managed-spawn-anchored   — agent placed managed_spawn services with cwd
+ *                                inside (or equal to) the worktree (checked
+ *                                BOTH against in-memory `managedSpawnSpawnedCount`
+ *                                for services this dispatch just spawned AND
+ *                                against the global state file for legacy
+ *                                services that recordManagedBatch persisted)
+ *
+ * Otherwise: `{ gc: true, reason: 'orphan' }`.
+ */
+function shouldGcDispatchWorktree(opts) {
+  const {
+    worktreePath,
+    agentId = '',
+    // Belt+suspenders: defensive override when caller wants to forcibly
+    // protect this worktree regardless of pool/anchor state.
+    forceSkip = false,
+    // In-memory hint from the dispatch-end caller: when > 0, services were
+    // spawned by THIS dispatch but recordManagedBatch may have failed to
+    // persist them; skip GC unconditionally to prevent yanking their cwd.
+    managedSpawnSpawnedCount = 0,
+    // Test injection points — production callers leave undefined.
+    isPoolMember = null,
+    listManagedSpecs = null,
+    getActiveAnchorPidsForAgent = null,
+    fileExists = null,
+  } = opts || {};
+
+  if (!worktreePath) return { gc: false, reason: 'no-worktree-path' };
+  const exists = typeof fileExists === 'function'
+    ? !!fileExists(worktreePath)
+    : fs.existsSync(worktreePath);
+  if (!exists) return { gc: false, reason: 'missing-on-disk' };
+  if (forceSkip) return { gc: false, reason: 'force-skip' };
+
+  // Pool ownership is authoritative: the pool's on-disk state file tells us
+  // whether ANY pool entry (idle, borrowed, just-returned) currently claims
+  // this path. Subsumes the legacy in-memory borrowedFromPool/returnedToPool
+  // flags and covers the pool-return-throw eviction case correctly.
+  try {
+    const fn = typeof isPoolMember === 'function'
+      ? isPoolMember
+      : (wt) => worktreePool.isPoolMember(wt);
+    if (fn(worktreePath)) return { gc: false, reason: 'pool-member' };
+  } catch (_e) { /* pool readable optional */ }
+
+  // In-memory managed-spawn signal: this dispatch's own spawn batch.
+  // `managedSpawnSpawnedCount > 0` means recordManagedBatch was called (or
+  // attempted) — the cwd of those services lives inside this worktree, so
+  // even if the state-file persistence failed we must protect them.
+  if (Number(managedSpawnSpawnedCount) > 0) {
+    return { gc: false, reason: 'managed-spawn-anchored' };
+  }
+
+  // keep_processes anchor check: any live PID for this agent → skip.
+  if (agentId) {
+    try {
+      const fn = typeof getActiveAnchorPidsForAgent === 'function'
+        ? getActiveAnchorPidsForAgent
+        : _keepProcessSweep().getActiveAnchorPidsForAgent;
+      const res = fn(agentId);
+      if (res && res.pids && res.pids.size > 0) {
+        return { gc: false, reason: 'keep-processes-anchored' };
+      }
+    } catch (_e) { /* sidecar reader optional */ }
+  }
+
+  // managed_spawn anchor check: any LIVE spec (from any agent) whose cwd
+  // is == or under the worktree → skip. Covers the "completed dispatch
+  // with long-running managed-spawn services survives boot" case.
+  try {
+    const fn = typeof listManagedSpecs === 'function'
+      ? listManagedSpecs
+      : _managedSpawn().listManagedSpecs;
+    const specs = fn() || [];
+    const wtAbs = path.resolve(worktreePath);
+    const wtPrefix = wtAbs + path.sep;
+    for (const rec of specs) {
+      if (!rec || typeof rec.cwd !== 'string' || rec.cwd.length === 0) continue;
+      let cwdAbs;
+      try { cwdAbs = path.resolve(rec.cwd); } catch { continue; }
+      if (cwdAbs === wtAbs || cwdAbs.startsWith(wtPrefix)) {
+        return { gc: false, reason: 'managed-spawn-anchored' };
+      }
+    }
+  } catch (_e) { /* sidecar reader optional */ }
+
+  return { gc: true, reason: 'orphan' };
+}
+
+/**
+ * Run shouldGcDispatchWorktree + (if eligible) `shared.removeWorktree`.
+ *
+ * Returns `{ outcome, reason, removed }`:
+ *   - outcome: 'gc'|'skip'|'gc-failed'
+ *   - reason:  short tag from shouldGcDispatchWorktree, or 'remove-failed'
+ *   - removed: boolean — true when removeWorktree returned truthy
+ */
+function gcDispatchWorktreeIfOrphan(opts) {
+  const {
+    worktreePath,
+    gitRoot,
+    worktreeRoot,
+    log = _noopLog,
+    removeWorktree = null,
+  } = opts || {};
+  const decision = shouldGcDispatchWorktree(opts);
+  if (!decision.gc) {
+    return { outcome: 'skip', reason: decision.reason, removed: false };
+  }
+  if (!gitRoot || !worktreeRoot) {
+    return { outcome: 'skip', reason: 'no-git-root', removed: false };
+  }
+  const _removeFn = typeof removeWorktree === 'function' ? removeWorktree : shared.removeWorktree;
+  try {
+    const removed = _removeFn(worktreePath, gitRoot, worktreeRoot);
+    if (removed) {
+      log('info', `worktree-gc: dispatch-end removed ${path.basename(worktreePath)}`);
+      return { outcome: 'gc', reason: decision.reason, removed: true };
+    }
+    log('warn', `worktree-gc: dispatch-end remove returned false for ${worktreePath}`);
+    return { outcome: 'gc-failed', reason: 'remove-failed', removed: false };
+  } catch (gcErr) {
+    log('warn', `worktree-gc: dispatch-end remove threw for ${worktreePath}: ${gcErr.message}`);
+    return { outcome: 'gc-failed', reason: 'remove-threw', removed: false };
+  }
+}
+
+/**
+ * Walk each project's worktree root and evict orphan W-* dirs.
+ *
+ *   - `projects`        — array of `{ name, localPath }`
+ *   - `dispatchSnap`    — `{ active: [...], pending: [...] }` (work-item dispatch.json)
+ *   - `worktreeRootRel` — relative dir under each project's localPath (default '../worktrees')
+ *   - `log`             — log(level, msg) function (optional)
+ *   - `fs`/`removeWorktree`/`buildWorktreeDirName`/`listManagedSpecs` — test injection points
+ *
+ * Protection rules (any hit → keep):
+ *   1. Dir name matches the wtDirName of any active/pending dispatch in
+ *      `dispatchSnap`, computed using THAT DISPATCH'S OWN project name.
+ *      We iterate every (dispatch, project) combo so two projects sharing
+ *      a parent `worktreeRoot` (monorepo-style) don't cross-evict each
+ *      other's dispatches. (PR #2627 review — Issue 2)
+ *   2. Normalized abs path is currently in any `worktreePool` entry (idle
+ *      or borrowed) — see `extraPoolPaths` for the test override.
+ *   3. Worktree contains (or equals) the cwd of any live managed_spawn
+ *      spec — matches `engine/cleanup.js`'s tick-time protection so a
+ *      completed dispatch with long-running services survives engine
+ *      restart. (PR #2627 review — Issue 1)
+ *
+ * Returns `{ scanned, kept, evicted, failed, perProject }`.
+ */
+function pruneOrphanWorktrees(opts) {
+  opts = opts || {};
+  const projects = Array.isArray(opts.projects) ? opts.projects : [];
+  const dispatchSnap = opts.dispatchSnap || { active: [], pending: [] };
+  const worktreeRootRel = typeof opts.worktreeRootRel === 'string' && opts.worktreeRootRel.length > 0
+    ? opts.worktreeRootRel
+    : (shared.ENGINE_DEFAULTS && shared.ENGINE_DEFAULTS.worktreeRoot) || '../worktrees';
+  const log = typeof opts.log === 'function' ? opts.log : _noopLog;
+  const _fs = opts.fs || fs;
+  const _removeWorktree = typeof opts.removeWorktree === 'function'
+    ? opts.removeWorktree
+    : shared.removeWorktree;
+  const _buildWorktreeDirName = typeof opts.buildWorktreeDirName === 'function'
+    ? opts.buildWorktreeDirName
+    : shared.buildWorktreeDirName;
+  const _listManagedSpecs = typeof opts.listManagedSpecs === 'function'
+    ? opts.listManagedSpecs
+    : (() => {
+      try { return _managedSpawn().listManagedSpecs(); }
+      catch (_e) { return []; }
+    });
+
+  // Pool-known paths (idle + borrowed + any stale entry still on disk). The
+  // worktree-pool's own pruneStale() runs FIRST in cli boot so this snapshot
+  // is post-prune.
+  const poolPaths = new Set();
+  try {
+    const entries = (worktreePool.readPool() || { entries: [] }).entries || [];
+    for (const e of entries) {
+      if (e && e.path) poolPaths.add(worktreePool._normalizePath(e.path));
+    }
+  } catch (_e) { /* pool readable optional */ }
+  if (Array.isArray(opts.extraPoolPaths)) {
+    for (const p of opts.extraPoolPaths) poolPaths.add(worktreePool._normalizePath(p));
+  }
+
+  // Cross-project live dir names: compute the expected wtDirName for every
+  // active/pending dispatch using THAT DISPATCH'S OWN project name. Each
+  // dir name's hash depends on (id, projectName, branchName), so a dir
+  // belonging to project B will not appear when we compute names for A.
+  // This prevents the cross-project sweep from yanking another project's
+  // active worktree when they share a parent `worktreeRoot`. (PR #2627
+  // review — Issue 2)
+  const globalLiveDirNames = new Set();
+  for (const d of [...(dispatchSnap.active || []), ...(dispatchSnap.pending || [])]) {
+    if (!d || !d.id || !d.meta || !d.meta.branch) continue;
+    const dispatchProject = (d.meta.project && typeof d.meta.project === 'string')
+      ? d.meta.project
+      : 'default';
+    try {
+      globalLiveDirNames.add(_buildWorktreeDirName({
+        dispatchId: d.id,
+        projectName: dispatchProject,
+        branchName: d.meta.branch,
+      }));
+    } catch (_e) { /* defensive */ }
+  }
+
+  // Resolved managed-spawn cwds (per-cwd → resolved abs path). Used to
+  // reject GC of any dir that contains (or equals) a live service's cwd.
+  // (PR #2627 review — Issue 1)
+  const managedSpawnCwds = [];
+  try {
+    for (const rec of (_listManagedSpecs() || [])) {
+      if (!rec || typeof rec.cwd !== 'string' || rec.cwd.length === 0) continue;
+      try { managedSpawnCwds.push(path.resolve(rec.cwd)); }
+      catch (_e) { /* malformed cwd — skip */ }
+    }
+  } catch (_e) { /* optional */ }
+
+  const result = { scanned: 0, kept: 0, evicted: 0, failed: 0, perProject: {} };
+
+  for (const project of projects) {
+    if (!project || !project.localPath) continue;
+    let rootDir;
+    try { rootDir = path.resolve(String(project.localPath)); } catch { continue; }
+    let rootExists = false;
+    try { rootExists = _fs.existsSync(rootDir); } catch { rootExists = false; }
+    if (!rootExists) continue;
+    const wtParent = path.resolve(rootDir, worktreeRootRel);
+    let parentExists = false;
+    try { parentExists = _fs.existsSync(wtParent); } catch { parentExists = false; }
+    if (!parentExists) continue;
+
+    let entries;
+    try { entries = _fs.readdirSync(wtParent, { withFileTypes: true }); }
+    catch (readErr) {
+      log('warn', `worktree-gc: readdir failed for ${wtParent}: ${readErr.message}`);
+      continue;
+    }
+
+    const projStats = { scanned: 0, kept: 0, evicted: 0, failed: 0 };
+    for (const ent of entries) {
+      if (!ent || (typeof ent.isDirectory === 'function' && !ent.isDirectory())) continue;
+      const name = ent.name || ent;
+      if (typeof name !== 'string' || name.length === 0) continue;
+      projStats.scanned++;
+      result.scanned++;
+      const wtPath = path.join(wtParent, name);
+
+      // 1. Live-dispatch protection (cross-project safe).
+      if (globalLiveDirNames.has(name)) {
+        projStats.kept++; result.kept++;
+        continue;
+      }
+      // 2. Pool membership protection.
+      const normPath = worktreePool._normalizePath(wtPath);
+      if (poolPaths.has(normPath)) {
+        projStats.kept++; result.kept++;
+        continue;
+      }
+      // 3. managed_spawn cwd anchor protection.
+      if (managedSpawnCwds.length > 0) {
+        const wtPathNorm = path.resolve(wtPath);
+        const wtPrefix = wtPathNorm + path.sep;
+        let anchored = false;
+        for (const cwd of managedSpawnCwds) {
+          if (cwd === wtPathNorm || cwd.startsWith(wtPrefix)) { anchored = true; break; }
+        }
+        if (anchored) {
+          projStats.kept++; result.kept++;
+          continue;
+        }
+      }
+
+      try {
+        const removed = _removeWorktree(wtPath, rootDir, wtParent);
+        if (removed) {
+          projStats.evicted++; result.evicted++;
+          log('info', `worktree-gc: boot-evicted orphan ${name} for project ${project.name || 'default'}`);
+        } else {
+          projStats.failed++; result.failed++;
+          log('warn', `worktree-gc: boot-evict returned false for ${wtPath}`);
+        }
+      } catch (rmErr) {
+        projStats.failed++; result.failed++;
+        log('warn', `worktree-gc: boot-evict threw for ${wtPath}: ${rmErr.message}`);
+      }
+    }
+    result.perProject[project.name || rootDir] = projStats;
+  }
+  return result;
+}
+
+module.exports = {
+  shouldGcDispatchWorktree,
+  gcDispatchWorktreeIfOrphan,
+  pruneOrphanWorktrees,
+};

package/engine.js

@@ -2600,9 +2600,15 @@ async function spawnAgent(dispatchItem, config) {
             // Capacity rejected — drop any stale entry so cleanup can reap normally.
             worktreePool.evictEntry(worktreePath, 'capacity-rejected');
           }
+          // W-mpbqhstz001lf518: 'inserted'/'flipped' both leave the pool
+          // owning the worktree on disk; the dispatch-end GC below queries
+          // `worktreePool.isPoolMember(worktreePath)` to honor that.
         } catch (returnErr) {
           log('warn', `worktree-pool: return failed for ${worktreePath}: ${returnErr.message} — evicting from pool`);
           worktreePool.evictEntry(worktreePath, 'return-git-failed');
+          // After eviction, the pool no longer owns this worktree — the
+          // dispatch-end GC below will pick it up via the isPoolMember
+          // check (which now correctly returns false).
         }
       } else if (_keepPidsAlive || _managedSpawnAlive) {
         // Skip the pool — the worktree is in use by left-running processes
@@ -2613,6 +2619,42 @@ async function spawnAgent(dispatchItem, config) {
       }
     }
 
+    // W-mpbqhstz001lf518 — dispatch-end orphan worktree GC (closes #2627).
+    // Runs AFTER all sidecar reads (keep_processes / managed_spawn
+    // acceptance + healthcheck) and AFTER the pool-return block has settled
+    // its decision, BEFORE completeDispatch finalizes the dispatch. The GC
+    // decision queries `worktreePool.isPoolMember(worktreePath)` directly
+    // — that on-disk state is authoritative over the in-memory
+    // borrowedFromPool/returnedToPool flags because the pool can evict the
+    // entry mid-dispatch (e.g. when returnToPool throws). We also pass
+    // `managedSpawnSpawnedCount` so a spawn batch where recordManagedBatch
+    // silently failed still protects the cwd from GC. Without this GC, a
+    // crashed dispatch leaks `work/W-<id>` worktree entries that block
+    // every retry with `fatal: 'work/W-<id>' is already used by worktree
+    // at …` until the 2-hour age sweep in cleanup.js eventually catches up.
+    if (worktreePath && rootDir && branchName) {
+      try {
+        const _wgc = require('./engine/worktree-gc');
+        const _wtRoot = path.resolve(rootDir, engineConfig.worktreeRoot || ENGINE_DEFAULTS.worktreeRoot);
+        const _gcResult = _wgc.gcDispatchWorktreeIfOrphan({
+          worktreePath,
+          gitRoot: rootDir,
+          worktreeRoot: _wtRoot,
+          agentId,
+          managedSpawnSpawnedCount: Array.isArray(managedSpawnSpawned) ? managedSpawnSpawned.length : 0,
+          log,
+        });
+        if (_gcResult.outcome === 'gc') {
+          log('info', `worktree-gc: dispatch-end GC of ${path.basename(worktreePath)} (id=${id}, agent=${agentId})`);
+        } else if (_gcResult.outcome === 'gc-failed') {
+          log('warn', `worktree-gc: dispatch-end GC failed for ${worktreePath} (id=${id}): ${_gcResult.reason}`);
+        }
+        // 'skip' is silent — every skip reason is expected behavior.
+      } catch (gcErr) {
+        log('warn', `worktree-gc: dispatch-end check threw for ${worktreePath} (id=${id}): ${gcErr.message}`);
+      }
+    }
+
     completeDispatch(id, effectiveResult, errorReason, resultSummary, completeOpts);
 
     // W-mpbpexrg00110661 — surface managed-spawn partial-healthcheck failures
@@ -4462,11 +4504,21 @@ function discoverFromWorkItems(config, project) {
     if (item.depends_on && item.depends_on.length > 0) {
       const depStatus = areDependenciesMet(item, config);
       if (depStatus === 'failed' && !isItemCompleted(item)) {
-        item.status = WI_STATUS.FAILED;
-        item.failReason = 'Dependency failed — cannot proceed';
-        delete item._pendingReason;
-        log('warn', `Marking ${item.id} as failed: dependency failed (plan: ${item.sourcePlan})`);
-        needsWrite = true;
+        // W-mpbqhstz001lf518 (closes #2627) — do NOT cascade-fail the
+        // dependent. Previously we set status=FAILED here, which burned the
+        // dependent's _retryCount every time the dep was auto-retried and
+        // failed again, and left the dependent stuck at `failed` requiring
+        // manual intervention even after the dep eventually succeeded.
+        //
+        // New behavior: surface `_pendingReason: 'dependency_failed'` and
+        // skip dispatch this tick. The dependent stays PENDING so when the
+        // dep flips to done (e.g. via the stall-recovery sweep auto-retry
+        // at engine.js:5577), the dependent picks up naturally on the next
+        // dispatch tick. No _retryCount increment, no FAILED mark.
+        if (item._pendingReason !== 'dependency_failed') {
+          item._pendingReason = 'dependency_failed';
+          needsWrite = true;
+        }
         continue;
       }
       if (!depStatus) {

package/package.json

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