@yemi33/minions 0.1.1697 → 0.1.1699

package/CHANGELOG.md

@@ -1,9 +1,21 @@
 # Changelog
 
-## 0.1.1697 (2026-05-04)
+## 0.1.1699 (2026-05-04)
+
+### Features
+-  Gracefully handle missing runtime across Command Center and LLM call sites
+
+### Fixes
+- yemi33/minions#2022
+
+## 0.1.1698 (2026-05-04)
+
+### Features
+- fix update restart and Copilot steering (#2025)
+
+## 0.1.1696 (2026-05-04)
 
 ### Features
-- guard engine shutdown ownership (#2021)
 - preserve doc-chat final payload (#2019)
 
 ## 0.1.1695 (2026-05-04)

package/bin/minions.js

@@ -203,6 +203,7 @@ function resolveMinionsHome(forInit = false) {
 const [cmd, ...rest] = process.argv.slice(2);
 let force = rest.includes('--force');
 const skipScan = rest.includes('--skip-scan');
+const skipStart = rest.includes('--skip-start') || rest.includes('--no-start');
 const MINIONS_HOME = resolveMinionsHome(cmd === 'init');
 
 function isSubpath(parent, child) {
@@ -339,7 +340,12 @@ function init() {
     printPreflight(results, { label: 'Preflight checks' });
   } catch {}
 
-  // Auto-start on fresh install; force-upgrade restarts automatically.
+  if (isUpgrade && skipStart) {
+    console.log(`\n  Upgrade complete (${pkgVersion}). Restart skipped by caller.\n`);
+    return;
+  }
+
+  // Auto-start on fresh install; direct force-upgrade restarts automatically.
   if (isUpgrade) {
     try { execSync(`node "${path.join(MINIONS_HOME, 'engine.js')}" stop`, { stdio: 'ignore', cwd: MINIONS_HOME }); } catch {}
   }
@@ -436,7 +442,7 @@ function showVersion() {
   if (installed) {
     console.log(`  Installed version: ${installed}`);
     if (installed !== pkg) {
-      console.log('\n  Update available! Run: minions init --force');
+      console.log('\n  Update available! Run: minions update');
     } else {
       console.log('  Up to date.');
     }
@@ -449,7 +455,7 @@ function showVersion() {
     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');
+      console.log('  To update: minions update');
     }
   } catch {} // offline or npm not available — skip silently
 
@@ -489,7 +495,7 @@ if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
 
   Setup:
     minions init                     Bootstrap ~/.minions/ (first time)
-    minions update                   Update to latest version (npm update + init --force)
+    minions update                   Update to latest version (npm update + one restart)
     minions version                  Show installed vs package version
     minions doctor                   Check prerequisites and runtime health
     minions add <project-dir>        Link a project (interactive)
@@ -538,7 +544,7 @@ if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
       console.error('  npm update failed:', e.message);
       process.exit(1);
     }
-    execSync('minions init --force', { stdio: 'inherit', timeout: 120000 });
+    execSync('minions init --force --skip-start', { stdio: 'inherit', timeout: 120000 });
   }
   // Restart engine + dashboard so they pick up the new code
   console.log('\n  Restarting engine and dashboard...\n');
@@ -761,4 +767,3 @@ if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
   console.log('  Run "minions help" for usage.\n');
   process.exit(1);
 }
-

package/dashboard.js

@@ -226,6 +226,40 @@ function _agentSessionIsDraining(agentId) {
   return terminalIdx >= 0 && terminalIdx > lastSteer;
 }
 
+function _dispatchBranch(item) {
+  const branch = item?.meta?.branch || item?.branch || item?.meta?.item?.branch || item?.meta?.item?.featureBranch;
+  return branch ? String(branch).replace(/^refs\/heads\//, '') : null;
+}
+
+function _hasCachedResumeSession(agentId, activeDispatch, maxAgeMs = 2 * 60 * 60 * 1000) {
+  const sessionFile = safeJson(path.join(AGENTS_DIR, agentId, 'session.json'));
+  if (!sessionFile?.sessionId || !sessionFile.savedAt) return false;
+  const savedAtMs = new Date(sessionFile.savedAt).getTime();
+  if (!Number.isFinite(savedAtMs) || Date.now() - savedAtMs >= maxAgeMs) return false;
+  const dispatchBranch = _dispatchBranch(activeDispatch);
+  const sessionBranch = sessionFile.branch ? String(sessionFile.branch).replace(/^refs\/heads\//, '') : null;
+  return !!dispatchBranch && !!sessionBranch && dispatchBranch === sessionBranch;
+}
+
+function _steeringDeliveryState(agentId) {
+  const activeDispatch = (getDispatchQueue().active || []).find(d => d.agent === agentId);
+  if (!activeDispatch) return { deliveryStatus: 'queued', pendingDelivery: true };
+
+  const runtimeName = shared.resolveAgentCli(CONFIG.agents?.[agentId], CONFIG.engine);
+  try {
+    const runtime = require('./engine/runtimes').resolveRuntime(runtimeName);
+    if (runtime?.capabilities?.midRunSessionId === false && !_hasCachedResumeSession(agentId, activeDispatch)) {
+      return {
+        deliveryStatus: 'pending_checkpoint',
+        pendingDelivery: true,
+        detail: 'Runtime has not emitted a resumable session yet; delivery is pending until the next resumable checkpoint.',
+      };
+    }
+  } catch { /* unknown runtime: checkSteering will surface retry state */ }
+
+  return { deliveryStatus: 'queued', pendingDelivery: false };
+}
+
 const PLANS_DIR = path.join(MINIONS_DIR, 'plans');
 const TEAMS_INBOX_PATH = path.join(ENGINE_DIR, 'teams-inbox.json');
 
@@ -1791,6 +1825,7 @@ async function ccCall(message, { store = 'cc', sessionKey, extraContext, label =
     if (onAbortReady) onAbortReady(p1.abort);
     result = await p1;
     llm.trackEngineUsage(label, result.usage);
+    if (result.missingRuntime) return result;
 
     if (result.text) {
       updateSession(store, sessionKey, result.sessionId || sessionId, true);
@@ -1828,6 +1863,7 @@ async function ccCall(message, { store = 'cc', sessionKey, extraContext, label =
   if (onAbortReady) onAbortReady(p2.abort);
   result = await p2;
   llm.trackEngineUsage(label, result.usage);
+  if (result.missingRuntime) return result;
 
   if (result.text) {
     updateSession(store, sessionKey, result.sessionId, false);
@@ -1845,6 +1881,7 @@ async function ccCall(message, { store = 'cc', sessionKey, extraContext, label =
   if (onAbortReady) onAbortReady(p3.abort);
   result = await p3;
   llm.trackEngineUsage(label, result.usage);
+  if (result.missingRuntime) return result;
 
   if (result.text) {
     updateSession(store, sessionKey, result.sessionId, false);
@@ -1878,6 +1915,7 @@ async function ccCallStreaming(message, { store = 'cc', sessionKey, extraContext
     if (onAbortReady) onAbortReady(p1.abort);
     result = await p1;
     llm.trackEngineUsage(label, result.usage);
+    if (result.missingRuntime) return result;
 
     if (result.text) {
       updateSession(store, sessionKey, result.sessionId || sessionId, true);
@@ -1914,6 +1952,7 @@ async function ccCallStreaming(message, { store = 'cc', sessionKey, extraContext
   if (onAbortReady) onAbortReady(p2.abort);
   result = await p2;
   llm.trackEngineUsage(label, result.usage);
+  if (result.missingRuntime) return result;
 
   if (result.text) {
     updateSession(store, sessionKey, result.sessionId, false);
@@ -1932,6 +1971,7 @@ async function ccCallStreaming(message, { store = 'cc', sessionKey, extraContext
   if (onAbortReady) onAbortReady(p3.abort);
   result = await p3;
   llm.trackEngineUsage(label, result.usage);
+  if (result.missingRuntime) return result;
 
   if (result.text) {
     updateSession(store, sessionKey, result.sessionId, false);
@@ -2037,6 +2077,10 @@ async function ccDocCall({ message, document, title, filePath, selection, canEdi
     if (session) session._docHash = docHash;
   }
 
+  if (result.missingRuntime) {
+    return { answer: result.text || result.stderr || 'Minions runtime is not installed or configured.', content: null, actions: [] };
+  }
+
   if (result.code !== 0 || !result.text) {
     console.error(`[doc-chat] Failed: code=${result.code}, empty=${!result.text}, filePath=${filePath}, stderr=${(result.stderr || '').slice(0, 200)}`);
     return { answer: 'Failed to process request. Try again.', content: null, actions: [] };
@@ -2091,6 +2135,10 @@ async function ccDocCallStreaming({ message, document, title, filePath, selectio
     if (session) session._docHash = docHash;
   }
 
+  if (result.missingRuntime) {
+    return { answer: result.text || result.stderr || 'Minions runtime is not installed or configured.', content: null, actions: [] };
+  }
+
   if (result.code !== 0 || !result.text) {
     console.error(`[doc-chat-stream] Failed: code=${result.code}, empty=${!result.text}, filePath=${filePath}, stderr=${(result.stderr || '').slice(0, 200)}`);
     return { answer: 'Failed to process request. Try again.', content: null, actions: [] };
@@ -5020,6 +5068,13 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         _ccHeartbeatTimer = null;
       }
     };
+    const finishMissingRuntime = (result, liveState) => {
+      const text = result.text || result.stderr || 'Minions runtime is not installed or configured.';
+      liveState.donePayload = { type: 'done', text, actions: [], sessionId: null, missingRuntime: true };
+      if (liveState.writer) liveState.writer(liveState.donePayload);
+      if (liveState.endResponse) liveState.endResponse();
+      _scheduleCcLiveCleanup(tabId);
+    };
     try {
       const body = await readBody(req);
       if (!body.message && !body.reconnect) { res.statusCode = 400; res.end('message required'); return; }
@@ -5142,6 +5197,11 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         const result = await llmPromise;
         trackUsage('command-center', result.usage);
 
+        if (result.missingRuntime) {
+          finishMissingRuntime(result, liveState);
+          return;
+        }
+
         // Handle failure — non-zero exit with text = max_turns or partial success, still usable
         if (!result.text && wasResume && result.code !== 0 && !req.destroyed) {
           // Resume failed (stale/expired session) — auto-retry as fresh session (skip if client already disconnected)
@@ -5164,6 +5224,10 @@ What would you like to discuss or change? When you're happy, say "approve" and I
             Object.assign(result, retryResult);
           }
         }
+        if (result.missingRuntime) {
+          finishMissingRuntime(result, liveState);
+          return;
+        }
         if (!result.text) {
           if (req.destroyed) { _ccStreamEnded = true; return; } // client already gone — nothing to send
           const debugInfo = result.code !== 0 ? `(exit code ${result.code})` : '(empty response)';
@@ -5347,6 +5411,9 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         model: 'haiku', maxTurns: 1, timeout: 30000, label: 'schedule-parse', direct: true,
         engineConfig: CONFIG.engine,
       });
+      if (result.missingRuntime) {
+        return jsonReply(res, 503, { error: result.text || result.stderr || 'Minions runtime is not installed or configured.', missingRuntime: true });
+      }
       const parsed = JSON.parse(result.text.trim());
       if (!parsed.cron) return jsonReply(res, 422, { error: 'Could not parse schedule' });
       return jsonReply(res, 200, { cron: parsed.cron, description: parsed.description || '' });
@@ -6219,6 +6286,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       }
 
       const entry = steering.writeSteeringMessage(agentId, text);
+      const delivery = _steeringDeliveryState(agentId);
 
       // Also append to live-output.log so it shows in the chat view
       const liveLogPath = path.join(agentDir, 'live-output.log');
@@ -6226,7 +6294,8 @@ What would you like to discuss or change? When you're happy, say "approve" and I
 
       return jsonReply(res, 200, {
         ok: true,
-        message: 'Steering message queued',
+        message: delivery.pendingDelivery ? 'Steering message pending delivery' : 'Steering message queued',
+        ...delivery,
         file: entry?.file || null,
         inboxCount: steering.listUnreadSteeringMessages(agentId).length,
       });

package/engine/consolidation.js

@@ -201,6 +201,10 @@ function consolidateWithLLM(items, existingNotes, files, config) {
     if (_cleared) return;
     clearTimeout(timeoutHandle);
     trackEngineUsage('consolidation', result.usage);
+    if (result.missingRuntime) {
+      _fallback(`LLM consolidation skipped: ${result.text || result.stderr || 'runtime unavailable'} — falling back to regex`);
+      return;
+    }
 
     const extractedText = result.text || '';
     const rawText = result.raw || '';

package/engine/copilot-models.json

@@ -1,5 +1,5 @@
 {
   "runtime": "copilot",
   "models": null,
-  "cachedAt": "2026-05-04T06:13:46.106Z"
+  "cachedAt": "2026-05-04T06:56:12.183Z"
 }

package/engine/kb-sweep.js

@@ -135,6 +135,10 @@ If nothing to do: { "duplicates": [], "reclassify": [], "remove": [] }`;
         engineConfig: opts.engineConfig,
       });
       trackEngineUsage('kb-sweep', result.usage);
+      if (result.missingRuntime) {
+        log('warn', `[kb-sweep] batch ${b + 1} LLM skipped: ${result.text || result.stderr || 'runtime unavailable'}`);
+        continue;
+      }
     } catch (e) { log('warn', `[kb-sweep] batch ${b + 1} LLM error: ${e.message}`); continue; }
 
     let batchPlan;
@@ -212,6 +216,10 @@ ${body}`;
           engineConfig: opts.engineConfig,
         });
         trackEngineUsage('kb-sweep', result.usage);
+        if (result.missingRuntime) {
+          log('warn', `[kb-sweep] rewrite ${c.entry.category}/${c.entry.file} skipped: ${result.text || result.stderr || 'runtime unavailable'}`);
+          continue;
+        }
         let newBody = (result.text || '').trim();
         // Strip accidental code fence
         const fence = newBody.match(/^```(?:markdown|md)?\s*([\s\S]*?)```$/);

package/engine/llm.js

@@ -23,6 +23,7 @@ const { resolveRuntime } = require('./runtimes');
 const MINIONS_DIR = shared.MINIONS_DIR;
 const ENGINE_DIR = path.join(MINIONS_DIR, 'engine');
 const COPILOT_TASK_COMPLETE_GRACE_MS = 3000;
+const MISSING_RUNTIME_EXIT_CODE = 78;
 
 // ─── Engine-Usage Metrics ────────────────────────────────────────────────────
 
@@ -96,6 +97,85 @@ function _resolveBin(runtime) {
 
 function _resetBinCache() { _binCache.clear(); }
 
+function _runtimeInstallHint(runtimeName, runtime) {
+  if (runtime && typeof runtime.installHint === 'string' && runtime.installHint) return runtime.installHint;
+  return `install the ${runtimeName || 'selected'} CLI and make sure it is on PATH`;
+}
+
+function _missingRuntimeMessage(runtimeName, runtime, reason) {
+  const selected = runtime?.name || runtimeName || 'configured';
+  if (!runtime) {
+    return [
+      `Minions can't run the configured runtime "${selected}".`,
+      '',
+      reason || 'The configured runtime is not registered.',
+      '',
+      'Choose a supported runtime in Settings -> Engine -> defaultCli/ccCli, then install its CLI:',
+      '- Claude Code: npm install -g @anthropic-ai/claude-code or download from https://claude.ai/download',
+      '- GitHub Copilot CLI: install via GitHub CLI/gh-copilot or download from https://github.com/github/copilot-cli/releases',
+      '',
+      'After installing, restart Minions so the dashboard and engine inherit the updated PATH.',
+    ].join('\n');
+  }
+  const lines = [
+    `Minions can't run the "${selected}" runtime yet.`,
+    '',
+    reason || `The ${selected} CLI binary was not found on PATH.`,
+    '',
+    `Install steps for "${selected}": ${_runtimeInstallHint(selected, runtime)}.`,
+    '',
+    'After installing, restart Minions so the dashboard and engine inherit the updated PATH.',
+  ];
+  if (selected !== 'claude') {
+    lines.push('Or switch Settings -> Engine -> defaultCli/ccCli back to "claude" after installing Claude Code.');
+  } else {
+    lines.push('Or switch Settings -> Engine -> defaultCli/ccCli to "copilot" after installing GitHub Copilot CLI.');
+  }
+  return lines.join('\n');
+}
+
+function _missingRuntimeResult(runtimeName, runtime, reason) {
+  const message = _missingRuntimeMessage(runtimeName, runtime, reason);
+  return {
+    text: message,
+    usage: null,
+    sessionId: null,
+    code: MISSING_RUNTIME_EXIT_CODE,
+    stderr: message,
+    raw: '',
+    toolUses: [],
+    runtime: runtime?.name || runtimeName || null,
+    errorClass: shared.FAILURE_CLASS.CONFIG_ERROR,
+    missingRuntime: true,
+  };
+}
+
+function _resolvedCallResult(result) {
+  const promise = Promise.resolve(result);
+  promise.abort = () => {};
+  return promise;
+}
+
+function _resolveRuntimeNameFor(callOpts = {}) {
+  let runtimeName = callOpts.cli;
+  if (!runtimeName && callOpts.engineConfig) runtimeName = resolveCcCli(callOpts.engineConfig);
+  return runtimeName || 'claude';
+}
+
+function _runtimeUnavailableResult(callOpts = {}) {
+  const runtimeName = _resolveRuntimeNameFor(callOpts);
+  let runtime = null;
+  try {
+    runtime = resolveRuntime(runtimeName);
+  } catch (err) {
+    return _missingRuntimeResult(runtimeName, null, err.message);
+  }
+  if (!_resolveBin(runtime)) {
+    return _missingRuntimeResult(runtimeName, runtime, `The ${runtime.name} CLI binary was not found on PATH or in the runtime cache.`);
+  }
+  return null;
+}
+
 // ─── Spawn Helpers ───────────────────────────────────────────────────────────
 
 /**
@@ -386,10 +466,7 @@ function _createStreamAccumulator({
 function _resolveRuntimeFor(callOpts) {
   // Explicit `cli` opt wins; otherwise fall to `engineConfig` resolution;
   // otherwise default to claude (the historical behavior).
-  let runtimeName = callOpts.cli;
-  if (!runtimeName && callOpts.engineConfig) runtimeName = resolveCcCli(callOpts.engineConfig);
-  if (!runtimeName) runtimeName = 'claude';
-  return resolveRuntime(runtimeName);
+  return resolveRuntime(_resolveRuntimeNameFor(callOpts));
 }
 
 function _resolveModelFor(callOpts) {
@@ -434,6 +511,9 @@ function callLLM(promptText, sysPromptText, opts = {}) {
     stream, disableBuiltinMcps, suppressAgentsMd, reasoningSummaries,
   } = opts;
 
+  const unavailable = _runtimeUnavailableResult({ cli: cliOverride, engineConfig });
+  if (unavailable) return _resolvedCallResult(unavailable);
+
   const runtime = _resolveRuntimeFor({ cli: cliOverride, engineConfig });
   const model = _resolveModelForRuntime(runtime, { model: modelOverride, engineConfig });
   const runtimeFeatureOpts = _resolveRuntimeFeatureOpts({
@@ -531,6 +611,9 @@ function callLLMStreaming(promptText, sysPromptText, opts = {}) {
     stream, disableBuiltinMcps, suppressAgentsMd, reasoningSummaries,
   } = opts;
 
+  const unavailable = _runtimeUnavailableResult({ cli: cliOverride, engineConfig });
+  if (unavailable) return _resolvedCallResult(unavailable);
+
   const runtime = _resolveRuntimeFor({ cli: cliOverride, engineConfig });
   const model = _resolveModelForRuntime(runtime, { model: modelOverride, engineConfig });
   const runtimeFeatureOpts = _resolveRuntimeFeatureOpts({

package/engine/pipeline.js

@@ -488,7 +488,9 @@ async function executePlanStage(stage, stageState, run, config) {
       timeout: 120000, label: 'pipeline-plan', model: 'sonnet', maxTurns: 1,
       engineConfig: config.engine,
     });
-    if (result.text) {
+    if (result.missingRuntime) {
+      log('warn', `Pipeline plan LLM skipped: ${result.text || result.stderr || 'runtime unavailable'} — falling back to raw meeting context`);
+    } else if (result.text) {
       content = result.text;
       log('info', `Pipeline plan: LLM generated ${content.length} chars from meeting context`);
     }

package/engine.js

@@ -1129,14 +1129,35 @@ async function spawnAgent(dispatchItem, config) {
     const procInfo = activeProcesses.get(id);
     ackPendingSteeringFiles(agentId, procInfo, stdout);
 
+    if (procInfo?._deferredSteeringFiles?.length && procInfo.sessionId) {
+      const deferredPaths = new Set(procInfo._deferredSteeringFiles);
+      const pendingDeferred = steering.listUnreadSteeringMessages(agentId)
+        .filter(entry => deferredPaths.has(entry.path) && entry.message.trim());
+      if (pendingDeferred.length > 0) {
+        log('info', `Steering: delivering ${pendingDeferred.length} deferred message(s) for ${agentId} at resumable checkpoint`);
+        procInfo._steeringMessage = pendingDeferred.map(entry => entry.message.trim()).join('\n\n');
+        procInfo._steeringSessionId = procInfo.sessionId;
+        procInfo._steeringEntry = pendingDeferred;
+        procInfo._steeringDeferredCheckpoint = true;
+        delete procInfo._deferredSteeringFiles;
+      } else {
+        delete procInfo._deferredSteeringFiles;
+      }
+    } else if (procInfo?._deferredSteeringFiles?.length) {
+      log('warn', `Steering: ${agentId} exited before a resumable sessionId was available — message remains pending`);
+      try { fs.appendFileSync(liveOutputPath, `\n[steering-pending] Agent exited before a resumable session was available. Your message remains unread and will be retried on the next dispatch.\n`); } catch {}
+    }
+
     // Check if this was a steering kill — re-spawn with resume
     if (procInfo?._steeringMessage) {
       const steerMsg = procInfo._steeringMessage;
       const steerSessionId = procInfo._steeringSessionId;
       const steerEntry = procInfo._steeringEntry;
+      const steeringDeferredCheckpoint = procInfo._steeringDeferredCheckpoint === true;
       delete procInfo._steeringMessage;
       delete procInfo._steeringSessionId;
       delete procInfo._steeringEntry;
+      delete procInfo._steeringDeferredCheckpoint;
 
       // Guard: can't resume without a session
       if (!steerSessionId) {
@@ -1247,9 +1268,13 @@ async function spawnAgent(dispatchItem, config) {
         ),
       });
 
-      // Reset output buffers so post-completion parsing only sees the resumed session
-      stdout = '';
-      stderr = '';
+      // Live steering kills discard partial old output. Deferred checkpoint
+      // steering keeps the completed turn output so completion parsing still
+      // sees the original work if the follow-up only acknowledges steering.
+      if (!steeringDeferredCheckpoint) {
+        stdout = '';
+        stderr = '';
+      }
       sessionCaptureState.sessionLineBuffer = '';
       // Re-wire stdout/stderr handlers (same as original)
       resumeProc.stdout.on('data', (data) => {

package/package.json

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