@yemi33/minions 0.1.1740 → 0.1.1742

package/CHANGELOG.md

@@ -1,14 +1,23 @@
 # Changelog
 
-## 0.1.1740 (2026-05-06)
+## 0.1.1742 (2026-05-06)
+
+### Fixes
+- pending-reassignment double-books agent with own pending dispatch (#2108)
+
+## 0.1.1741 (2026-05-06)
 
 ### Features
-- doc-chat resume retry + 1h timeout + surfaced stderr (#2101)
-- make Command Center chat sessions non-expiring (#2100)
+- hard-timeout backstop prevents permanent round stalls
+- auto-index API + CLI catalog into preamble; threshold-based delegation gate
 
-### Fixes
-- invalidate stale session IDs on runtime switch (#2102)
-- drop 5s setTimeout that nuked sysprompt .tmp before Claude could read it (#2105)
+### Other
+- chore(gitignore): ignore .vscode/, engine/completions/, pull-requests.json.backup
+
+## 0.1.1739 (2026-05-06)
+
+### Features
+- make Command Center chat sessions non-expiring (#2100)
 
 ## 0.1.1738 (2026-05-06)
 

package/dashboard.js

@@ -1176,6 +1176,50 @@ let _preambleCache = null;
 let _preambleCacheTs = 0;
 const PREAMBLE_TTL = 30000; // 30s — longer TTL since preamble is lightweight orientation, not real-time data
 
+// SoT for CC's runtime API index. Captured lazily on the first HTTP request
+// because ROUTES is closed over inside the request handler. Subsequent
+// captures no-op via the truthy guard.
+let _ccApiRoutesMeta = null;
+
+function _routesAsMeta(routes) {
+  return routes.map(r => ({
+    method: r.method,
+    path: typeof r.path === 'string' ? r.path : String(r.path),
+    desc: r.desc || '',
+    params: r.params || null,
+  }));
+}
+
+function _captureApiRoutesMeta(routes) {
+  if (_ccApiRoutesMeta || !Array.isArray(routes)) return;
+  _ccApiRoutesMeta = _routesAsMeta(routes);
+}
+
+function _formatCcApiRoutesIndex() {
+  if (!Array.isArray(_ccApiRoutesMeta) || _ccApiRoutesMeta.length === 0) return '';
+  return _ccApiRoutesMeta
+    .filter(r => r.path.startsWith('/api/'))
+    .map(r => {
+      const params = r.params ? ` — params: ${r.params}` : '';
+      return `- \`${r.method} ${r.path}\` — ${r.desc}${params}`;
+    })
+    .join('\n');
+}
+
+const { CLI_COMMAND_DOCS: _CC_CLI_DOCS } = require('./engine/cli');
+
+function _formatCcCliCommandsIndex() {
+  if (!_CC_CLI_DOCS) return '';
+  return Object.entries(_CC_CLI_DOCS)
+    .map(([name, { args, summary }]) => `- \`minions ${name}${args ? ' ' + args : ''}\` — ${summary}`)
+    .join('\n');
+}
+
+function _resetPreambleCache() {
+  _preambleCache = null;
+  _preambleCacheTs = 0;
+}
+
 function buildCCStatePreamble() {
   const now = Date.now();
   if (_preambleCache && now - _preambleCacheTs < PREAMBLE_TTL) return _preambleCache;
@@ -1198,6 +1242,19 @@ function buildCCStatePreamble() {
   let pipelineCount = 0;
   try { pipelineCount = require('./engine/pipeline').getPipelines().length; } catch {}
 
+  const apiIndex = _formatCcApiRoutesIndex();
+  const cliIndex = _formatCcCliCommandsIndex();
+  const indexSection = (apiIndex || cliIndex) ? `
+
+### API Index (auto-generated from dashboard.js ROUTES — single source of truth)
+${apiIndex || '(routes not yet captured — first request still pending)'}
+
+### CLI Index (auto-generated from engine/cli.js CLI_COMMAND_DOCS — single source of truth)
+${cliIndex || '(unavailable)'}
+
+For any \`/api/...\` endpoint not covered by a named CC action, use the generic fallback:
+\`{"type":"<descriptive>","endpoint":"/api/...","params":{...}}\`.` : '';
+
   const result = `### Agents
 ${agents}
 
@@ -1211,8 +1268,8 @@ PRs: ${prCount} | Work items: ${wiCount} | Plans/PRDs: ${planFiles.length} | Sch
 ### Projects
 ${projects}
 
-Use tools to read \`config.json\` (schedules), \`pipelines/\` dir, or \`curl http://localhost:7331/api/routes\` for details.
-For all state files, look under \`${MINIONS_DIR}\`.`;
+Use tools to read \`config.json\` (schedules), \`pipelines/\` dir for details.
+For all state files, look under \`${MINIONS_DIR}\`.${indexSection}`;
   _preambleCache = result;
   _preambleCacheTs = now;
   return result;
@@ -6546,12 +6603,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       });
     }},
     { method: 'GET', path: '/api/routes', desc: 'List all available API endpoints', handler: (req, res) => {
-      const list = ROUTES.map(r => ({
-        method: r.method,
-        path: typeof r.path === 'string' ? r.path : r.path.toString(),
-        description: r.desc,
-        params: r.params || null
-      }));
+      const list = _routesAsMeta(ROUTES).map(({ desc, ...rest }) => ({ ...rest, description: desc }));
       return jsonReply(res, 200, { routes: list });
     }},
 
@@ -7184,6 +7236,11 @@ What would you like to discuss or change? When you're happy, say "approve" and I
 
   // ── Route Dispatcher ────────────────────────────────────────────────────────
 
+  // Capture ROUTES metadata into the module-level snapshot so CC's preamble
+  // renders the live API surface (single source of truth — adding any new
+  // route to ROUTES above auto-surfaces it in CC's index).
+  _captureApiRoutesMeta(ROUTES);
+
   const pathname = req.url.split('?')[0];
   const _reqStart = Date.now();
   for (const route of ROUTES) {
@@ -7269,6 +7326,11 @@ module.exports = {
   _resolveWorkItemsCreateTarget: resolveWorkItemsCreateTarget,
   _createPipelineFromAction: createPipelineFromAction,
   executeCCActions,
+  buildCCStatePreamble,
+  _captureApiRoutesMeta,
+  _formatCcApiRoutesIndex,
+  _formatCcCliCommandsIndex,
+  _resetPreambleCache,
 };
 
 // Start the HTTP server only when run directly (node dashboard.js).

package/engine/cli.js

@@ -97,27 +97,41 @@ function handleCommand(cmd, args) {
   } else {
     console.log(`Unknown command: ${cmd}`);
     console.log('Commands:');
-    console.log('  start [--cli R] [--model M]   Start engine daemon (R = registered runtime)');
-    console.log('  stop                          Stop engine');
-    console.log('  pause / resume                Pause/resume dispatching');
-    console.log('  status                        Show engine + agent state + fleet config');
-    console.log('  queue                         Show dispatch queue');
-    console.log('  sources                       Show work source status');
-    console.log('  discover                      Dry-run work discovery');
-    console.log('  dispatch                      Force a dispatch cycle');
-    console.log('  spawn <a> <p>                 Manually spawn agent with prompt');
-    console.log('  work <title> [o]              Add to work-items.json queue');
-    console.log('  plan <src> [p]                Generate PRD from a plan (file or text)');
-    console.log('  kill                          Kill all active agents, reset to pending');
-    console.log('  complete <id>                 Mark a 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');
-    console.log('  config set-cli <R> [--model M]  Persist defaultCli/defaultModel without starting');
+    for (const line of formatCliCommandHelpLines()) console.log(line);
     process.exit(1);
   }
 }
 
+// SoT for engine-CLI metadata: drives handleCommand's help text and the
+// CC preamble's CLI index in dashboard.js. Drift-checked against `commands`.
+const CLI_COMMAND_DOCS = Object.freeze({
+  start:    { args: '[--cli R] [--model M]', summary: 'Start engine daemon (R = registered runtime)' },
+  stop:     { args: '',                      summary: 'Stop engine' },
+  pause:    { args: '',                      summary: 'Pause dispatching' },
+  resume:   { args: '',                      summary: 'Resume dispatching' },
+  status:   { args: '',                      summary: 'Show engine + agent state + fleet config' },
+  queue:    { args: '',                      summary: 'Show dispatch queue' },
+  sources:  { args: '',                      summary: 'Show work source status per project' },
+  discover: { args: '',                      summary: 'Dry-run work discovery' },
+  dispatch: { args: '',                      summary: 'Force a dispatch cycle' },
+  spawn:    { args: '<agent> <prompt>',      summary: 'Manually spawn an agent with prompt' },
+  work:     { args: '<title> [opts]',        summary: 'Add to work-items.json queue' },
+  plan:     { args: '<file|text> [project]', summary: 'Generate PRD from a plan (file or text)' },
+  kill:       { args: '',                      summary: 'Kill all active agents, reset to pending' },
+  complete:   { args: '<dispatch-id>',         summary: 'Mark a dispatch as done' },
+  cleanup:    { args: '',                      summary: 'Clean temp files, worktrees, zombies' },
+  'mcp-sync': { args: '',                      summary: 'Sync MCP servers from ~/.claude.json' },
+  doctor:     { args: '',                      summary: 'Check prerequisites and runtime health' },
+  config:     { args: 'set-cli <R> [--model M]', summary: 'Persist defaultCli/defaultModel without starting' },
+});
+
+function formatCliCommandHelpLines() {
+  const entries = Object.entries(CLI_COMMAND_DOCS);
+  const lefts = entries.map(([name, { args }]) => '  ' + name + (args ? ' ' + args : ''));
+  const padTo = Math.max(...lefts.map(s => s.length)) + 2;
+  return entries.map(([, { summary }], i) => lefts[i].padEnd(padTo) + summary);
+}
+
 // ─── Runtime fleet flags (--cli / --model / --effort) ────────────────────────
 //
 // Shared by `start`, `restart`, and `config set-cli`. Single source of truth
@@ -1461,7 +1475,11 @@ const commands = {
 
 module.exports = {
   handleCommand,
+  // exported for downstream indexing (dashboard CC preamble)
+  CLI_COMMAND_DOCS,
+  formatCliCommandHelpLines,
   // exported for testing
+  _listCommandKeys: () => Object.keys(commands),
   _parseRuntimeFlags,
   _modelLooksIncompatible,
   _applyRuntimeFlags,

package/engine/copilot-models.json

@@ -1,5 +1,5 @@
 {
   "runtime": "copilot",
   "models": null,
-  "cachedAt": "2026-05-06T00:41:30.276Z"
+  "cachedAt": "2026-05-06T01:07:10.189Z"
 }

package/engine/meeting.js

@@ -730,6 +730,8 @@ function checkMeetingTimeouts(config) {
   const meetings = getMeetings();
   const timeout = (config.engine || {}).meetingRoundTimeout
     || ENGINE_DEFAULTS.meetingRoundTimeout;
+  const hardTimeout = (config.engine || {}).meetingRoundHardTimeout
+    || ENGINE_DEFAULTS.meetingRoundHardTimeout;
 
   for (const meeting of meetings) {
     if (isTerminalMeetingStatus(meeting.status)) continue;
@@ -760,11 +762,34 @@ function checkMeetingTimeouts(config) {
         meeting.transcript.push({ round: meeting.round, agent: 'system', type: 'timeout', content: `Round ${meeting.round} timed out after all participants finished`, at: ts() });
         advanceMeetingIfRoundComplete(meeting, roundName, meeting.id, config);
         saveMeeting(meeting);
+      } else if (elapsed >= hardTimeout) {
+        const failures = getRoundFailures(meeting, roundName, meeting.round, true);
+        const stalled = (meeting.participants || []).filter(p => !hasRoundTerminalOutcome(meeting, roundName, p, meeting.round));
+        const reason = `Hard meeting timeout after ${Math.round(elapsed / 60000)}min — agent did not produce ${roundName} output`;
+        for (const agentId of stalled) {
+          failures[agentId] = { reason, content: '', submittedAt: ts() };
+          meeting.transcript.push({ round: meeting.round, agent: agentId, type: 'failure', content: reason, at: ts() });
+        }
+        log('warn', `Meeting ${meeting.id}: round ${meeting.round} hit hard timeout after ${Math.round(elapsed / 60000)}min — marking ${stalled.length}/${totalCount} non-responders as failed and advancing`);
+        meeting.transcript.push({ round: meeting.round, agent: 'system', type: 'timeout', content: `Round ${meeting.round} hard timeout — ${stalled.length} non-responder(s) marked failed`, at: ts() });
+        advanceMeetingIfRoundComplete(meeting, roundName, meeting.id, config);
+        saveMeeting(meeting);
       } else {
         log('warn', `Meeting ${meeting.id}: round ${meeting.round} timed out after ${Math.round(elapsed / 60000)}min — waiting for all participants to finish (${respondedCount}/${totalCount} succeeded)`);
       }
     } else if (meeting.status === 'concluding') {
-      log('warn', `Meeting ${meeting.id}: conclusion round timed out after ${Math.round(elapsed / 60000)}min — waiting for the conclusion agent to finish`);
+      if (elapsed >= hardTimeout) {
+        const reason = `Hard meeting timeout after ${Math.round(elapsed / 60000)}min — conclusion agent did not produce output`;
+        const failures = getRoundFailures(meeting, 'conclude', meeting.round, true);
+        const conclusionAgent = (meeting.participants || []).find(p => !hasRoundTerminalOutcome(meeting, 'conclude', p, meeting.round)) || meeting.participants?.[0] || 'system';
+        failures[conclusionAgent] = { reason, content: '', submittedAt: ts() };
+        meeting.transcript.push({ round: meeting.round, agent: conclusionAgent, type: 'failure', content: reason, at: ts() });
+        log('warn', `Meeting ${meeting.id}: conclusion round hit hard timeout after ${Math.round(elapsed / 60000)}min — synthesising fallback conclusion`);
+        advanceMeetingIfRoundComplete(meeting, 'conclude', meeting.id, config);
+        saveMeeting(meeting);
+      } else {
+        log('warn', `Meeting ${meeting.id}: conclusion round timed out after ${Math.round(elapsed / 60000)}min — waiting for the conclusion agent to finish`);
+      }
     }
   }
 }

package/engine/shared.js

@@ -861,7 +861,8 @@ const ENGINE_DEFAULTS = {
   prNoOpFixPauseAttempts: 2, // pause one PR automation cause after repeated no-op fixes for unchanged evidence
   completionReportRetentionDays: 90, // retain completion report sidecars beyond capped dispatch history
   completionReportMaxFiles: 5000, // hard cap for completion report sidecars during cleanup
-  meetingRoundTimeout: 900000, // 15min per meeting round before auto-advance
+  meetingRoundTimeout: 900000, // 15min per meeting round — soft signal; logs a "still waiting" warning each tick
+  meetingRoundHardTimeout: 3600000, // 60min hard backstop — non-terminal participants are marked failed and the round advances. Prevents permanent stalls if an agent's dispatch never spawns or its completion gets dropped.
   evalLoop: true, // enable review→fix loop after implementation completes
   evalMaxIterations: 3, // legacy UI/config field; engine discovery no longer enforces review→fix cycle caps
   evalMaxCost: null, // USD ceiling per work item across all eval iterations; null = no limit (gather baseline data first)

package/engine.js

@@ -4326,6 +4326,17 @@ async function tickInner() {
 
   // Build set of agents currently active (one task per agent at a time).
   const busyAgents = new Set((dispatch.active || []).map(d => d.agent));
+  // W-motc4y1n000t1a5f: Track agents that already have a pending dispatch in
+  // the queue. Reassignment routes (busy / unspawned-temp) must not move a
+  // dispatch onto an agent who already has their own pending entry — order-
+  // dependent iteration would otherwise double-book that agent. Seeded once
+  // from the snapshot of pending and updated on successful reassignment.
+  const pendingAgents = new Set();
+  for (const p of (dispatch.pending || [])) {
+    if (typeof p.agent === 'string' && p.agent && p.agent !== routing.ANY_AGENT) {
+      pendingAgents.add(p.agent);
+    }
+  }
   // Branch mutex: track branches locked by active dispatches to prevent concurrent writes
   const lockedBranches = new Set();
   for (const d of (dispatch.active || [])) {
@@ -4409,9 +4420,12 @@ async function tickInner() {
     const isUnspawnedTemp = item.agent?.startsWith('temp-') && !busyAgents.has(item.agent);
     if (isUnspawnedTemp) {
       const altAgent = resolvePendingDispatchAgent(item, config);
-      if (altAgent && altAgent !== item.agent) {
+      // W-motc4y1n000t1a5f: don't reassign onto an agent who already has
+      // their own pending dispatch — that would double-book the alt.
+      if (altAgent && altAgent !== item.agent && !pendingAgents.has(altAgent)) {
         const prevAgent = item.agent;
         assignPendingDispatchAgent(item, altAgent, config);
+        pendingAgents.add(altAgent);
         log('info', `Reassigning ${item.id} from unspawned temp ${prevAgent} to ${altAgent} — temp agent never spawned`);
         // Persist reassignment to dispatch.json so it survives restarts/ticks
         persistPendingDispatchAgent(item);
@@ -4427,10 +4441,14 @@ async function tickInner() {
         continue; // Valid hard pin — keep waiting for pinned agent
       }
       // agent busy and idle alternative available — reroute immediately (no threshold)
+      // W-motc4y1n000t1a5f: pendingAgents check prevents reassigning onto an
+      // agent who already has their own pending dispatch (order-dependent
+      // double-book in the meeting fan-out scenario).
       const altAgent = resolvePendingDispatchAgent(item, config);
-      if (altAgent && altAgent !== originalAgent && !busyAgents.has(altAgent)) {
+      if (altAgent && altAgent !== originalAgent && !busyAgents.has(altAgent) && !pendingAgents.has(altAgent)) {
         log('info', `Reassigning ${item.id} from ${originalAgent} to ${altAgent} — agent busy and idle alternative available`);
         assignPendingDispatchAgent(item, altAgent, config);
+        pendingAgents.add(altAgent);
         persistPendingDispatchAgent(item);
         // Fall through to branch mutex / concurrency checks below
       } else if (isSoftFixDispatch(item)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.1740",
+  "version": "0.1.1742",
   "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/prompts/cc-system.md

@@ -30,30 +30,35 @@ CAN modify: notes, plans, knowledge, work items, pull-requests.json, routing.md,
 Minions state lives in `{{minions_dir}}/`. Key paths: `config.json` (config), `routing.md` (dispatch rules), `projects/{name}/work-items.json` & `pull-requests.json` (per-project), `agents/{id}/` (charters, output), `plans/` & `prd/` (plans), `knowledge/` (KB), `notes/inbox/` (inbox), `engine/dispatch.json` (queue), `playbooks/` (templates). Use tools to read specifics.
 
 ## Role: Orchestrator
-Default: **delegate to agents**. Agents have full Claude Code + worktrees + MCP tools.
+You are primarily a dispatcher. Agents have full Claude Code + worktrees + MCP tools and are better suited for real work — but you are not hard-stopped from handling small requests yourself.
 
-### When to delegate (ALWAYS)
+### Step 1 — Estimate difficulty before responding
+State the size in 3-4 words to yourself, then act:
+- **Small** (≤3 tool calls, 1-2 files, no cross-module reasoning): you MAY do it yourself.
+- **Medium** (4-10 tool calls, 3+ files, multi-file reasoning, real refactor): you MUST delegate.
+- **Large** (10+ tool calls, cross-cutting, multi-stage): you MUST delegate, consider a plan with decomposition.
+
+### Step 2 — Delegate when ≥ Medium (the hard stop)
+Always delegate these to an agent — do not attempt them yourself even if they look small at first:
 - Code changes, fixes, refactors, new features → `implement` or `fix`
 - Exploration, investigation, research, audits → `explore`
 - Code reviews → `review`
 - Testing → `test`
 - Architecture analysis → `explore`
-- Any task that would require **more than 3 tool calls** or touching **more than 2 files**
+- Anything ≥ Medium per Step 1
 
-### When to do it yourself (ONLY these)
+### Step 3 — Small tasks: do them yourself when it's faster than dispatching
+Examples (not an exhaustive whitelist — apply Step 1 to anything not listed):
 - Quick status lookups (reading 1-2 state files)
 - Notes, plan edits, KB entries, routing updates
 - Git ops the user explicitly asked CC to do
 - Simple config changes (`set-config`)
 - Answering questions from context you already have
+- One-line edits to non-protected files when the change is unambiguous
 
-### Size estimation rule
-Before responding, estimate the task size:
-- **Small** (≤3 tool calls, 1-2 files): do it yourself
-- **Medium** (4-10 tool calls, 3+ files): DELEGATE to an agent
-- **Large** (10+ tool calls, cross-cutting): DELEGATE, consider a plan with decomposition
+If you start a small task and discover it's actually Medium (3+ files, more tool calls than expected, surprising complexity), STOP and delegate instead of pushing through.
 
-When in doubt, delegate. You are the dispatcher, not the worker. Agents have isolated worktrees, full tool access, and no turn limits — they are better suited for real work.
+When genuinely in doubt about the size, delegate — agents have isolated worktrees, full tool access, and no turn limits.
 
 ## Actions
 Append actions at the END of your response. Write your response first, then `===ACTIONS===` on its own line, then a JSON array. No text after the JSON. Omit entirely if no actions needed.
@@ -149,4 +154,13 @@ Terms like schedules, pipelines, agents, inbox, work items, plans, PRD, PRs, dis
 1. Answer from the state preamble and context first. Only use tools for specific file lookups the user asked about — not to explore or investigate.
 2. Be specific — cite IDs, names, filenames, line numbers.
 3. Never modify engine source. Never push to git without user confirmation.
-4. Delegate, don't do. If a task involves code changes, multi-file reads, debugging, or any real engineering work — dispatch an agent. Your tools are for quick lookups, not for doing the work.
+4. Estimate first, then act (see Role: Orchestrator). For Medium-and-above tasks, your tools are for orientation; the agent does the work. For Small tasks, you may do them yourself.
+
+## API & CLI Index (auto-injected)
+Your state preamble (delivered alongside this prompt at session start) carries an auto-generated **API Index** rendered from `dashboard.js` `ROUTES` and a **CLI Index** rendered from `engine/cli.js` `CLI_COMMAND_DOCS`. Both are single-source-of-truth — adding a new HTTP endpoint or CLI command auto-surfaces it in your preamble; do not memorize the named action shorthand list above as exhaustive.
+
+For any `/api/...` endpoint that doesn't have a matching named action above, emit the generic fallback shape:
+`{"type":"<short-descriptor>","endpoint":"/api/...","params":{...}}`
+The action runner accepts any local `/api/` path and POSTs `params` as JSON.
+
+For CLI commands (`minions <cmd>`), use Bash to invoke them when delegating would be heavier than just running the command.