@yemi33/minions 0.1.1985 → 0.1.1986

package/engine/queries.js

@@ -1527,73 +1527,142 @@ function resetPrdInfoCache() {
 }
 
 // ── Project git status (current branch + dirty/detached) ──────────────────
-// Cached per resolved localPath with a 30s TTL so /api/status doesn't shell
-// out to git on every poll. Mirrors the cache shape used by getDiskVersion in
-// dashboard.js (TTL + cached map). All git invocations pipe stderr to suppress
-// the `fatal: not a git repository` noise on non-git project paths — same
-// requirement enforced for install/boot paths in
+// Cached per resolved localPath with a 5-minute TTL. `getProjectGitStatus` is
+// synchronous (returns the cached value or a pending placeholder) and NEVER
+// blocks the event loop — the actual git probes run asynchronously via
+// child_process.execFile and write back into the cache when they settle. This
+// is critical for /api/status responsiveness: under the previous synchronous
+// implementation, four projects × three git invocations was ~12 sync shell-outs
+// per slow-state rebuild, which on Windows + Defender real-time scanning could
+// block the event loop long enough to starve SSE heartbeats and drop the CC
+// drawer's "Dashboard connection lost". Mirrors the cache shape used by
+// getDiskVersion in dashboard.js (TTL + cached map). All git invocations pipe
+// stderr to suppress the `fatal: not a git repository` noise on non-git project
+// paths — same requirement enforced for install/boot paths in
 // test/unit/runtime-fleet-helpers.test.js:465.
+// Single map keyed by normalized localPath. Each entry holds `{ts, value, promise}`:
+//   ts:      last-settled timestamp (Date.now()), or 0 if never settled
+//   value:   last-settled status object (or PROJECT_GIT_STATUS_PENDING placeholder)
+//   promise: in-flight refresh Promise, or null when idle
+// Folding state + in-flight into one map keeps reads/writes atomic and removes
+// the second-Map sync hazard.
 const _projectGitStatusCache = new Map();
-const PROJECT_GIT_STATUS_TTL = 30000; // 30s
-
+const PROJECT_GIT_STATUS_TTL = 300000; // 5 minutes
+const PROJECT_GIT_STATUS_PENDING = Object.freeze({ gitBranch: null, gitDetached: false, gitDirty: false, gitState: 'pending' });
+const PROJECT_GIT_STATUS_MISSING = Object.freeze({ gitBranch: null, gitDetached: false, gitDirty: false, gitState: 'missing' });
+const PROJECT_GIT_STATUS_NON_GIT = Object.freeze({ gitBranch: null, gitDetached: false, gitDirty: false, gitState: 'non-git' });
+
+// Async git invocation. Promise-returning so getProjectGitStatus can fire
+// background refreshes without blocking the event loop. Pipes stderr to keep
+// `fatal: not a git repository` from leaking to the dashboard console.
 function _gitExec(localPath, args) {
-  const { execFileSync } = require('child_process');
-  return execFileSync('git', ['-C', localPath, ...args], {
-    encoding: 'utf8',
-    timeout: 10000,
-    windowsHide: true,
-    stdio: ['pipe', 'pipe', 'pipe'],
+  const { execFile } = require('child_process');
+  return new Promise((resolve, reject) => {
+    execFile('git', ['-C', localPath, ...args], {
+      encoding: 'utf8',
+      timeout: 10000,
+      windowsHide: true,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }, (err, stdout) => {
+      if (err) reject(err);
+      else resolve(stdout);
+    });
+  });
+}
+
+// Probe a single project. Returns the resolved status value. Used both by the
+// background refresh path inside getProjectGitStatus and by test code that
+// wants to drive a probe to completion deterministically.
+async function _probeProjectGitStatus(localPath) {
+  try {
+    if (!fs.existsSync(localPath)) return PROJECT_GIT_STATUS_MISSING;
+    let isRepo = false;
+    try {
+      const out = (await _gitExec(localPath, ['rev-parse', '--is-inside-work-tree'])).trim();
+      isRepo = out === 'true';
+    } catch { isRepo = false; }
+    if (!isRepo) return PROJECT_GIT_STATUS_NON_GIT;
+    let branch = null;
+    let detached = false;
+    try {
+      branch = (await _gitExec(localPath, ['rev-parse', '--abbrev-ref', 'HEAD'])).trim() || null;
+    } catch { branch = null; }
+    if (branch === 'HEAD') {
+      detached = true;
+      try { branch = (await _gitExec(localPath, ['rev-parse', '--short', 'HEAD'])).trim() || null; }
+      catch { branch = null; }
+    }
+    let dirty = false;
+    try {
+      const status = await _gitExec(localPath, ['status', '--porcelain', '--untracked-files=no']);
+      dirty = status.length > 0;
+    } catch { dirty = false; }
+    return { gitBranch: branch, gitDetached: detached, gitDirty: dirty, gitState: 'ok' };
+  } catch {
+    // Defensive — never let a git probe failure escape this helper.
+    return PROJECT_GIT_STATUS_MISSING;
+  }
+}
+
+function _scheduleProjectGitStatusRefresh(localPath, key) {
+  const existing = _projectGitStatusCache.get(key);
+  if (existing && existing.promise) return existing.promise;
+  const entry = existing || { ts: 0, value: PROJECT_GIT_STATUS_PENDING, promise: null };
+  entry.promise = _probeProjectGitStatus(localPath).then(value => {
+    entry.ts = Date.now();
+    entry.value = value;
+    entry.promise = null;
+    return value;
+  }, () => {
+    entry.promise = null;
+    return null;
   });
+  _projectGitStatusCache.set(key, entry);
+  return entry.promise;
 }
 
 function getProjectGitStatus(localPath) {
   const key = String(localPath || '').replace(/\\/g, '/');
-  if (!key) return { gitBranch: null, gitDetached: false, gitDirty: false, gitState: 'missing' };
+  if (!key) return PROJECT_GIT_STATUS_MISSING;
   const now = Date.now();
   const cached = _projectGitStatusCache.get(key);
-  if (cached && (now - cached.ts) < PROJECT_GIT_STATUS_TTL) return cached.value;
+  if (cached && cached.ts && (now - cached.ts) < PROJECT_GIT_STATUS_TTL) return cached.value;
+  // Cheap synchronous existsSync — short-circuits a path that just disappeared
+  // (project removed) without scheduling a useless git probe.
+  if (!fs.existsSync(localPath)) {
+    _projectGitStatusCache.set(key, { ts: now, value: PROJECT_GIT_STATUS_MISSING, promise: null });
+    return PROJECT_GIT_STATUS_MISSING;
+  }
+  // Stale or never-populated — kick off a background refresh and return the
+  // previous value (or pending placeholder on the very first call). The next
+  // /api/status response after the refresh settles will have fresh data.
+  _scheduleProjectGitStatusRefresh(localPath, key);
+  return cached ? cached.value : PROJECT_GIT_STATUS_PENDING;
+}
 
-  let value = { gitBranch: null, gitDetached: false, gitDirty: false, gitState: 'missing' };
-  try {
-    if (!fs.existsSync(localPath)) {
-      // missing — cache the negative result
-    } else {
-      let isRepo = false;
-      try {
-        const out = _gitExec(localPath, ['rev-parse', '--is-inside-work-tree']).trim();
-        isRepo = out === 'true';
-      } catch { isRepo = false; }
-      if (!isRepo) {
-        value = { gitBranch: null, gitDetached: false, gitDirty: false, gitState: 'non-git' };
-      } else {
-        let branch = null;
-        let detached = false;
-        try {
-          branch = _gitExec(localPath, ['rev-parse', '--abbrev-ref', 'HEAD']).trim() || null;
-        } catch { branch = null; }
-        if (branch === 'HEAD') {
-          detached = true;
-          try { branch = _gitExec(localPath, ['rev-parse', '--short', 'HEAD']).trim() || null; }
-          catch { branch = null; }
-        }
-        let dirty = false;
-        try {
-          const status = _gitExec(localPath, ['status', '--porcelain', '--untracked-files=no']);
-          dirty = status.length > 0;
-        } catch { dirty = false; }
-        value = { gitBranch: branch, gitDetached: detached, gitDirty: dirty, gitState: 'ok' };
-      }
-    }
-  } catch {
-    // Defensive — never let a git probe failure break /api/status
-    value = { gitBranch: null, gitDetached: false, gitDirty: false, gitState: 'missing' };
+// Force a refresh now and wait for completion. Called from engine boot to
+// pre-warm the cache for every configured project so the first /api/status
+// after restart already has data. Also used by tests to settle the async
+// probe deterministically.
+function warmProjectGitStatus(localPath) {
+  const key = String(localPath || '').replace(/\\/g, '/');
+  if (!key) return Promise.resolve();
+  return _scheduleProjectGitStatusRefresh(localPath, key);
+}
+
+// Wait for every in-flight probe to settle. Test helper.
+function _awaitPendingProjectGitStatusProbes() {
+  const promises = [];
+  for (const entry of _projectGitStatusCache.values()) {
+    if (entry && entry.promise) promises.push(entry.promise);
   }
-  _projectGitStatusCache.set(key, { ts: now, value });
-  return value;
+  return Promise.all(promises);
 }
 
 /** Reset project git-status cache — exported for testing */
-function resetProjectGitStatusCache() { _projectGitStatusCache.clear(); }
+function resetProjectGitStatusCache() {
+  _projectGitStatusCache.clear();
+}
 
 // ── Exports ─────────────────────────────────────────────────────────────────
 
@@ -1610,6 +1679,8 @@ module.exports = {
   resetProjectGitStatusCache,
   invalidateKnowledgeBaseCache,
   getProjectGitStatus,
+  warmProjectGitStatus,
+  _awaitPendingProjectGitStatusProbes,
 
   // Core state
   getConfig, getControl, getDispatch, getDispatchQueue, getDispatchCompletionReport, invalidateDispatchCache,

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,
@@ -1664,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) ──────────────────────────────────
@@ -4391,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,
@@ -4402,6 +4650,13 @@ module.exports = {
   safeWrite,
   mutateTextFileLocked,
   safeUnlink,
+  createDispatchTmpDir,
+  removeDispatchTmpDir,
+  validateDispatchTmpDir,
+  readFileNoFollow,
+  dispatchPidCandidates,
+  findDispatchPidFile,
+  forEachPidFile,
   resolveMinionsHome,
   saveMinionsRootPointer,
   neutralizeJsonBackupSidecar,
@@ -4436,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; }