@yemi33/minions 0.1.1739 → 0.1.1741

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.1.1741 (2026-05-06)
+
+### Features
+- hard-timeout backstop prevents permanent round stalls
+- auto-index API + CLI catalog into preamble; threshold-based delegation gate
+
+### Other
+- chore(gitignore): ignore .vscode/, engine/completions/, pull-requests.json.backup
+
 ## 0.1.1739 (2026-05-06)
 
 ### Features

package/dashboard.js

@@ -952,9 +952,10 @@ const CC_STREAM_REATTACH_GRACE_MS = 60000; // keep CC job alive briefly after di
 const CC_STREAM_DONE_RETENTION_MS = 30000; // retain final payload briefly so reconnect can still receive it
 const CC_LIVE_STREAM_MAX_AGE_MS = shared.ENGINE_DEFAULTS.ccLiveStreamMaxAgeMs;
 // Doc-chat is interactive — long-doc edits with multi-step Read+Write tool use can run
-// 4–5 min on `canEdit:true` paths. CC's default 2-min timeout was killing legitimate
-// edits mid-stream. Pinned to 6 min as the bounded but generous ceiling.
-const DOC_CHAT_TIMEOUT_MS = 360000;
+// well past 5 min on `canEdit:true` paths. Bumped to 1 hour (matching CC) so legitimate
+// edits aren't killed mid-stream and the backend timeout never beats the user's reading
+// time. The doc-chat handlers still abort on client disconnect.
+const DOC_CHAT_TIMEOUT_MS = 60 * 60 * 1000;
 function _releaseCCTab(tabId) { ccInFlightTabs.delete(tabId); ccInFlightAborts.delete(tabId); }
 function _getCcLiveStream(tabId) {
   return ccLiveStreams.get(tabId) || null;
@@ -1175,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;
@@ -1197,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}
 
@@ -1210,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;
@@ -2466,6 +2524,56 @@ function _formatDocChatContext({ document, title, filePath, selection, canEdit,
   return context;
 }
 
+// Build the doc-chat extraContext for a single ccCall pass — refreshed on retry
+// so a fresh-session retry includes the full document instead of relying on the
+// dead session's prior turn for context.
+function _buildDocChatPass({ docSlice, title, filePath, selection, canEdit, isJson, sessionKey, freshSession }) {
+  const existing = freshSession ? null : resolveSession('doc', sessionKey);
+  const docHash = require('crypto').createHash('md5').update(docSlice).digest('hex').slice(0, 8);
+  const docUnchanged = existing?.sessionId && existing._docHash === docHash;
+  const extraContext = _formatDocChatContext({
+    document: docSlice, title, filePath, selection, canEdit, isJson, docUnchanged,
+  });
+  return { extraContext, docHash, hadSession: !!existing?.sessionId };
+}
+
+// One-shot recovery from a stuck resumed session: if the initial call rode an
+// existing session and came back empty / non-zero, invalidate the persisted
+// session and re-run via the supplied closure. ccCall already retries fresh
+// when the runtime can't extract a sessionId, but on adapter-still-alive
+// failures it preserves the session — and from doc-chat's perspective that's
+// the failure mode the user actually sees ("Failed to process request").
+async function _retryDocChatAfterResumeFailure({ result, initialPass, freshSession, sessionKey, runOnce }) {
+  if (!initialPass.hadSession || freshSession || result.missingRuntime) return result;
+  if (result.code === 0 && result.text) return result;
+  console.log(`[doc-chat] Resumed session call failed (code=${result.code}, empty=${!result.text}) — invalidating session and retrying fresh for ${sessionKey || 'untitled'}`);
+  if (sessionKey) {
+    docSessions.delete(sessionKey);
+    schedulePersistDocSessions();
+  }
+  return runOnce();
+}
+
+// Build the {error} envelope returned to the dashboard when doc-chat ultimately
+// fails. Keeps the polite user-facing message but exposes the runtime's real
+// stderr / exit code / errorClass so the UI can render the cause and so future
+// failures are debuggable from logs.
+function _docChatFailureResponse(label, filePath, result) {
+  const stderrTail = (result.stderr || '').slice(-2048);
+  console.error(`[${label}] Failed: code=${result.code}, empty=${!result.text}, filePath=${filePath}, errorClass=${result.errorClass || 'null'}, stderr=${stderrTail.slice(0, 200)}`);
+  return {
+    answer: 'Failed to process request. Try again.',
+    content: null,
+    actions: [],
+    error: {
+      code: result.code ?? null,
+      stderr: stderrTail,
+      errorClass: result.errorClass || null,
+      runtime: result.runtime || null,
+    },
+  };
+}
+
 // Doc-specific wrapper — adds document context, parses ---DOCUMENT---
 async function ccDocCall({ message, document, title, filePath, selection, canEdit, isJson, model, freshSession, onAbortReady }) {
   const sessionKey = filePath || title;
@@ -2479,34 +2587,30 @@ async function ccDocCall({ message, document, title, filePath, selection, canEdi
     // Skip persistDocSessions() here — the post-call cleanup below handles persistence.
   }
 
-  // Skip re-sending full document on session resume if content unchanged
-  const docHash = require('crypto').createHash('md5').update(docSlice).digest('hex').slice(0, 8);
-  const existing = freshSession ? null : resolveSession('doc', sessionKey);
-  const docUnchanged = existing?.sessionId && existing._docHash === docHash;
-
-  const docContext = _formatDocChatContext({
-    document: docSlice,
-    title,
-    filePath,
-    selection,
-    canEdit,
-    isJson,
-    docUnchanged,
-  });
   const allowActions = _messageRequestsOrchestration(message);
 
-  const result = await ccCall(message, {
-    store: 'doc', sessionKey,
-    extraContext: docContext, label: 'doc-chat',
-    timeout: DOC_CHAT_TIMEOUT_MS,
-    allowedTools: canEdit ? 'Read,Write,Edit,Glob,Grep' : 'Read,Glob,Grep',
-    maxTurns: canEdit ? 25 : 10,
-    timeout: DOC_CHAT_TIMEOUT_MS,
-    skipStatePreamble: true,
-    systemPrompt: DOC_CHAT_SYSTEM_PROMPT,
-    ...(model ? { model } : {}),
-    onAbortReady,
+  const runOnce = async () => {
+    const { extraContext } = _buildDocChatPass({
+      docSlice, title, filePath, selection, canEdit, isJson, sessionKey, freshSession,
+    });
+    return ccCall(message, {
+      store: 'doc', sessionKey,
+      extraContext, label: 'doc-chat',
+      timeout: DOC_CHAT_TIMEOUT_MS,
+      allowedTools: canEdit ? 'Read,Write,Edit,Glob,Grep' : 'Read,Glob,Grep',
+      maxTurns: canEdit ? 25 : 10,
+      skipStatePreamble: true,
+      systemPrompt: DOC_CHAT_SYSTEM_PROMPT,
+      ...(model ? { model } : {}),
+      onAbortReady,
+    });
+  };
+
+  const initialPass = _buildDocChatPass({
+    docSlice, title, filePath, selection, canEdit, isJson, sessionKey, freshSession,
   });
+  let result = await runOnce();
+  result = await _retryDocChatAfterResumeFailure({ result, initialPass, freshSession, sessionKey, runOnce });
 
   if (freshSession && sessionKey) {
     // One-shot call — discard the session ccCall just stored so it cannot
@@ -2516,7 +2620,7 @@ async function ccDocCall({ message, document, title, filePath, selection, canEdi
   } else if (result.code === 0 && result.sessionId) {
     // Store doc hash for next call's unchanged check
     const session = resolveSession('doc', sessionKey);
-    if (session) session._docHash = docHash;
+    if (session) session._docHash = initialPass.docHash;
   }
 
   if (result.missingRuntime) {
@@ -2524,8 +2628,7 @@ async function ccDocCall({ message, document, title, filePath, selection, canEdi
   }
 
   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: [] };
+    return _docChatFailureResponse('doc-chat', filePath, result);
   }
 
   return _parseDocChatResultText(result.text, { allowActions });
@@ -2539,42 +2642,39 @@ async function ccDocCallStreaming({ message, document, title, filePath, selectio
     docSessions.delete(sessionKey);
   }
 
-  const docHash = require('crypto').createHash('md5').update(docSlice).digest('hex').slice(0, 8);
-  const existing = freshSession ? null : resolveSession('doc', sessionKey);
-  const docUnchanged = existing?.sessionId && existing._docHash === docHash;
-
-  const docContext = _formatDocChatContext({
-    document: docSlice,
-    title,
-    filePath,
-    selection,
-    canEdit,
-    isJson,
-    docUnchanged,
-  });
   const allowActions = _messageRequestsOrchestration(message);
 
-  const result = await ccCallStreaming(message, {
-    store: 'doc', sessionKey,
-    extraContext: docContext, label: 'doc-chat',
-    timeout: DOC_CHAT_TIMEOUT_MS,
-    allowedTools: canEdit ? 'Read,Write,Edit,Glob,Grep' : 'Read,Glob,Grep',
-    maxTurns: canEdit ? 25 : 10,
-    timeout: DOC_CHAT_TIMEOUT_MS,
-    skipStatePreamble: true,
-    systemPrompt: DOC_CHAT_SYSTEM_PROMPT,
-    ...(model ? { model } : {}),
-    onAbortReady,
-    onChunk: (text) => { if (onChunk) onChunk(_docChatDisplayText(text, { allowActions })); },
-    onToolUse,
+  const runOnce = async () => {
+    const { extraContext } = _buildDocChatPass({
+      docSlice, title, filePath, selection, canEdit, isJson, sessionKey, freshSession,
+    });
+    return ccCallStreaming(message, {
+      store: 'doc', sessionKey,
+      extraContext, label: 'doc-chat',
+      timeout: DOC_CHAT_TIMEOUT_MS,
+      allowedTools: canEdit ? 'Read,Write,Edit,Glob,Grep' : 'Read,Glob,Grep',
+      maxTurns: canEdit ? 25 : 10,
+      skipStatePreamble: true,
+      systemPrompt: DOC_CHAT_SYSTEM_PROMPT,
+      ...(model ? { model } : {}),
+      onAbortReady,
+      onChunk: (text) => { if (onChunk) onChunk(_docChatDisplayText(text, { allowActions })); },
+      onToolUse,
+    });
+  };
+
+  const initialPass = _buildDocChatPass({
+    docSlice, title, filePath, selection, canEdit, isJson, sessionKey, freshSession,
   });
+  let result = await runOnce();
+  result = await _retryDocChatAfterResumeFailure({ result, initialPass, freshSession, sessionKey, runOnce });
 
   if (freshSession && sessionKey) {
     docSessions.delete(sessionKey);
     schedulePersistDocSessions();
   } else if (result.code === 0 && result.sessionId) {
     const session = resolveSession('doc', sessionKey);
-    if (session) session._docHash = docHash;
+    if (session) session._docHash = initialPass.docHash;
   }
 
   if (result.missingRuntime) {
@@ -2582,8 +2682,7 @@ async function ccDocCallStreaming({ message, document, title, filePath, selectio
   }
 
   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: [] };
+    return _docChatFailureResponse('doc-chat-stream', filePath, result);
   }
 
   return _parseDocChatResultText(result.text, { allowActions });
@@ -4680,7 +4779,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         }
       }
 
-      const { answer, content, actions, actionParseError } = await ccDocCall({
+      const { answer, content, actions, actionParseError, error: ccError } = await ccDocCall({
         message: body.message, document: currentContent, title: body.title,
         filePath: body.filePath, selection: body.selection, canEdit, isJson,
         model: body.model || undefined,
@@ -4689,11 +4788,12 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       });
       const actionResults = await executeDocChatActions(actions);
       const baseReply = (extra = {}) => ({
-        ok: true,
+        ok: !ccError,
         answer,
         actions,
         ...(actionResults ? { actionResults } : {}),
         ...(actionParseError ? { actionParseError } : {}),
+        ...(ccError ? { error: ccError } : {}),
         ...extra,
       });
 
@@ -4795,7 +4895,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
 
       try {
 
-        const { answer, content, actions, actionParseError } = await ccDocCallStreaming({
+        const { answer, content, actions, actionParseError, error: ccError } = await ccDocCallStreaming({
           message: body.message, document: currentContent, title: body.title,
           filePath: body.filePath, selection: body.selection, canEdit, isJson,
           model: body.model || undefined,
@@ -4811,6 +4911,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           actions,
           ...(actionResults ? { actionResults } : {}),
           ...(actionParseError ? { actionParseError } : {}),
+          ...(ccError ? { error: ccError } : {}),
           ...extra,
         });
 
@@ -6502,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 });
     }},
 
@@ -7140,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) {
@@ -7225,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:40:29.215Z"
+  "cachedAt": "2026-05-06T01:02:44.756Z"
 }

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/runtimes/claude.js

@@ -287,12 +287,33 @@ function getSkillWriteTargets({ homeDir = os.homedir(), project = null } = {}) {
   };
 }
 
+// Stamped into every session.json this adapter writes so the pre-spawn resume
+// path can detect "session was produced by a different runtime" — Claude
+// rejects Copilot session IDs (and vice versa) with "No conversation found",
+// which would otherwise burn a retry slot before the post-failure cleanup at
+// engine.js:1195 fires. See W-mot9fwya000d09cb.
+const RUNTIME_NAME = 'claude';
+
 function getResumeSessionId({ agentId, branchName, agentsDir, maxAgeMs = 2 * 60 * 60 * 1000, logger = console } = {}) {
   if (!agentId || agentId.startsWith('temp-') || !agentsDir) return null;
+  const sessionPath = path.join(agentsDir, agentId, 'session.json');
   try {
-    const sessionPath = path.join(agentsDir, agentId, 'session.json');
     const sessionFile = _safeJson(sessionPath);
     if (!sessionFile?.sessionId || !sessionFile.savedAt) return null;
+
+    // Runtime-mismatch invalidation. Distinct from stale-by-age: the session is
+    // structurally unusable on this runtime, so drop it AND clear session.json
+    // so the next dispatch starts fresh instead of failing with --resume.
+    // Legacy sessions (no `runtime` field) are treated as compatible — opt-in
+    // check, no false invalidations on first deploy.
+    if (sessionFile.runtime && sessionFile.runtime !== RUNTIME_NAME) {
+      if (logger && typeof logger.info === 'function') {
+        logger.info(`Skipping resume for ${agentId}: runtime mismatch (session: ${sessionFile.runtime}, current: ${RUNTIME_NAME}) — clearing session.json`);
+      }
+      try { fs.unlinkSync(sessionPath); } catch {}
+      return null;
+    }
+
     const sessionAge = Date.now() - new Date(sessionFile.savedAt).getTime();
     const sameBranch = branchName && sessionFile.branch && sessionFile.branch === branchName;
     if (sessionAge < maxAgeMs && sameBranch) {
@@ -315,6 +336,7 @@ function saveSession({ agentId, dispatchId, branch, sessionId, agentsDir, now =
       dispatchId,
       savedAt: typeof now === 'function' ? now() : new Date().toISOString(),
       branch: branch || null,
+      runtime: RUNTIME_NAME,
     });
     return true;
   } catch (err) {

package/engine/runtimes/copilot.js

@@ -306,12 +306,33 @@ function getSkillWriteTargets({ homeDir = os.homedir(), project = null } = {}) {
   };
 }
 
+// Stamped into every session.json this adapter writes so the pre-spawn resume
+// path can detect "session was produced by a different runtime" — Copilot
+// rejects Claude session IDs (and vice versa) with "No conversation found",
+// which would otherwise burn a retry slot before the post-failure cleanup at
+// engine.js:1195 fires. See W-mot9fwya000d09cb.
+const RUNTIME_NAME = 'copilot';
+
 function getResumeSessionId({ agentId, branchName, agentsDir, maxAgeMs = 2 * 60 * 60 * 1000, logger = console } = {}) {
   if (!agentId || agentId.startsWith('temp-') || !agentsDir) return null;
+  const sessionPath = path.join(agentsDir, agentId, 'session.json');
   try {
-    const sessionPath = path.join(agentsDir, agentId, 'session.json');
     const sessionFile = _safeJson(sessionPath);
     if (!sessionFile?.sessionId || !sessionFile.savedAt) return null;
+
+    // Runtime-mismatch invalidation. Distinct from stale-by-age: the session is
+    // structurally unusable on this runtime, so drop it AND clear session.json
+    // so the next dispatch starts fresh instead of failing with --resume.
+    // Legacy sessions (no `runtime` field) are treated as compatible — opt-in
+    // check, no false invalidations on first deploy.
+    if (sessionFile.runtime && sessionFile.runtime !== RUNTIME_NAME) {
+      if (logger && typeof logger.info === 'function') {
+        logger.info(`Skipping resume for ${agentId}: runtime mismatch (session: ${sessionFile.runtime}, current: ${RUNTIME_NAME}) — clearing session.json`);
+      }
+      try { fs.unlinkSync(sessionPath); } catch {}
+      return null;
+    }
+
     const sessionAge = Date.now() - new Date(sessionFile.savedAt).getTime();
     const sameBranch = branchName && sessionFile.branch && sessionFile.branch === branchName;
     if (sessionAge < maxAgeMs && sameBranch) {
@@ -334,6 +355,7 @@ function saveSession({ agentId, dispatchId, branch, sessionId, agentsDir, now =
       dispatchId,
       savedAt: typeof now === 'function' ? now() : new Date().toISOString(),
       branch: branch || null,
+      runtime: RUNTIME_NAME,
     });
     return true;
   } catch (err) {

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/spawn-agent.js

@@ -355,11 +355,14 @@ function main() {
 
   // Clean up sys tmp (only created for non-resume sessions on adapters that
   // use --system-prompt-file).
-  if (wantsSystemPromptFile) {
-    setTimeout(() => { try { fs.unlinkSync(sysTmpPath); } catch { /* cleanup */ } }, 5000);
-  }
-
-  // Register exit handler to clean up orphaned temp files
+  //
+  // We deliberately DO NOT use a fixed-delay setTimeout here. Claude CLI reads
+  // `--system-prompt-file` lazily during init; on cold starts (MCP boot,
+  // `--add-dir` traversal, Windows process startup) the read can land well
+  // after any short timer fires, leaving Claude to bail with
+  // "System prompt file not found". The exit/SIGTERM handler below — plus the
+  // matching unlinks in engine/dispatch.js and engine/meeting.js on dispatch
+  // completion — are sufficient to keep tmp files from leaking.
   function _cleanupSpawnTempFiles() {
     if (wantsSystemPromptFile) {
       try { fs.unlinkSync(sysTmpPath); } catch { /* may already be cleaned */ }

package/package.json

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