@yemi33/minions 0.1.1981 → 0.1.1982

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/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/package.json

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