@yemi33/minions 0.1.1909 → 0.1.1911

package/README.md

@@ -15,6 +15,8 @@ Inspired by and initially scaffolded from [Brady Gaster's Squad](https://bradyga
 - **Anthropic API key** or Claude Max subscription (agents spawn Claude Code sessions)
 - **Git** — agents create worktrees for all code changes
 
+> **Note:** you do **not** need to configure your CLI for "autopilot" / "bypass permissions" / "dangerous mode". Minions passes the right bypass flag per spawn (`--dangerously-skip-permissions` for Claude; `--autopilot --allow-all --no-ask-user` for Copilot), independent of your global CLI config. Run `minions doctor` to verify your installed CLI accepts those flags.
+
 ## Installation
 
 ```bash

package/engine/cc-worker-pool.js

@@ -0,0 +1,512 @@
+/**
+ * engine/cc-worker-pool.js — Persistent per-tab Copilot worker pool (W-mp3ioyh300056f36).
+ *
+ * Sub-task B of W-mp2w003600196c51 ("CC perf: persistent per-tab Copilot
+ * worker"). Wraps `copilot --acp` (Agent Client Protocol — long-lived JSON-RPC
+ * server over stdin/stdout) so that a Command Center / doc-chat tab keeps a
+ * single warm Copilot process across N turns instead of paying the
+ * spawn + initialize + session/new (~14 s) cost on every turn.
+ *
+ * Public API:
+ *
+ *   pool.getSession({ tabId, model, effort, mcpServers, systemPromptHash, cwd })
+ *     → SessionHandle: {
+ *         sessionId,
+ *         stream(promptText, { onChunk, onDone, onError, signal, systemPromptText }) → Promise,
+ *         cancel(),                  // session/cancel notification
+ *         close(),                   // tear down this tab
+ *       }
+ *   pool.closeTab(tabId)             // cancel inflight, kill proc, drop entry
+ *   pool.shutdown()                  // close every tab and stop the idle reaper
+ *
+ * Internal model (one process per tab):
+ *
+ *   tabs: Map<tabId, Worker> where Worker = {
+ *     proc, sessionId, model, effort, mcpServers, mcpServersHash,
+ *     systemPromptHash, cwd, lastUsedAt,
+ *     pending: Map<id, { resolve, reject }>, inflight, readBuf, nextReqId
+ *   }
+ *
+ *   TODO (sub-task C/D follow-up): multiplex N tabs onto one ACP process
+ *   (`session/new` per tab, single `proc`). ACP supports it; left as a
+ *   follow-up perf win once one-process-per-tab is proven in the dashboard.
+ *
+ * Eviction rules:
+ *   - mcpServers changes      → kill proc entirely + respawn
+ *   - systemPromptHash change → keep proc, send a fresh `session/new`
+ *   - model / effort change   → no eviction (state updated in place)
+ *   - closeTab                → `session/cancel` if inflight, then kill proc
+ *   - Idle > 10 min           → kill proc (reaper sweep every 60 s)
+ *
+ * Auth precheck: when `copilot --acp` exits before the initialize handshake
+ * completes, surface
+ *   "copilot --acp failed -- ensure copilot CLI >=1.0.46 and copilot login
+ *    is complete (...)"
+ * so the dashboard can surface a precise reason instead of a generic timeout.
+ *
+ * No new npm deps — Node built-ins only (child_process, events, timers, crypto).
+ *
+ * See `notes/archive/2026-05-13-ripley-W-mp3h2wq2000e64f7-2026-05-13-0301.md`
+ * for the ACP protocol probe (line framing, request/response correlation,
+ * cold-vs-warm timings, cancel semantics, configOptions surface).
+ */
+
+const { spawn } = require('child_process');
+const crypto = require('crypto');
+
+// 10 minutes — matches the work-item spec.
+const IDLE_REAPER_MS = 10 * 60 * 1000;
+// Reaper sweep cadence. Not exposed as ENGINE_DEFAULTS to keep the pool
+// dependency-free; sub-task C/D can plumb a config knob if needed.
+const REAPER_INTERVAL_MS = 60 * 1000;
+
+// Test seam — every external side effect goes through `_internals` so
+// test/unit/cc-worker-pool.test.js can stub spawn/now/killImmediate.
+const _internals = {
+  spawnAcp({ cwd } = {}) {
+    return spawn(
+      'copilot',
+      ['--acp', '--allow-all', '--max-autopilot-continues', '1'],
+      {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        cwd: cwd || process.cwd(),
+        windowsHide: true,
+        // Don't pass shell:true — Copilot is a binary on PATH and a shell
+        // wrapper would swallow stdin/stdout framing.
+      }
+    );
+  },
+  killImmediate(proc) {
+    // Lazy require so unit tests that don't load engine/shared still work.
+    try {
+      const shared = require('./shared');
+      shared.killImmediate(proc);
+    } catch {
+      try { proc.kill('SIGKILL'); } catch { /* already dead */ }
+    }
+  },
+  now() { return Date.now(); },
+};
+
+const _tabs = new Map();
+let _reaperTimer = null;
+
+function _hashMcpServers(mcpServers) {
+  // Stable hash via JSON.stringify; mcpServers is an array of plain objects
+  // in practice (name/command/env) so the natural key order is fine.
+  const json = mcpServers == null ? '[]' : JSON.stringify(mcpServers);
+  return crypto.createHash('sha256').update(json).digest('hex');
+}
+
+class Worker {
+  constructor({ tabId, model, effort, mcpServers, mcpServersHash, systemPromptHash, cwd }) {
+    this.tabId = tabId;
+    this.model = model;
+    this.effort = effort;
+    this.mcpServers = mcpServers || [];
+    this.mcpServersHash = mcpServersHash;
+    this.systemPromptHash = systemPromptHash;
+    this.cwd = cwd || process.cwd();
+
+    this.proc = null;
+    this.sessionId = null;
+    this.pending = new Map();      // id → { resolve, reject }
+    this.inflight = null;          // current { id, sessionId, onChunk, onDone, onError, signal, signalHandler, settled }
+    this.readBuf = '';
+    this.nextReqId = 1;
+    this.lastUsedAt = _internals.now();
+    this.killed = false;
+    this.spawnError = null;
+    this.firstSystemPromptSent = false;
+  }
+
+  // ── Spawn + initialize handshake ────────────────────────────────────────
+  async _spawnAndInit() {
+    let proc;
+    try {
+      proc = _internals.spawnAcp({ cwd: this.cwd });
+    } catch (err) {
+      throw new Error(
+        `copilot --acp failed -- ensure copilot CLI >=1.0.46 and copilot login is complete (${err.message})`
+      );
+    }
+    this.proc = proc;
+
+    proc.stdout.on('data', (chunk) => this._onStdout(chunk));
+    // stderr is captured for diagnostics but we don't act on it.
+    if (proc.stderr) proc.stderr.on('data', () => { /* ignore */ });
+
+    // Race the init handshake against an early process exit so an auth
+    // failure (which kills the daemon before initialize completes) surfaces
+    // a clear error instead of hanging forever.
+    let earlyExitReject;
+    const earlyExitPromise = new Promise((_, reject) => {
+      earlyExitReject = (code) => {
+        this.killed = true;
+        const err = new Error(
+          `copilot --acp failed -- ensure copilot CLI >=1.0.46 and copilot login is complete (exit ${code})`
+        );
+        this.spawnError = err;
+        this._failAllPending(err);
+        reject(err);
+      };
+    });
+    const earlyExitHandler = (code) => earlyExitReject(code);
+    proc.once('exit', earlyExitHandler);
+
+    const errorHandler = (err) => {
+      const wrapped = new Error(
+        `copilot --acp failed -- ensure copilot CLI >=1.0.46 and copilot login is complete (${err.message})`
+      );
+      this.spawnError = wrapped;
+      this.killed = true;
+      this._failAllPending(wrapped);
+    };
+    proc.on('error', errorHandler);
+
+    try {
+      await Promise.race([
+        this._call('initialize', { protocolVersion: 1, clientCapabilities: {} }),
+        earlyExitPromise,
+      ]);
+      const result = await Promise.race([
+        this._call('session/new', { cwd: this.cwd, mcpServers: this.mcpServers }),
+        earlyExitPromise,
+      ]);
+      this.sessionId = result && result.sessionId;
+      if (!this.sessionId) {
+        throw new Error('copilot --acp failed -- session/new returned no sessionId');
+      }
+    } finally {
+      // Either the handshake finished (swap to a persistent exit handler that
+      // just marks killed) or it failed (proc is dying anyway).
+      proc.removeListener('exit', earlyExitHandler);
+    }
+    proc.on('exit', () => {
+      this.killed = true;
+      const err = new Error('copilot --acp process exited');
+      this._failAllPending(err);
+      // Settle inflight too if it's still hanging
+      if (this.inflight && !this.inflight.settled) {
+        const cb = this.inflight.onError;
+        this.inflight.settled = true;
+        this.inflight = null;
+        if (cb) try { cb(err); } catch { /* swallow */ }
+      }
+    });
+  }
+
+  _failAllPending(err) {
+    for (const { reject } of this.pending.values()) {
+      try { reject(err); } catch { /* swallow */ }
+    }
+    this.pending.clear();
+  }
+
+  // ── Newline-delimited JSON-RPC line framing ────────────────────────────
+  _onStdout(chunk) {
+    this.readBuf += chunk.toString('utf8');
+    let i;
+    while ((i = this.readBuf.indexOf('\n')) >= 0) {
+      const line = this.readBuf.slice(0, i).trim();
+      this.readBuf = this.readBuf.slice(i + 1);
+      if (!line) continue;
+      let obj;
+      try { obj = JSON.parse(line); } catch { continue; }
+      this._handleMessage(obj);
+    }
+  }
+
+  _handleMessage(obj) {
+    // Response (matches an outbound id)
+    if (obj.id != null && this.pending.has(obj.id)) {
+      const { resolve, reject } = this.pending.get(obj.id);
+      this.pending.delete(obj.id);
+      if (obj.error) reject(new Error(obj.error.message || 'ACP error'));
+      else resolve(obj.result);
+      return;
+    }
+    // Notification (no id) — only `session/update` matters for streaming.
+    if (obj.method === 'session/update' && obj.params && this.inflight) {
+      if (obj.params.sessionId !== this.inflight.sessionId) return;
+      const update = obj.params.update;
+      if (!update) return;
+      if (update.sessionUpdate === 'agent_message_chunk') {
+        const text = _extractChunkText(update.content);
+        if (text && this.inflight.onChunk) {
+          try { this.inflight.onChunk(text); } catch { /* swallow */ }
+        }
+      }
+      // Other update kinds (available_commands_update, tool_call, ...) are
+      // ignored in sub-task B. Sub-task C/D will surface tool_call to the
+      // dashboard's onToolUse callback.
+    }
+  }
+
+  _writeFrame(obj) {
+    if (this.killed) return;
+    if (!this.proc || !this.proc.stdin || this.proc.stdin.destroyed) return;
+    try { this.proc.stdin.write(JSON.stringify(obj) + '\n'); }
+    catch { /* pipe may be broken; exit handler will fire */ }
+  }
+
+  _call(method, params) {
+    return new Promise((resolve, reject) => {
+      const id = this.nextReqId++;
+      this.pending.set(id, { resolve, reject });
+      this._writeFrame({ jsonrpc: '2.0', id, method, params });
+    });
+  }
+
+  _notify(method, params) {
+    this._writeFrame({ jsonrpc: '2.0', method, params });
+  }
+
+  // ── Stream a single turn ───────────────────────────────────────────────
+  stream(promptText, opts = {}) {
+    const { onChunk, onDone, onError, signal, systemPromptText } = opts;
+    if (this.killed) {
+      const err = new Error('cc-worker-pool: tab is closed');
+      if (onError) try { onError(err); } catch { /* swallow */ }
+      return Promise.resolve();
+    }
+    if (this.inflight) {
+      const err = new Error('cc-worker-pool: a prompt is already in flight on this tab');
+      if (onError) try { onError(err); } catch { /* swallow */ }
+      return Promise.resolve();
+    }
+    this.lastUsedAt = _internals.now();
+
+    // Inject the <system> block on the first prompt of a session — Copilot
+    // ACP has no in-protocol "set system prompt" method (per Ripley's note),
+    // so the per-session adapter pattern of <system>...</system> prepended
+    // to the first user message remains correct.
+    let prompt = promptText;
+    if (!this.firstSystemPromptSent && systemPromptText) {
+      prompt = `<system>\n${systemPromptText}\n</system>\n\n${promptText}`;
+    }
+    this.firstSystemPromptSent = true;
+
+    const id = this.nextReqId++;
+    const inflight = {
+      id,
+      sessionId: this.sessionId,
+      onChunk,
+      onDone,
+      onError,
+      signal,
+      signalHandler: null,
+      settled: false,
+    };
+    this.inflight = inflight;
+
+    if (signal && typeof signal.addEventListener === 'function') {
+      inflight.signalHandler = () => this.cancel();
+      try { signal.addEventListener('abort', inflight.signalHandler); } catch { /* swallow */ }
+    }
+
+    return new Promise((resolve) => {
+      const finalize = (err, result) => {
+        if (inflight.settled) return;
+        inflight.settled = true;
+        if (this.inflight === inflight) this.inflight = null;
+        this.lastUsedAt = _internals.now();
+        if (signal && inflight.signalHandler) {
+          try { signal.removeEventListener('abort', inflight.signalHandler); }
+          catch { /* swallow */ }
+        }
+        if (err) {
+          if (onError) try { onError(err); } catch { /* swallow */ }
+        } else {
+          if (onDone) try { onDone(result); } catch { /* swallow */ }
+        }
+        resolve();
+      };
+
+      this.pending.set(id, {
+        resolve: (result) => finalize(null, result),
+        reject: (err) => finalize(err, null),
+      });
+      this._writeFrame({
+        jsonrpc: '2.0',
+        id,
+        method: 'session/prompt',
+        params: { sessionId: this.sessionId, prompt: [{ type: 'text', text: prompt }] },
+      });
+    });
+  }
+
+  cancel() {
+    if (!this.inflight || this.killed) return;
+    // session/cancel is a JSON-RPC notification (no id). The in-flight
+    // session/prompt response will arrive with stopReason=cancelled per the
+    // ACP spec — we don't synthesize a fake response client-side.
+    this._notify('session/cancel', { sessionId: this.inflight.sessionId });
+  }
+
+  async newSession({ mcpServers, systemPromptHash }) {
+    // Cancel any inflight before swapping the underlying session.
+    if (this.inflight) {
+      this.cancel();
+      // Wait briefly for the cancelled response to settle so we don't leak
+      // a stale inflight reference into the new session.
+      const inflight = this.inflight;
+      await new Promise((resolve) => {
+        const start = _internals.now();
+        const wait = () => {
+          if (!inflight || inflight.settled || _internals.now() - start > 1000) resolve();
+          else setTimeout(wait, 5);
+        };
+        wait();
+      });
+    }
+    const result = await this._call('session/new', {
+      cwd: this.cwd,
+      mcpServers: mcpServers || [],
+    });
+    this.sessionId = result && result.sessionId;
+    this.systemPromptHash = systemPromptHash;
+    this.firstSystemPromptSent = false;
+  }
+
+  close() {
+    if (this.killed) return;
+    this.killed = true;
+    // Best-effort cancel of an inflight prompt so the daemon doesn't keep
+    // generating into a torn-down session before we kill the proc.
+    if (this.inflight) {
+      try { this._notify('session/cancel', { sessionId: this.inflight.sessionId }); }
+      catch { /* swallow */ }
+    }
+    if (this.proc) {
+      try { _internals.killImmediate(this.proc); } catch { /* already dead */ }
+    }
+    this._failAllPending(new Error('cc-worker-pool: worker closed'));
+    if (this.inflight && !this.inflight.settled) {
+      const cb = this.inflight.onError;
+      this.inflight.settled = true;
+      this.inflight = null;
+      if (cb) try { cb(new Error('cc-worker-pool: worker closed')); } catch { /* swallow */ }
+    }
+  }
+}
+
+function _extractChunkText(content) {
+  if (content == null) return '';
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    let out = '';
+    for (const block of content) {
+      if (block && typeof block.text === 'string') out += block.text;
+    }
+    return out;
+  }
+  if (typeof content === 'object' && typeof content.text === 'string') return content.text;
+  return '';
+}
+
+// ── Public API ────────────────────────────────────────────────────────────
+
+async function getSession({ tabId, model, effort, mcpServers, systemPromptHash, cwd } = {}) {
+  if (!tabId) throw new Error('cc-worker-pool.getSession: tabId is required');
+  const mcpServersHash = _hashMcpServers(mcpServers);
+  let worker = _tabs.get(tabId);
+
+  if (worker) {
+    if (worker.killed) {
+      _tabs.delete(tabId);
+      worker = null;
+    } else if (worker.mcpServersHash !== mcpServersHash) {
+      // mcpServers shape changed → must respawn the proc; the daemon
+      // resolves MCP server config at process boot, not per session.
+      _tabs.delete(tabId);
+      worker.close();
+      worker = null;
+    } else if (worker.systemPromptHash !== systemPromptHash) {
+      // System prompt changed → keep the warm process, drop the session
+      // and create a fresh one. Saves the ~2.1 s initialize handshake.
+      await worker.newSession({ mcpServers, systemPromptHash });
+      worker.model = model;
+      worker.effort = effort;
+      worker.lastUsedAt = _internals.now();
+    } else {
+      // Warm reuse — only update bookkeeping. model/effort changes on a
+      // warm session are tracked here but not pushed via configOptions in
+      // sub-task B; sub-task C/D will wire that to ACP `session/configure`
+      // (or equivalent) once the dashboard exposes the toggle live.
+      worker.model = model;
+      worker.effort = effort;
+      worker.lastUsedAt = _internals.now();
+    }
+  }
+
+  if (!worker) {
+    worker = new Worker({
+      tabId, model, effort, mcpServers, mcpServersHash, systemPromptHash, cwd,
+    });
+    _tabs.set(tabId, worker);
+    try {
+      await worker._spawnAndInit();
+    } catch (err) {
+      _tabs.delete(tabId);
+      try { worker.close(); } catch { /* already torn down */ }
+      throw err;
+    }
+  }
+
+  _ensureReaper();
+
+  return {
+    sessionId: worker.sessionId,
+    stream: (promptText, opts) => worker.stream(promptText, opts),
+    cancel: () => worker.cancel(),
+    close: () => closeTab(tabId),
+  };
+}
+
+function closeTab(tabId) {
+  const worker = _tabs.get(tabId);
+  if (!worker) return;
+  _tabs.delete(tabId);
+  worker.close();
+}
+
+function shutdown() {
+  for (const worker of _tabs.values()) {
+    try { worker.close(); } catch { /* swallow */ }
+  }
+  _tabs.clear();
+  if (_reaperTimer) {
+    clearInterval(_reaperTimer);
+    _reaperTimer = null;
+  }
+}
+
+function _ensureReaper() {
+  if (_reaperTimer) return;
+  _reaperTimer = setInterval(_reapIdleTabs, REAPER_INTERVAL_MS);
+  if (typeof _reaperTimer.unref === 'function') _reaperTimer.unref();
+}
+
+function _reapIdleTabs() {
+  const now = _internals.now();
+  for (const [tabId, worker] of [..._tabs]) {
+    if (worker.inflight) continue;
+    if (now - worker.lastUsedAt > IDLE_REAPER_MS) {
+      _tabs.delete(tabId);
+      try { worker.close(); } catch { /* already torn down */ }
+    }
+  }
+}
+
+module.exports = {
+  getSession,
+  closeTab,
+  shutdown,
+  // Exposed for unit tests; engine code MUST go through the public API.
+  _internals,
+  _tabs,
+  _reapIdleTabs,
+  IDLE_REAPER_MS,
+  REAPER_INTERVAL_MS,
+};

package/engine/preflight.js

@@ -10,7 +10,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { execSync } = require('child_process');
+const { execSync, execFileSync } = require('child_process');
 
 /**
  * Resolve the Claude Code CLI binary path. Legacy helper preserved for back-
@@ -421,6 +421,115 @@ async function _modelDiscoveryResults(config) {
   return results;
 }
 
+/**
+ * Spawn `<resolved.bin> --help` and return the combined stdout/stderr, or null
+ * if the binary couldn't be invoked at all. Used only by the bypass-flag check
+ * in `_bypassFlagResults`; never on the hot path of `runPreflight` because
+ * it adds a subprocess invocation per runtime.
+ *
+ * Many CLIs emit `--help` to stderr or return a non-zero code when invoked in
+ * a non-TTY context, so we tolerate both — `execFileSync` populates `stdout`
+ * and `stderr` on the thrown error and we read them back.
+ */
+function _fetchCliHelpText(resolved, { timeoutMs = 5000 } = {}) {
+  if (!resolved || !resolved.bin) return null;
+  const leading = Array.isArray(resolved.leadingArgs) ? resolved.leadingArgs : [];
+  let cmd;
+  let args;
+  if (resolved.native === false) {
+    // Node shim (e.g. claude/cli.js). Invoke via the current Node so we don't
+    // depend on a `node` on PATH and we honor the same execPath the engine
+    // uses for spawn-agent.
+    cmd = process.execPath;
+    args = [resolved.bin, ...leading, '--help'];
+  } else {
+    cmd = resolved.bin;
+    args = [...leading, '--help'];
+  }
+  try {
+    const out = execFileSync(cmd, args, {
+      encoding: 'utf8',
+      windowsHide: true,
+      timeout: timeoutMs,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return String(out || '');
+  } catch (e) {
+    const stdout = e && e.stdout ? String(e.stdout) : '';
+    const stderr = e && e.stderr ? String(e.stderr) : '';
+    const combined = stdout + stderr;
+    return combined.length > 0 ? combined : null;
+  }
+}
+
+/**
+ * Pure helper — takes the adapter and the help text and returns a doctor
+ * result entry. Splitting this from the spawn keeps the helper unit-testable
+ * without mocking `execFileSync`. The check is `warn`-level (not critical) so
+ * a false positive from a CLI that renames flags or paginates help doesn't
+ * block existing installs; the engine spawns will still error loudly if the
+ * flag really isn't honored.
+ */
+function _checkBypassFlagSupported(runtimeName, adapter, helpText) {
+  const name = `Permission bypass: ${runtimeName}`;
+  const flags = Array.isArray(adapter && adapter.permissionBypassFlags)
+    ? adapter.permissionBypassFlags.filter(f => typeof f === 'string' && f.length > 0)
+    : [];
+  if (flags.length === 0) {
+    return {
+      name,
+      ok: 'warn',
+      message: `adapter did not declare permissionBypassFlags — cannot verify ${runtimeName} CLI accepts headless bypass`,
+    };
+  }
+  if (helpText == null || helpText === '') {
+    return {
+      name,
+      ok: 'warn',
+      message: `could not invoke ${runtimeName} --help to verify ${flags.join(' ')} support — Minions will still pass the flag(s) but you may see permission prompts if the CLI doesn't accept them`,
+    };
+  }
+  const missing = flags.filter(f => !helpText.includes(f));
+  if (missing.length > 0) {
+    return {
+      name,
+      ok: 'warn',
+      message: `${runtimeName} --help does not list expected flag(s): ${missing.join(', ')} — your CLI may be outdated. Agents will hang on permission prompts. Update with the CLI's package manager (npm i -g @anthropic-ai/claude-code for Claude; winget upgrade Microsoft.CopilotCLI for Copilot)`,
+    };
+  }
+  return {
+    name,
+    ok: true,
+    message: `${flags.join(' ')} accepted`,
+  };
+}
+
+/**
+ * Build the per-runtime bypass-flag verification entries for `minions doctor`.
+ * One entry per distinct configured runtime. Skipped silently when the binary
+ * itself didn't resolve (the upstream `Runtime: <name>` check already surfaces
+ * that failure — no point shouting twice).
+ */
+function _bypassFlagResults(config) {
+  const results = [];
+  if (!config || typeof config !== 'object') return results;
+  let registry;
+  try { registry = require('./runtimes'); } catch { return results; }
+  const runtimes = _distinctRuntimes(config);
+  for (const runtimeName of runtimes) {
+    let adapter;
+    try { adapter = registry.resolveRuntime(runtimeName); }
+    catch { continue; }
+    let resolved = null;
+    try { resolved = adapter.resolveBinary({ env: process.env }); }
+    catch { /* upstream Runtime check already reported this */ }
+    if (!resolved || !resolved.bin) continue;
+    const helpText = _fetchCliHelpText(resolved);
+    results.push(_checkBypassFlagSupported(runtimeName, adapter, helpText));
+  }
+  return results;
+}
+
 /**
  * Run extended doctor checks (preflight + runtime health + fleet summary +
  * per-runtime model discovery).
@@ -552,6 +661,11 @@ function doctor(minionsHome) {
     runtimeResults.push(...fleetSummary);
     const modelResults = await _modelDiscoveryResults(preflightConfig);
     runtimeResults.push(...modelResults);
+    // Verify each runtime CLI still recognizes the headless bypass flags the
+    // adapters inject. Catches "user installed an outdated CLI" before the
+    // first agent silently hangs on a permission prompt.
+    const bypassResults = _bypassFlagResults(preflightConfig);
+    runtimeResults.push(...bypassResults);
 
     // Print all
     const allResults = [...results, ...runtimeResults];
@@ -584,4 +698,7 @@ module.exports = {
   _warmModelCache,
   _fleetSummaryResults,
   _modelDiscoveryResults,
+  _fetchCliHelpText,
+  _checkBypassFlagSupported,
+  _bypassFlagResults,
 };

package/engine/runtimes/claude.js

@@ -689,6 +689,14 @@ function createStreamConsumer(ctx) {
   return { consume, reset };
 }
 
+// ── Permission Bypass ───────────────────────────────────────────────────────
+//
+// Flags the engine relies on for headless operation. `preflight.doctor()`
+// shells out to `<bin> --help` and verifies each literal appears in the help
+// text — surfaces "your CLI is too old / has been renamed" before agents
+// silently hang on permission prompts. Must stay in sync with `buildArgs`.
+const PERMISSION_BYPASS_FLAGS = ['--dangerously-skip-permissions'];
+
 // ── Capability Block ────────────────────────────────────────────────────────
 
 const capabilities = {
@@ -806,6 +814,7 @@ module.exports = {
   parseStreamChunk,
   parseError,
   createStreamConsumer,
+  permissionBypassFlags: PERMISSION_BYPASS_FLAGS,
   // Exposed for unit tests — never imported by engine code
   _CLAUDE_SHORTHANDS,
   THINKING_BLOCK_TYPES,

package/engine/runtimes/copilot.js

@@ -1062,6 +1062,14 @@ function createStreamConsumer(ctx) {
   return { consume, reset };
 }
 
+// ── Permission Bypass ───────────────────────────────────────────────────────
+//
+// Flags the engine relies on for headless operation. `preflight.doctor()`
+// shells out to `<bin> --help` and verifies each literal appears in the help
+// text — surfaces "your CLI is too old / has been renamed" before agents
+// silently hang on permission prompts. Must stay in sync with `buildArgs`.
+const PERMISSION_BYPASS_FLAGS = ['--autopilot', '--allow-all', '--no-ask-user'];
+
 // ── Capability Block ────────────────────────────────────────────────────────
 
 const capabilities = {
@@ -1170,6 +1178,7 @@ module.exports = {
   parseStreamChunk,
   parseError,
   createStreamConsumer,
+  permissionBypassFlags: PERMISSION_BYPASS_FLAGS,
   // Exposed for unit tests — engine code MUST go through resolveRuntime + the
   // adapter contract; never reach into these helpers directly.
   _MINIONS_MODEL_ALIASES,

package/package.json

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