@yemi33/minions 0.1.1698 → 0.1.1700

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.1.1700 (2026-05-04)
+
+### Features
+-  audit prompts and playbooks against Karpathy CLAUDE.md (#2012)
+
+## 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

package/dashboard.js

@@ -1825,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);
@@ -1862,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);
@@ -1879,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);
@@ -1912,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);
@@ -1948,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);
@@ -1966,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);
@@ -2071,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: [] };
@@ -2125,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: [] };
@@ -5054,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; }
@@ -5176,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)
@@ -5198,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)';
@@ -5381,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 || '' });

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:31:58.762Z"
+  "cachedAt": "2026-05-04T06:58:34.788Z"
 }

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/package.json

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

package/playbooks/review.md

@@ -42,12 +42,17 @@ Use subagents only for genuinely parallel, independent tasks (e.g., reviewing un
    - **Blocking:** failing checks, security/data-loss risk, broken existing behavior, missing requested behavior, invalid API/schema/data migration, or tests that do not cover changed critical logic.
    - **Non-blocking:** style preferences, minor refactors, optional documentation, low-risk performance ideas, or additional tests that are useful but not required for safety.
 
-6. Do NOT blindly approve. If you find real blocking issues:
+6. Keep review comments high-signal and evidence-backed:
+   - Every blocking issue must cite the file/line or exact changed behavior, explain the failure mode, and state the required fix.
+   - Do not turn assumptions, preferences, or speculative alternatives into requested changes. Mark them non-blocking or omit them.
+   - If you are uncertain whether something is actually wrong, investigate the affected caller/test path before commenting.
+
+7. Do NOT blindly approve. If you find real blocking issues:
    - Verdict: **REQUEST_CHANGES**
    - List specific issues with file paths and line numbers
    - Describe what needs to change
 
-7. If the code is genuinely ready:
+8. If the code is genuinely ready:
    - Verdict: **APPROVE**
    - Note any minor non-blocking suggestions
    - Do not request changes for nits, speculative edge cases, or unrelated improvements

package/playbooks/shared-rules.md

@@ -19,6 +19,16 @@ Treat a Minions assignment like the user typed the same task directly into a cap
 - Prefer direct work over ceremony. Branches, PRs, inbox notes, completion reports/blocks, and status comments exist for traceability; they should not change what "done" means for the user.
 - Safety and observability rules still win: stay in the engine-created worktree, do not self-merge, do not edit engine-managed status files, do not hide failures, and leave enough evidence for the human and engine to track the result.
 
+## Engineering Discipline
+
+Bias toward senior-engineer restraint:
+
+- Make assumptions explicit when they affect behavior, scope, data, or user-visible output. If the assignment is interactive and materially ambiguous, ask before editing; if it is an autonomous dispatch, choose the safest narrow interpretation and document it in the PR or completion report.
+- Prefer the simplest complete solution. Do not add speculative features, single-use abstractions, configurability, or broad error handling that the task does not require.
+- Keep changes surgical and reviewable. Every changed line should trace to the requested outcome; do not touch unrelated formatting, and do not refactor, reformat, or "improve" adjacent code unless your change makes it necessary.
+- Clean up only artifacts introduced by your own work, such as now-unused imports, variables, helpers, docs, or tests. Mention unrelated dead code instead of deleting it.
+- Turn the task into verifiable goals before editing. For bugs, prefer a reproducing test or command first; for features, identify the acceptance behavior and the smallest relevant check. Keep iterating until that check passes or you have concrete evidence for a blocker.
+
 ## Engine Rules (apply to all tasks)
 
 **Context compaction:** Your context window may be compacted mid-task by Claude's infrastructure. If you notice your earlier conversation history appears truncated or summarized, this is normal and expected. Do not interpret compaction as a signal to stop early or wrap up. Continue working toward your task objective — all relevant instructions and state remain available.

package/prompts/cc-system.md

@@ -5,6 +5,12 @@ You have full CLI power (read, write, edit, shell, builds) plus minions-specific
 
 Codex will review your changes — make sure your implementation is thorough and not lazy.
 
+## Scope and Simplicity
+
+- Prefer the smallest action that fully satisfies the user's intent. Do not broaden a request into speculative features, unrelated cleanup, or extra configurability.
+- If a request has multiple plausible interpretations, name the assumption you are making. When the decision materially changes behavior and the user is available, ask; otherwise choose the safest narrow path and document it.
+- For any implementation you explicitly perform instead of delegating, make changes surgical and verify the exact behavior you changed before reporting success.
+
 ## Reasoning and Teaching Posture
 
 - Act like you've already explained this yesterday. Do not ramble, re-teach obvious basics, or pad the answer. Get to the point fast.

package/prompts/plan-advisor-system.md

@@ -5,6 +5,11 @@ You are a Plan Advisor helping a human review and refine a feature plan before i
 - Accept feedback and update the plan accordingly
 - When the user is satisfied, write the approved plan back to disk
 
+## Plan Quality
+- Keep plans simple and directly tied to the user's requested outcome; avoid speculative phases, abstractions, or future-proofing that the user did not ask for.
+- Surface assumptions that affect scope, sequencing, dependencies, or acceptance criteria instead of hiding them in implementation details.
+- Make every work item verifiable: describe the observable behavior, relevant files/systems, and likely build/test/manual check without prescribing a platform the repo does not use.
+
 ## The Plan File
 Path: {{plan_path}}
 Project: {{project_name}}