@yemi33/minions 0.1.1984 → 0.1.1986

package/engine/recovery.js

@@ -28,6 +28,12 @@ const RECOVERY_RECIPES = new Map([
     freshSession: false,
     description: 'Permission/trust gate blocked — requires human intervention',
   }],
+  [FAILURE_CLASS.AUTH, {
+    maxAttempts: 0,
+    escalation: ESCALATION_POLICY.NO_RETRY,
+    freshSession: false,
+    description: 'Git/network authentication failed (missing az login, expired token, GCM prompt) — requires human credential fix before retry',
+  }],
   [FAILURE_CLASS.MERGE_CONFLICT, {
     maxAttempts: 2,
     escalation: ESCALATION_POLICY.RETRY_SAME,

package/engine/shared.js

@@ -68,6 +68,12 @@ const ENGINE_STATE_PATH = path.join(ENGINE_DIR, 'state.json');
 const PR_LINKS_PATH = path.join(MINIONS_DIR, 'engine', 'pr-links.json');
 const PINNED_ITEMS_PATH = path.join(MINIONS_DIR, 'engine', 'kb-pins.json');
 const LOG_PATH = path.join(MINIONS_DIR, 'engine', 'log.json');
+// Constellation-bridge cross-repo marker (P-wi1-bridge-readonly). Written by the
+// Constellation agent's bridge on every successful poll; read by `minions bridge
+// status` to surface the last-seen timestamp. The engine itself never writes
+// this file — it is a one-way breadcrumb from Constellation → Minions.
+const CONSTELLATION_BRIDGE_MARKER_PATH = path.join(MINIONS_DIR, 'engine', 'constellation-bridge.json');
+const CONSTELLATION_BRIDGE_MARKER_SCHEMA_VERSION = 1;
 
 // ── Timestamps & Logging ────────────────────────────────────────────────────
 // Extracted from engine.js so engine/* modules can import directly without
@@ -477,6 +483,156 @@ function safeUnlink(p) {
   try { fs.unlinkSync(p); } catch { /* cleanup */ }
 }
 
+// ─── Per-dispatch temp dirs (P-f6-tmp-toctou) ────────────────────────────────
+//
+// Background: agent dispatches share `engine/tmp/` with predictable prefixes
+// (`prompt-<id>.md`, `pid-<id>.pid`, `sysprompt-<id>.md.tmp`). A sibling agent
+// running under the same engine identity could plant a symlink at one of those
+// paths before the engine wrote there, redirecting reads/writes to attacker-
+// controlled content. Per-dispatch unique dirs (mkdtempSync + 0o700) close the
+// path-prediction window; readFileNoFollow() closes the symlink-traversal
+// window on platforms that support O_NOFOLLOW.
+
+const DISPATCH_TMP_PREFIX = 'dispatch-';
+
+function _dispatchTmpRoot() {
+  return path.join(MINIONS_DIR, 'engine', 'tmp');
+}
+
+function _safeDispatchId(dispatchId) {
+  return String(dispatchId || '').replace(/[^a-zA-Z0-9_-]/g, '-');
+}
+
+// Create a unique tmp dir for a single dispatch.
+//   engine/tmp/dispatch-<safeId>-XXXXXX/   (6-char random suffix from mkdtemp)
+// POSIX: chmod to 0o700 (owner-only). Windows: ACL inherits from MINIONS_DIR
+// (typically owner-only on a single-user devbox); chmod is a no-op for ACLs.
+function createDispatchTmpDir(dispatchId) {
+  const safeId = _safeDispatchId(dispatchId);
+  if (!safeId) throw new Error('createDispatchTmpDir: dispatchId required');
+  const tmpRoot = _dispatchTmpRoot();
+  if (!fs.existsSync(tmpRoot)) fs.mkdirSync(tmpRoot, { recursive: true });
+  const dir = fs.mkdtempSync(path.join(tmpRoot, `${DISPATCH_TMP_PREFIX}${safeId}-`));
+  if (process.platform !== 'win32') {
+    try { fs.chmodSync(dir, 0o700); } catch { /* best-effort */ }
+  }
+  return dir;
+}
+
+// Validate a tmpDir path before destructive ops (rmSync). Defends against a
+// corrupted/poisoned dispatch.json `entry.tmpDir` field pointing at an
+// arbitrary directory: must resolve under <MINIONS_DIR>/engine/tmp/, basename
+// must match `dispatch-*`, and lstat must be a real directory (not a symlink).
+function validateDispatchTmpDir(dirPath) {
+  if (!dirPath || typeof dirPath !== 'string') return false;
+  let resolved;
+  try { resolved = path.resolve(dirPath); }
+  catch { return false; }
+  const root = path.resolve(_dispatchTmpRoot());
+  const rel = path.relative(root, resolved);
+  if (rel.startsWith('..') || path.isAbsolute(rel) || rel === '') return false;
+  if (!path.basename(resolved).startsWith(DISPATCH_TMP_PREFIX)) return false;
+  let stat;
+  try { stat = fs.lstatSync(resolved); }
+  catch { return false; }
+  if (!stat.isDirectory()) return false;
+  return true;
+}
+
+function removeDispatchTmpDir(dirPath) {
+  if (!validateDispatchTmpDir(dirPath)) return false;
+  try { fs.rmSync(dirPath, { recursive: true, force: true }); return true; }
+  catch { return false; }
+}
+
+// Read a file using O_NOFOLLOW where the platform supports it. On Windows
+// fs.constants.O_NOFOLLOW is undefined, so the bitwise-or below is a no-op
+// (Windows non-junction reads don't follow symlinks the way POSIX does).
+function readFileNoFollow(filepath, encoding = 'utf8') {
+  const NOFOLLOW = fs.constants.O_NOFOLLOW || 0;
+  let fd;
+  try {
+    fd = fs.openSync(filepath, fs.constants.O_RDONLY | NOFOLLOW);
+    const stat = fs.fstatSync(fd);
+    const buf = Buffer.alloc(stat.size);
+    let read = 0;
+    while (read < stat.size) {
+      const n = fs.readSync(fd, buf, read, stat.size - read, read);
+      if (n <= 0) break;
+      read += n;
+    }
+    return encoding ? buf.toString(encoding) : buf;
+  } finally {
+    if (fd !== undefined) {
+      try { fs.closeSync(fd); } catch { /* close-after-error */ }
+    }
+  }
+}
+
+// Returns absolute paths to candidate PID files for a dispatch id. Resolution
+// order: (1) entry.tmpDir/pid-<safeId>.pid if `entryOrId` is a dispatch entry
+// with a validated tmpDir; (2) engine/tmp/dispatch-<safeId>-*/pid-<safeId>.pid
+// (post-P-f6-tmp-toctou layout); (3) engine/tmp/pid-<safeId>.pid (legacy flat
+// layout — pre-P-f6-tmp-toctou and during the transition window).
+function dispatchPidCandidates(entryOrId) {
+  const entry = (entryOrId && typeof entryOrId === 'object') ? entryOrId : null;
+  const id = entry?.id || entryOrId;
+  const safeId = _safeDispatchId(id);
+  if (!safeId) return [];
+  const candidates = [];
+  if (entry?.tmpDir && validateDispatchTmpDir(entry.tmpDir)) {
+    candidates.push(path.join(entry.tmpDir, `pid-${safeId}.pid`));
+  }
+  const tmpRoot = _dispatchTmpRoot();
+  try {
+    for (const name of fs.readdirSync(tmpRoot)) {
+      if (!name.startsWith(`${DISPATCH_TMP_PREFIX}${safeId}-`)) continue;
+      const dir = path.join(tmpRoot, name);
+      if (!validateDispatchTmpDir(dir)) continue;
+      const candidate = path.join(dir, `pid-${safeId}.pid`);
+      if (!candidates.includes(candidate)) candidates.push(candidate);
+    }
+  } catch { /* tmp root may not exist yet */ }
+  const legacy = path.join(tmpRoot, `pid-${safeId}.pid`);
+  if (!candidates.includes(legacy)) candidates.push(legacy);
+  return candidates;
+}
+
+// Resolve the first existing PID file path for a dispatch (entry preferred,
+// then per-dispatch dir, then legacy). Returns null when none exist.
+function findDispatchPidFile(entryOrId) {
+  for (const candidate of dispatchPidCandidates(entryOrId)) {
+    try { if (fs.existsSync(candidate)) return candidate; } catch { /* skip */ }
+  }
+  return null;
+}
+
+// Iterate every PID file under engine/tmp/ — both the new per-dispatch layout
+// and the legacy flat layout — invoking callback(absPath, basename, layout).
+// `layout` is 'dispatch-dir' or 'legacy'. Used by orphan-reap and `kill`.
+function forEachPidFile(callback) {
+  const tmpRoot = _dispatchTmpRoot();
+  let entries;
+  try { entries = fs.readdirSync(tmpRoot, { withFileTypes: true }); }
+  catch { return; }
+  for (const entry of entries) {
+    const full = path.join(tmpRoot, entry.name);
+    if (entry.isDirectory() && entry.name.startsWith(DISPATCH_TMP_PREFIX)) {
+      if (!validateDispatchTmpDir(full)) continue;
+      let inner;
+      try { inner = fs.readdirSync(full); }
+      catch { continue; }
+      for (const f of inner) {
+        if (f.startsWith('pid-') && f.endsWith('.pid')) {
+          callback(path.join(full, f), f, 'dispatch-dir');
+        }
+      }
+    } else if (entry.isFile() && entry.name.startsWith('pid-') && entry.name.endsWith('.pid')) {
+      callback(full, entry.name, 'legacy');
+    }
+  }
+}
+
 function neutralizeJsonBackupSidecar(filePath, inertData = { status: 'archived' }) {
   const backupPath = filePath + '.backup';
   try {
@@ -739,7 +895,17 @@ function withFileLock(lockPath, fn, {
         } catch { /* payload is advisory; lock semantics unaffected */ }
         break;
       } catch (err) {
-        if (err.code !== 'EEXIST') throw err;
+        // EEXIST is the cross-platform exclusive-create collision.
+        // On Windows, the loser of an unlink/create race can surface as EPERM
+        // (errno -4048: "file is marked for deletion but not yet gone" — common
+        // when AV/Search Indexer holds an opportunistic handle on the file the
+        // prior holder just unlinked). Without this branch, the loser child
+        // dies mid-retry-loop with EPERM and the dispatch fails. Linux/macOS
+        // EPERM still throws to preserve real permission-error visibility.
+        // See W-mpd6lm1g000x195e.
+        const isLockRaceErr = err.code === 'EEXIST' ||
+          (process.platform === 'win32' && err.code === 'EPERM');
+        if (!isLockRaceErr) throw err;
         // P-b7d4e8f2 — Stale-lock check combines mtime age with PID liveness:
         //   1. If mtime <= LOCK_STALE_MS  → never reap (recently active).
         //   2. If JSON-parsable {pid, ts}:
@@ -773,15 +939,23 @@ function withFileLock(lockPath, fn, {
               try {
                 fs.unlinkSync(lockPath);
               } catch (unlinkErr) {
-                // ENOENT: another process deleted the lock between stat and unlink — safe to retry
-                if (unlinkErr.code !== 'ENOENT') throw unlinkErr;
+                // ENOENT: another process deleted the lock between stat and unlink — safe to retry.
+                // EPERM on Windows: file is in 'pending delete' state from a concurrent
+                // reaper — the OS will finalize the delete shortly; retry will succeed.
+                const tolerable = unlinkErr.code === 'ENOENT' ||
+                  (process.platform === 'win32' && unlinkErr.code === 'EPERM');
+                if (!tolerable) throw unlinkErr;
               }
               continue; // lock just removed — retry immediately
             }
           }
         } catch (staleErr) {
-          // ENOENT from statSync: lock file disappeared between EEXIST and stat — retry will succeed
-          if (staleErr.code !== 'ENOENT') throw staleErr;
+          // ENOENT from statSync: lock file disappeared between EEXIST and stat — retry will succeed.
+          // EPERM on Windows: file is in 'pending delete' state — statSync itself
+          // can fail; fall through to the normal retry sleep (W-mpd6lm1g000x195e).
+          const tolerable = staleErr.code === 'ENOENT' ||
+            (process.platform === 'win32' && staleErr.code === 'EPERM');
+          if (!tolerable) throw staleErr;
         }
         sleepMs(retryDelayMs);
       }
@@ -1089,6 +1263,55 @@ function validateGhSlug(slug) {
   return slug;
 }
 
+// P-f2-gh-shell (F2): validators for `gh api` endpoint paths and numeric IDs.
+// Used by engine/github.js to gate argv-form shell-out calls (shellSafeGh)
+// against poisoned PR JSON that could carry shell metacharacters or non-numeric
+// IDs through to child_process. All validators throw a structured Error on
+// rejection — callers must let it propagate so the shell-out never happens.
+
+// Allowlist mirrors the spec: only path chars + query-string punctuation that
+// the gh API legitimately uses. Specifically EXCLUDES shell metacharacters
+// (`;`, `$`, backtick, `|`, newlines, quotes, spaces, brackets). Leading `-`
+// is rejected separately to block argv injection (e.g. `--upload-pack=evil`).
+// `%` is allowed because callers URL-encode ref names via encodeURIComponent
+// (e.g. ghApi(`/compare/${encodeURIComponent(...)}...`)). Empty string is
+// explicitly allowed: the base-repo probe (`ghApi('', slug)`) hits
+// `repos/owner/repo` with no path suffix.
+function validateGhEndpoint(endpoint) {
+  const fail = (why) => {
+    throw new Error(`Invalid gh API endpoint (${why}): ${JSON.stringify(String(endpoint).slice(0, 128))}`);
+  };
+  if (typeof endpoint !== 'string') fail('not a string');
+  if (endpoint.length === 0) return endpoint; // base-repo probe — no path suffix
+  if (endpoint.length > 512) fail('too long');
+  if (!/^[/A-Za-z0-9._%?=&\-]+$/.test(endpoint)) fail('disallowed character');
+  if (endpoint.startsWith('-')) fail('leading dash (argv injection)');
+  return endpoint;
+}
+
+// Generic positive-integer ID validator. `name` is interpolated into the
+// thrown error so call sites can be diagnosed from logs alone.
+function validateGhNumericId(value, name = 'id') {
+  const fail = (why) => {
+    throw new Error(`Invalid GitHub ${name} (${why}): ${JSON.stringify(String(value).slice(0, 64))}`);
+  };
+  if (typeof value === 'string' && /^[0-9]+$/.test(value)) {
+    const n = Number(value);
+    if (!Number.isSafeInteger(n) || n <= 0) fail('not a positive safe integer');
+    return n;
+  }
+  if (typeof value !== 'number') fail('not a number');
+  if (!Number.isInteger(value)) fail('not an integer');
+  if (!Number.isSafeInteger(value)) fail('not a safe integer');
+  if (value <= 0) fail('not positive');
+  return value;
+}
+// Thin aliases match the call-site naming in the threat model so greps for
+// `validatePrNum` / `validateReviewId` / `validateJobId` land on real code.
+const validatePrNum    = (value) => validateGhNumericId(value, 'PR number');
+const validateReviewId = (value) => validateGhNumericId(value, 'review id');
+const validateJobId    = (value) => validateGhNumericId(value, 'job id');
+
 // W-mp6k7ywi000fa33c — pure helper. Returns:
 //   { ok: boolean,
 //     reason?: string,
@@ -1232,8 +1455,15 @@ function shellSafeGit(args, opts = {}) {
   if (!Array.isArray(args)) {
     return Promise.reject(new TypeError('shellSafeGit: args must be an array'));
   }
-  const { timeout, ...rest } = opts;
-  return _execFileAsync('git', args, {
+  // W-mpcuc8i80003a7b3 — `gitExtraArgs` is prepended to the git argv so callers
+  // can inject per-invocation `-c key=value` flags (e.g. ADO bearer-token
+  // auth header) without rewriting every shellSafeGit call site. Strip the
+  // key before delegating so it never reaches Node's execFile options.
+  const { timeout, gitExtraArgs, ...rest } = opts;
+  const finalArgs = (Array.isArray(gitExtraArgs) && gitExtraArgs.length > 0)
+    ? [...gitExtraArgs, ...args]
+    : args;
+  return _execFileAsync('git', finalArgs, {
     windowsHide: true,
     encoding: 'utf8',
     shell: false,
@@ -1249,9 +1479,13 @@ function shellSafeGitSync(args, opts = {}) {
   if (!Array.isArray(args)) {
     throw new TypeError('shellSafeGitSync: args must be an array');
   }
-  const { timeout, ...rest } = opts;
+  // W-mpcuc8i80003a7b3 — mirror the gitExtraArgs plumbing from the async variant.
+  const { timeout, gitExtraArgs, ...rest } = opts;
+  const finalArgs = (Array.isArray(gitExtraArgs) && gitExtraArgs.length > 0)
+    ? [...gitExtraArgs, ...args]
+    : args;
   const { execFileSync: _execFileSync } = require('child_process');
-  return _execFileSync('git', args, {
+  return _execFileSync('git', finalArgs, {
     windowsHide: true,
     encoding: 'utf8',
     shell: false,
@@ -1653,6 +1887,29 @@ const ENGINE_DEFAULTS = {
   // knows which subkeys to flag as deprecated. Do not consume `claude.*` in new code — use the runtime
   // adapter system (engine/runtimes/) and the resolveAgent*/resolveCc* helpers instead.
   _deprecatedConfigClaudeFields: ['binary', 'outputFormat', 'allowedTools', 'maxTurns', 'effort', 'budgetCap'],
+  // ── Constellation bridge (P-wi1-bridge-readonly) ────────────────────────────
+  // Read-only cross-repo bridge that lets the Constellation dashboard project
+  // Minions engine state (agents, dispatch queue, PR pipeline) into its HUD.
+  // Bridge logic itself lives in the Constellation repo
+  // (packages/agent/src/bridges/) — Minions only owns the on/off flag and the
+  // marker-file contract used by `minions bridge status`.
+  //
+  // Strict semantics: ONLY the literal boolean `true` enables the bridge. Any
+  // missing, malformed, or non-boolean value is treated as disabled. The
+  // Constellation reader MUST mirror this check (no truthy coercion) so a
+  // typo'd `"enabled": "false"` does not silently turn the bridge on.
+  //
+  // Marker-file contract (`engine/constellation-bridge.json`, written by the
+  // Constellation agent's bridge on every poll, never by the engine itself):
+  //   { "schemaVersion": 1, "lastSeenAt": "<ISO8601>",
+  //     "agentVersion": "<semver>", "source": "constellation-agent" }
+  // See docs/constellation-bridge.md and bin/minions.js (`bridge` subcommand).
+  //
+  // Default OFF so the Minions-side PR can land independently of (and ahead
+  // of) the Constellation-side PR per the WI acceptance criterion.
+  constellationBridge: {
+    enabled: false,
+  },
 };
 
 // ─── Runtime Fleet Resolution (P-3b8e5f1d) ──────────────────────────────────
@@ -2307,6 +2564,7 @@ const AGENT_STATUS = {
 const FAILURE_CLASS = {
   CONFIG_ERROR: 'config-error',           // Exit code 78, CLI not found, bad config
   PERMISSION_BLOCKED: 'permission-blocked', // Trust gate, permission denied, auth failure
+  AUTH: 'auth',                           // W-mpcuc8i80003a7b3: git/network credential failure (e.g. ADO bearer-token acquire or GCM prompt) — structural, never retryable mechanically
   MERGE_CONFLICT: 'merge-conflict',       // Git merge conflict in worktree or dependency
   BUILD_FAILURE: 'build-failure',         // Compilation, lint, or test failure
   TIMEOUT: 'timeout',                     // Hard runtime timeout or stale-orphan timeout
@@ -4379,6 +4637,8 @@ module.exports = {
   PR_LINKS_PATH,
   PINNED_ITEMS_PATH,
   LOG_PATH,
+  CONSTELLATION_BRIDGE_MARKER_PATH,
+  CONSTELLATION_BRIDGE_MARKER_SCHEMA_VERSION,
   currentLogPath: _currentLogPath,
   ts,
   logTs,
@@ -4390,6 +4650,13 @@ module.exports = {
   safeWrite,
   mutateTextFileLocked,
   safeUnlink,
+  createDispatchTmpDir,
+  removeDispatchTmpDir,
+  validateDispatchTmpDir,
+  readFileNoFollow,
+  dispatchPidCandidates,
+  findDispatchPidFile,
+  forEachPidFile,
   resolveMinionsHome,
   saveMinionsRootPointer,
   neutralizeJsonBackupSidecar,
@@ -4424,6 +4691,11 @@ module.exports = {
   shellSafeGitSync,
   validateGitRef,
   validateGhSlug,
+  validateGhEndpoint,
+  validateGhNumericId,
+  validatePrNum,
+  validateReviewId,
+  validateJobId,
   isValidGitWorktree,
   resolveMainBranch,
   run,

package/engine/spawn-agent.js

@@ -35,7 +35,7 @@
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
-const { runFile, cleanChildEnv, killGracefully, killImmediate, killByPidsImmediate, listProcessDescendants, ts, resolveEngineCacheDir } = require('./shared');
+const { runFile, cleanChildEnv, killGracefully, killImmediate, killByPidsImmediate, listProcessDescendants, ts, readFileNoFollow } = require('./shared');
 const { resolveRuntime } = require('./runtimes');
 const { acquireAdoTokenSync, isLikelyAdoToken } = require('./ado-token');
 const keepProcessSweep = require('./keep-process-sweep');
@@ -357,8 +357,13 @@ function main() {
     process.exit(78);
   }
 
-  const promptText = fs.readFileSync(promptFile, 'utf8');
-  const sysPromptText = fs.readFileSync(sysPromptFile, 'utf8');
+  // P-f6-tmp-toctou: read prompt/sysprompt with O_NOFOLLOW on POSIX so a
+  // sibling agent that planted a symlink at the prompt path cannot redirect
+  // our read to an attacker-controlled file. Windows: fs.constants.O_NOFOLLOW
+  // is undefined → the bitwise-or is a no-op and the open still succeeds
+  // (Windows non-junction reads don't follow symlinks the same way POSIX does).
+  const promptText = readFileNoFollow(promptFile, 'utf8');
+  const sysPromptText = readFileNoFollow(sysPromptFile, 'utf8');
 
   // Sys prompt tmp file — only when (a) NOT resuming and (b) the adapter
   // accepts a system prompt as a separate file. For runtimes that bake the
@@ -397,8 +402,11 @@ function main() {
     opts, passthrough, addDirs,
   });
 
-  // Debug log (async — not on critical path).
-  const tmpDir = path.join(resolveEngineCacheDir(__dirname), 'tmp');
+  // Debug log (async — not on critical path). Lives inside the per-dispatch
+  // dir (path.dirname(promptFile)) so it inherits the unguessable parent
+  // (P-f6-tmp-toctou) instead of sharing engine/tmp/spawn-debug.log across all
+  // concurrent dispatches.
+  const tmpDir = path.dirname(promptFile);
   if (!fs.existsSync(tmpDir)) fs.mkdirSync(tmpDir, { recursive: true });
   const debugPath = path.join(tmpDir, 'spawn-debug.log');
   fs.writeFile(

package/engine/timeout.js

@@ -184,9 +184,11 @@ function isTrackedProcessAlive(procInfo) {
 // Read the on-disk PID for a dispatch ID, or null if missing/invalid. Shared by
 // `isOsPidAliveForDispatch` and the recycled-PID command-line cross-check below
 // so both paths agree on which integer PID to interrogate.
+// P-f6-tmp-toctou: walks both legacy flat layout (engine/tmp/pid-<safeId>.pid)
+// and the per-dispatch dir layout (engine/tmp/dispatch-<safeId>-*/pid-<safeId>.pid).
 function _readDispatchPid(itemId) {
-  const safeId = String(itemId || '').replace(/[:\\/*?"<>|]/g, '-');
-  const pidPath = path.join(ENGINE_DIR, 'tmp', `pid-${safeId}.pid`);
+  const pidPath = shared.findDispatchPidFile(itemId);
+  if (!pidPath) return null;
   let raw;
   try { raw = fs.readFileSync(pidPath, 'utf8'); }
   catch { return null; }