@yemi33/minions 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.1.8 (2026-03-25)
+
+### Engine
+- engine.js
+- engine/cli.js
+- engine/preflight.js
+- engine/shared.js
+- engine/spawn-agent.js
+
+### Documentation
+- README.md
+- auto-discovery.md
+
+### Other
+- CLAUDE.md
+- bin/minions.js
+- config.template.json
+- test/unit.test.js
+
+## 0.1.7 (2026-03-24)
+
+### Documentation
+- README.md
+
 ## 0.1.6 (2026-03-24)
 
 ### Other

package/README.md

@@ -59,15 +59,15 @@ Upgrades now skip the interactive repo scan automatically. If you want to re-run
 
 **What's shown:** A summary of files updated, added, and preserved, plus a pointer to the changelog.
 
-### Migrating from legacy `squad`
+### Migrating from legacy installs
 
-If you previously used `squad`, run:
+If you previously used an older install layout, run:
 
 ```bash
 minions init --force
 ```
 
-`minions` will auto-detect legacy installs (`~/.squad`, `.squad-root`, and `SQUAD_HOME`), migrate state into `~/.minions`, rename legacy runtime markers (`.squad-version` → `.minions-version`), and record the action in `~/.minions/migration.log`.
+`minions` will auto-detect legacy runtime locations and markers, migrate state into `~/.minions`, normalize runtime marker names, and record the action in `~/.minions/migration.log`.
 
 ## Quick Start
 
@@ -473,7 +473,7 @@ Engine behavior is controlled via `config.json`. Key settings:
 {
   "engine": {
     "tickInterval": 60000,
-    "maxConcurrent": 3,
+    "maxConcurrent": 5,
     "agentTimeout": 18000000,
     "heartbeatTimeout": 300000,
     "maxTurns": 100,
@@ -487,7 +487,7 @@ Engine behavior is controlled via `config.json`. Key settings:
 | Setting | Default | Description |
 |---------|---------|-------------|
 | `tickInterval` | 60000 (1min) | Milliseconds between engine ticks |
-| `maxConcurrent` | 3 | Max agents running simultaneously |
+| `maxConcurrent` | 5 | Max agents running simultaneously |
 | `agentTimeout` | 18000000 (5h) | Max total agent runtime |
 | `heartbeatTimeout` | 300000 (5min) | Kill agents silent longer than this |
 | `maxTurns` | 100 | Max Claude CLI turns per agent session |

package/bin/minions.js

@@ -297,6 +297,13 @@ function init() {
     showChangelog(installedVersion);
   }
 
+  // Run preflight checks (warn only — don't block init)
+  try {
+    const { runPreflight, printPreflight } = require(path.join(MINIONS_HOME, 'engine', 'preflight'));
+    const { results } = runPreflight();
+    printPreflight(results, { label: 'Preflight checks' });
+  } catch {}
+
   // Auto-start on fresh install; force-upgrade restarts automatically.
   if (isUpgrade) {
     try { execSync(`node "${path.join(MINIONS_HOME, 'engine.js')}" stop`, { stdio: 'ignore', cwd: MINIONS_HOME }); } catch {}
@@ -315,7 +322,17 @@ function init() {
   });
   dashProc.unref();
   console.log(`  Dashboard started (PID: ${dashProc.pid})`);
-  console.log('  Dashboard: http://localhost:7331\n');
+  console.log('  Dashboard: http://localhost:7331');
+
+  // Next steps guidance
+  console.log(`
+  Next steps:
+    minions work "Explore the codebase"   Give your first task
+    minions status                         Check engine state
+    http://localhost:7331                  Open the dashboard
+    minions doctor                         Verify everything is working
+    minions --help                         See all commands
+`);
 }
 
 function copyDir(src, dest, excludeTop, alwaysUpdate, neverOverwrite, isUpgrade, actions, relPath = '') {
@@ -391,6 +408,16 @@ function showVersion() {
   } else {
     console.log('  Not installed yet. Run: minions init');
   }
+
+  // Check npm registry for latest version (best-effort, non-blocking)
+  try {
+    const latest = execSync('npm view @yemi33/minions version', { encoding: 'utf8', timeout: 5000, windowsHide: true }).trim();
+    if (latest && latest !== pkg) {
+      console.log(`\n  Latest on npm:     ${latest}`);
+      console.log('  To update: npm update -g @yemi33/minions && minions init --force');
+    }
+  } catch {} // offline or npm not available — skip silently
+
   console.log('');
 }
 
@@ -428,12 +455,14 @@ if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
     minions init [--skip-scan]       Bootstrap ~/.minions/ (first time)
     minions init --force             Upgrade engine code + add new files (auto-skip scan)
     minions version                  Show installed vs package version
+    minions doctor                   Check prerequisites and runtime health
     minions add <project-dir>        Link a project (interactive)
     minions remove <project-dir>     Unlink a project
     minions list                     List linked projects
 
   Engine:
-    minions start                    Start engine daemon
+    minions up                       Start engine + dashboard (use after reboot)
+    minions start                    Start engine daemon only
     minions stop                     Stop the engine
     minions status                   Show agents, projects, queue
     minions pause / resume           Pause/resume dispatching
@@ -455,6 +484,26 @@ if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
   showVersion();
 } else if (cmd === 'add' || cmd === 'remove' || cmd === 'list') {
   delegate('minions.js', [cmd, ...rest]);
+} else if (cmd === 'up' || cmd === 'restart') {
+  // Start both engine and dashboard — the go-to command after a reboot
+  ensureInstalled();
+  // Stop engine if running (ignore errors)
+  try { execSync(`node "${path.join(MINIONS_HOME, 'engine.js')}" stop`, { stdio: 'ignore', cwd: MINIONS_HOME }); } catch {}
+  const engineProc = spawn(process.execPath, [path.join(MINIONS_HOME, 'engine.js'), 'start'], {
+    cwd: MINIONS_HOME, stdio: 'ignore', detached: true, windowsHide: true
+  });
+  engineProc.unref();
+  console.log(`\n  Engine started (PID: ${engineProc.pid})`);
+  const dashProc = spawn(process.execPath, [path.join(MINIONS_HOME, 'dashboard.js')], {
+    cwd: MINIONS_HOME, stdio: 'ignore', detached: true, windowsHide: true
+  });
+  dashProc.unref();
+  console.log(`  Dashboard started (PID: ${dashProc.pid})`);
+  console.log('  Dashboard: http://localhost:7331\n');
+} else if (cmd === 'doctor') {
+  ensureInstalled();
+  const { doctor } = require(path.join(MINIONS_HOME, 'engine', 'preflight'));
+  doctor(MINIONS_HOME).then(ok => process.exit(ok ? 0 : 1));
 } else if (cmd === 'dash' || cmd === 'dashboard') {
   delegate('dashboard.js', rest);
 } else if (engineCmds.has(cmd)) {

package/config.template.json

@@ -1,28 +1,4 @@
 {
-  "projects": [
-    {
-      "name": "YOUR_PROJECT_NAME",
-      "localPath": "/path/to/your/project",
-      "repoHost": "ado",
-      "repositoryId": "YOUR_REPO_ID",
-      "adoOrg": "YOUR_ORG",
-      "adoProject": "YOUR_PROJECT",
-      "repoName": "YOUR_REPO_NAME",
-      "mainBranch": "main",
-      "prUrlBase": "",
-      "workSources": {
-        "pullRequests": {
-          "enabled": true,
-          "path": ".minions/pull-requests.json",
-          "cooldownMinutes": 30
-        },
-        "workItems": {
-          "enabled": true,
-          "path": ".minions/work-items.json",
-          "cooldownMinutes": 0
-        }
-      }
-    }
-  ]
+  "projects": []
 }
 

package/docs/auto-discovery.md

@@ -196,7 +196,7 @@ Discovered items land in `engine/dispatch.json`:
 Each tick, the engine checks available slots:
 
 ```
-slotsAvailable = maxConcurrent (3) - activeCount
+slotsAvailable = maxConcurrent (5) - activeCount
 ```
 
 It takes up to `slotsAvailable` items from pending and spawns them. Items are processed in discovery-priority order (fixes first, then reviews, then implements, then work-items).
@@ -378,7 +378,7 @@ All discovery behavior is controlled via `config.json`:
 {
   "engine": {
     "tickInterval": 60000,       // ms between ticks
-    "maxConcurrent": 3,          // max agents running at once
+    "maxConcurrent": 5,          // max agents running at once
     "agentTimeout": 18000000,     // 5 hours — kill hung processes
     "heartbeatTimeout": 300000,  // 5min — kill stale/silent agents
     "maxTurns": 100,             // max claude CLI turns per agent

package/engine/cli.js

@@ -40,18 +40,41 @@ function handleCommand(cmd, args) {
     console.log('  complete <id>    Mark dispatch as done');
     console.log('  cleanup           Clean temp files, worktrees, zombies');
     console.log('  mcp-sync         Sync MCP servers from ~/.claude.json');
+    console.log('  doctor           Check prerequisites and runtime health');
     process.exit(1);
   }
 }
 
 const commands = {
   start() {
+    // Run preflight checks (warn but don't block — engine may still be useful)
+    try {
+      const { runPreflight, printPreflight } = require('./preflight');
+      const { results } = runPreflight();
+      const hasFatal = results.some(r => r.ok === false);
+      if (hasFatal) {
+        printPreflight(results, { label: 'Preflight checks' });
+        console.log('  Some checks failed — agents may not work. Run `minions doctor` for details.\n');
+      }
+    } catch {}
+
     const e = engine();
     const control = getControl();
     if (control.state === 'running') {
       let alive = false;
       if (control.pid) {
-        try { process.kill(control.pid, 0); alive = true; } catch {}
+        try {
+          if (process.platform === 'win32') {
+            // On Windows, process.kill(pid, 0) can false-positive if the PID was recycled.
+            // Use tasklist and verify the process is actually node.
+            const { execSync } = require('child_process');
+            const out = execSync(`tasklist /FI "PID eq ${control.pid}" /NH`, { encoding: 'utf8', windowsHide: true, timeout: 3000 });
+            alive = out.includes(String(control.pid)) && out.toLowerCase().includes('node');
+          } else {
+            process.kill(control.pid, 0);
+            alive = true;
+          }
+        } catch {}
       }
       if (alive) {
         console.log(`Engine is already running (PID ${control.pid}).`);
@@ -283,7 +306,7 @@ const commands = {
 
     // Start tick loop
     setInterval(() => e.tick(), interval);
-    console.log(`Tick interval: ${interval / 1000}s | Max concurrent: ${config.engine?.maxConcurrent || 3}`);
+    console.log(`Tick interval: ${interval / 1000}s | Max concurrent: ${config.engine?.maxConcurrent || 5}`);
     console.log('Press Ctrl+C to stop');
   },
 
@@ -338,10 +361,52 @@ const commands = {
     const { getProjects } = require('./shared');
     const projects = getProjects(config);
 
+    // Version info
+    let version = '?';
+    try {
+      const vFile = path.join(MINIONS_DIR, '.minions-version');
+      version = fs.readFileSync(vFile, 'utf8').trim();
+    } catch {}
+
     console.log('\n=== Minions Engine ===\n');
-    console.log(`State: ${control.state}`);
-    console.log(`PID: ${control.pid || 'N/A'}`);
-    console.log(`Projects: ${projects.map(p => p.name || 'unnamed').join(', ')}`);
+    console.log(`Version: ${version}`);
+
+    // Engine state with liveness check
+    let engineAlive = false;
+    if (control.state === 'running' && control.pid) {
+      try {
+        if (process.platform === 'win32') {
+          const { execSync } = require('child_process');
+          const out = execSync(`tasklist /FI "PID eq ${control.pid}" /NH`, { encoding: 'utf8', windowsHide: true, timeout: 3000 });
+          engineAlive = out.includes(String(control.pid)) && out.toLowerCase().includes('node');
+        } else {
+          process.kill(control.pid, 0);
+          engineAlive = true;
+        }
+      } catch {}
+    }
+    if (control.state === 'running' && !engineAlive) {
+      console.log(`Engine: stale (PID ${control.pid} is dead) — run: minions start`);
+    } else {
+      console.log(`Engine: ${control.state} (PID ${control.pid || 'N/A'})`);
+    }
+
+    // Dashboard check
+    const http = require('http');
+    const dashCheck = new Promise(resolve => {
+      const req = http.get('http://localhost:7331/api/health', { timeout: 2000 }, () => resolve(true));
+      req.on('error', () => resolve(false));
+      req.on('timeout', () => { req.destroy(); resolve(false); });
+    });
+    dashCheck.then(dashUp => {
+      if (dashUp) console.log('Dashboard: running (http://localhost:7331)');
+      else console.log('Dashboard: not running — start with: minions dash');
+    }).catch(() => {});
+
+    // Projects with health
+    const healthyProjects = projects.filter(p => p.localPath && fs.existsSync(path.resolve(p.localPath)));
+    const missingProjects = projects.filter(p => !p.localPath || !fs.existsSync(path.resolve(p.localPath)));
+    console.log(`Projects: ${healthyProjects.length} linked${missingProjects.length ? ` (${missingProjects.length} path missing)` : ''}`);
     console.log('');
 
     console.log('Agents:');
@@ -727,6 +792,13 @@ const commands = {
     console.log('MCP servers are read directly from ~/.claude.json — no sync needed.');
   },
 
+  doctor() {
+    const { doctor } = require('./preflight');
+    doctor(MINIONS_DIR).then(ok => {
+      if (!ok) process.exit(1);
+    });
+  },
+
   discover() {
     const e = engine();
     const config = getConfig();

package/engine/preflight.js

@@ -0,0 +1,239 @@
+/**
+ * engine/preflight.js — Prerequisite and health checks for Minions.
+ * Used by `minions init`, `minions start`, and `minions doctor`.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+/**
+ * Resolve the Claude Code CLI binary path.
+ * Returns the path if found, null otherwise.
+ * Reuses the same search logic as spawn-agent.js.
+ */
+function findClaudeBinary() {
+  const searchPaths = [
+    path.join(process.env.npm_config_prefix || '', 'node_modules', '@anthropic-ai', 'claude-code', 'cli.js'),
+    path.join(process.env.APPDATA || '', 'npm', 'node_modules', '@anthropic-ai', 'claude-code', 'cli.js'),
+    '/usr/local/lib/node_modules/@anthropic-ai/claude-code/cli.js',
+    '/usr/lib/node_modules/@anthropic-ai/claude-code/cli.js',
+  ];
+  for (const p of searchPaths) {
+    if (p && fs.existsSync(p)) return p;
+  }
+  // Fallback: parse the shell wrapper
+  try {
+    const which = execSync('bash -c "which claude"', { encoding: 'utf8', windowsHide: true, timeout: 5000 }).trim();
+    const wrapper = execSync(`bash -c "cat '${which}'"`, { encoding: 'utf8', windowsHide: true, timeout: 5000 });
+    const m = wrapper.match(/node_modules\/@anthropic-ai\/claude-code\/cli\.js/);
+    if (m) {
+      const basedir = path.dirname(which.replace(/^\/c\//, 'C:/').replace(/\//g, path.sep));
+      const resolved = path.join(basedir, 'node_modules', '@anthropic-ai', 'claude-code', 'cli.js');
+      if (fs.existsSync(resolved)) return resolved;
+    }
+  } catch {}
+  return null;
+}
+
+/**
+ * Run prerequisite checks. Returns { passed, results } where results is an
+ * array of { name, ok, message } objects.
+ *
+ * Options:
+ *   - warnOnly: if true, missing items don't cause passed=false (for init)
+ *   - verbose: include extra detail in messages
+ */
+function runPreflight(opts = {}) {
+  const results = [];
+  let allOk = true;
+
+  // 1. Node.js version >= 18
+  const nodeVersion = process.versions.node;
+  const major = parseInt(nodeVersion.split('.')[0], 10);
+  if (major >= 18) {
+    results.push({ name: 'Node.js', ok: true, message: `v${nodeVersion}` });
+  } else {
+    results.push({ name: 'Node.js', ok: false, message: `v${nodeVersion} — requires >= 18. Upgrade at https://nodejs.org` });
+    allOk = false;
+  }
+
+  // 2. Git available
+  try {
+    const gitVersion = execSync('git --version', { encoding: 'utf8', windowsHide: true, timeout: 5000 }).trim();
+    results.push({ name: 'Git', ok: true, message: gitVersion.replace('git version ', 'v') });
+  } catch {
+    results.push({ name: 'Git', ok: false, message: 'not found — install from https://git-scm.com' });
+    allOk = false;
+  }
+
+  // 3. Claude Code CLI
+  const claudeBin = findClaudeBinary();
+  if (claudeBin) {
+    results.push({ name: 'Claude Code CLI', ok: true, message: path.basename(path.dirname(path.dirname(claudeBin))) });
+  } else {
+    results.push({ name: 'Claude Code CLI', ok: false, message: 'not found — install with: npm install -g @anthropic-ai/claude-code' });
+    allOk = false;
+  }
+
+  // 4. Anthropic API key or Claude Max (best-effort warning)
+  const hasApiKey = !!process.env.ANTHROPIC_API_KEY;
+  if (hasApiKey) {
+    results.push({ name: 'Anthropic auth', ok: true, message: 'ANTHROPIC_API_KEY set' });
+  } else {
+    // Not fatal — user may have Claude Max subscription
+    results.push({ name: 'Anthropic auth', ok: 'warn', message: 'ANTHROPIC_API_KEY not set — agents need an API key or Claude Max subscription' });
+  }
+
+  return { passed: allOk, results };
+}
+
+/**
+ * Print preflight results to console. Returns true if all critical checks passed.
+ */
+function printPreflight(results, { label = 'Preflight checks' } = {}) {
+  console.log(`\n  ${label}:\n`);
+  let allOk = true;
+  for (const r of results) {
+    const icon = r.ok === true ? '\u2713' : r.ok === 'warn' ? '!' : '\u2717';
+    const prefix = r.ok === true ? '  ' : r.ok === 'warn' ? '  ' : '  ';
+    console.log(`${prefix} ${icon} ${r.name}: ${r.message}`);
+    if (r.ok === false) allOk = false;
+  }
+  console.log('');
+  return allOk;
+}
+
+/**
+ * Run preflight and print results. Exits with code 1 if fatal checks fail
+ * and exitOnFail is true.
+ */
+function checkOrExit({ exitOnFail = false, label = 'Preflight checks' } = {}) {
+  const { passed, results } = runPreflight();
+  const ok = printPreflight(results, { label });
+  if (!ok && exitOnFail) {
+    console.error('  Fix the issues above before continuing.\n');
+    process.exit(1);
+  }
+  return ok;
+}
+
+/**
+ * Run extended doctor checks (preflight + runtime health).
+ * Requires minionsHome path for runtime checks.
+ */
+function doctor(minionsHome) {
+  const { passed, results } = runPreflight();
+
+  // Runtime checks
+  const runtimeResults = [];
+
+  // Check if minions is installed
+  const engineJs = path.join(minionsHome, 'engine.js');
+  if (fs.existsSync(engineJs)) {
+    runtimeResults.push({ name: 'Minions installed', ok: true, message: minionsHome });
+  } else {
+    runtimeResults.push({ name: 'Minions installed', ok: false, message: `not found at ${minionsHome} — run: minions init` });
+  }
+
+  // Check config.json
+  const configPath = path.join(minionsHome, 'config.json');
+  try {
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    const projects = config.projects || [];
+    const real = projects.filter(p => p.name && !p.name.startsWith('YOUR_'));
+    if (real.length > 0) {
+      runtimeResults.push({ name: 'Projects configured', ok: true, message: `${real.length} project(s)` });
+    } else {
+      runtimeResults.push({ name: 'Projects configured', ok: false, message: 'no projects — run: minions add <dir>' });
+    }
+
+    // Check project paths exist
+    for (const p of real) {
+      if (p.localPath && !fs.existsSync(p.localPath)) {
+        runtimeResults.push({ name: `Project "${p.name}"`, ok: false, message: `path not found: ${p.localPath}` });
+      }
+    }
+
+    // Check agents
+    const agents = config.agents || {};
+    if (Object.keys(agents).length > 0) {
+      runtimeResults.push({ name: 'Agents configured', ok: true, message: `${Object.keys(agents).length} agent(s)` });
+    } else {
+      runtimeResults.push({ name: 'Agents configured', ok: false, message: 'no agents in config.json' });
+    }
+  } catch {
+    runtimeResults.push({ name: 'Config', ok: false, message: `missing or invalid — run: minions init` });
+  }
+
+  // Check engine status
+  const controlPath = path.join(minionsHome, 'engine', 'control.json');
+  try {
+    const control = JSON.parse(fs.readFileSync(controlPath, 'utf8'));
+    if (control.state === 'running' && control.pid) {
+      let alive = false;
+      try {
+        if (process.platform === 'win32') {
+          const out = execSync(`tasklist /FI "PID eq ${control.pid}" /NH`, { encoding: 'utf8', windowsHide: true, timeout: 3000 });
+          alive = out.includes(String(control.pid)) && out.toLowerCase().includes('node');
+        } else {
+          process.kill(control.pid, 0);
+          alive = true;
+        }
+      } catch {}
+      runtimeResults.push({ name: 'Engine', ok: alive, message: alive ? `running (PID ${control.pid})` : `stale PID ${control.pid} — run: minions start` });
+    } else {
+      runtimeResults.push({ name: 'Engine', ok: 'warn', message: `${control.state || 'stopped'} — run: minions start` });
+    }
+  } catch {
+    runtimeResults.push({ name: 'Engine', ok: 'warn', message: 'not started — run: minions start' });
+  }
+
+  // Check dashboard (try HTTP)
+  const http = require('http');
+  const dashCheck = new Promise(resolve => {
+    const req = http.get('http://localhost:7331/api/health', { timeout: 2000 }, res => {
+      resolve({ name: 'Dashboard', ok: true, message: 'running on http://localhost:7331' });
+    });
+    req.on('error', () => resolve({ name: 'Dashboard', ok: 'warn', message: 'not reachable on :7331 — run: minions dash' }));
+    req.on('timeout', () => { req.destroy(); resolve({ name: 'Dashboard', ok: 'warn', message: 'not reachable on :7331 — run: minions dash' }); });
+  });
+
+  return dashCheck.then(dashResult => {
+    runtimeResults.push(dashResult);
+
+    // Check playbooks
+    const playbooksDir = path.join(minionsHome, 'playbooks');
+    const required = ['implement.md', 'review.md', 'fix.md'];
+    const missing = required.filter(f => !fs.existsSync(path.join(playbooksDir, f)));
+    if (missing.length === 0) {
+      runtimeResults.push({ name: 'Playbooks', ok: true, message: `${required.length} required playbooks present` });
+    } else {
+      runtimeResults.push({ name: 'Playbooks', ok: false, message: `missing: ${missing.join(', ')} — run: minions init --force` });
+    }
+
+    // Check port 7331 availability (only if dashboard isn't running)
+    if (dashResult.ok !== true) {
+      // Dashboard isn't running, port should be free
+      runtimeResults.push({ name: 'Port 7331', ok: 'warn', message: 'dashboard not running — port status unknown' });
+    }
+
+    // Print all
+    const allResults = [...results, ...runtimeResults];
+    const ok = printPreflight(allResults, { label: 'Minions Doctor' });
+
+    const criticalFails = allResults.filter(r => r.ok === false).length;
+    const warnings = allResults.filter(r => r.ok === 'warn').length;
+    if (criticalFails === 0 && warnings === 0) {
+      console.log('  All checks passed.\n');
+    } else if (criticalFails === 0) {
+      console.log(`  ${warnings} warning(s), no critical issues.\n`);
+    } else {
+      console.log(`  ${criticalFails} issue(s) to fix, ${warnings} warning(s).\n`);
+    }
+
+    return ok;
+  });
+}
+
+module.exports = { findClaudeBinary, runPreflight, printPreflight, checkOrExit, doctor };

package/engine/shared.js

@@ -231,7 +231,7 @@ function classifyInboxItem(name, content) {
 
 const ENGINE_DEFAULTS = {
   tickInterval: 60000,
-  maxConcurrent: 3,
+  maxConcurrent: 5,
   inboxConsolidateThreshold: 5,
   agentTimeout: 18000000,  // 5h
   heartbeatTimeout: 300000, // 5min

package/engine/spawn-agent.js

@@ -67,8 +67,10 @@ if (isResume) {
 }
 
 if (!claudeBin) {
-  fs.appendFileSync(debugPath, 'FATAL: Cannot find claude-code cli.js\n');
-  process.exit(1);
+  const msg = 'FATAL: Cannot find claude-code cli.js — install with: npm install -g @anthropic-ai/claude-code';
+  fs.appendFileSync(debugPath, msg + '\n');
+  console.error(msg);
+  process.exit(78); // 78 = configuration error (distinct from runtime failures)
 }
 
 // Check if --system-prompt-file is supported (cached to avoid spawning claude --help every call)

package/engine.js

@@ -942,6 +942,17 @@ function spawnAgent(dispatchItem, config) {
     safeWrite(archivePath, outputContent);
     safeWrite(latestPath, outputContent); // overwrite latest for dashboard compat
 
+    // Detect configuration errors (e.g. Claude CLI not found) — fail immediately with clear message
+    if (code === 78) {
+      const errMsg = stderr.includes('claude-code') ? stderr.trim() : 'Configuration error — Claude Code CLI not found. Install with: npm install -g @anthropic-ai/claude-code';
+      log('error', `Agent ${agentId} (${id}) failed: ${errMsg}`);
+      completeDispatch(id, 'error', errMsg, '');
+      try { fs.unlinkSync(sysPromptPath); } catch {}
+      try { fs.unlinkSync(promptPath); } catch {}
+      try { fs.unlinkSync(promptPath.replace(/prompt-/, 'pid-').replace(/\.md$/, '.pid')); } catch {}
+      return;
+    }
+
     // Parse output and run all post-completion hooks
     const { resultSummary } = runPostCompletionHooks(dispatchItem, agentId, code, stdout, config);
 
@@ -1186,7 +1197,7 @@ function areDependenciesMet(item, config) {
       return false;
     }
     if (depItem.status === 'failed') return 'failed';
-    if (depItem.status !== 'done' && depItem.status !== 'in-pr') return false; // Pending, dispatched, or retrying — wait (in-pr accepted for backward compat)
+    if (!PRD_MET_STATUSES.has(depItem.status)) return false; // Pending, dispatched, or retrying — wait (legacy aliases accepted)
   }
   return true;
 }
@@ -1893,7 +1904,7 @@ function saveCooldowns() {
 function isOnCooldown(key, cooldownMs) {
   const entry = dispatchCooldowns.get(key);
   if (!entry) return false;
-  const backoff = Math.min(Math.pow(2, entry.failures || 0), 2);
+  const backoff = Math.min(Math.pow(2, entry.failures || 0), 8);
   return (Date.now() - entry.timestamp) < (cooldownMs * backoff);
 }
 
@@ -1908,7 +1919,7 @@ function setCooldownFailure(key) {
   const failures = (existing?.failures || 0) + 1;
   dispatchCooldowns.set(key, { timestamp: Date.now(), failures });
   if (failures >= 3) {
-    log('warn', `${key} has failed ${failures} times — cooldown is now ${Math.min(Math.pow(2, failures), 2)}x`);
+    log('warn', `${key} has failed ${failures} times — cooldown is now ${Math.min(Math.pow(2, failures), 8)}x`);
   }
   saveCooldowns();
 }
@@ -3158,7 +3169,7 @@ async function tickInner() {
   // 5. Process pending dispatches — auto-spawn agents
   const dispatch = getDispatch();
   const activeCount = (dispatch.active || []).length;
-  const maxConcurrent = config.engine?.maxConcurrent || 3;
+  const maxConcurrent = config.engine?.maxConcurrent || 5;
 
   if (activeCount >= maxConcurrent) {
     log('info', `At max concurrency (${activeCount}/${maxConcurrent}) — skipping dispatch`);

package/package.json

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