@yemi33/minions 0.1.1921 → 0.1.1923

package/bin/minions.js

@@ -766,7 +766,8 @@ if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
   void (async () => {
     const result = await waitForRestartHealth({
       minionsHome: MINIONS_HOME,
-      dashboardUrl: `http://127.0.0.1:${DASH_PORT}/api/health`,
+      dashboardPid: dashProc.pid,
+      dashboardPort: DASH_PORT,
     });
     if (!result.ok) {
       console.error(formatRestartHealthError(result));

package/dashboard.js

@@ -2443,6 +2443,144 @@ async function _preflightModelCheck({ runtime: cliOverride, model: modelOverride
   };
 }
 
+/**
+ * Sub-task D of W-mp2w003600196c51 (CC perf): pool-routed implementation of
+ * the doc-chat LLM call. Mirrors _invokeCcStreamViaPool (the CC streaming
+ * pool path from sub-task C), shaped to plug into ccCall / ccCallStreaming
+ * — the doc-chat call sites that live at module scope rather than inside
+ * the SSE handler closure.
+ *
+ * Pool key: `doc-chat:` + sessionKey (filePath or title). Different file =
+ * different key = natural eviction (the pool kills/respawns the worker on
+ * tab change). For one-shot flows (`freshSession: true`, e.g. Create Plan
+ * from meeting) we use a unique short-lived tab key so the call cannot
+ * inherit (or pollute) the persistent doc-chat conversation for that file.
+ *
+ * Behavior contract (matches callLLMStreaming so callers stay unchanged):
+ *   - Returns a Promise resolving to
+ *     `{ text, sessionId, code, usage, raw, stderr }`.
+ *   - `.abort` attached to the returned Promise. Abort cancels the in-flight
+ *     ACP prompt AND closes the worker tab — same "user-disconnect = strong
+ *     signal, drop the warm process" semantics CC uses in
+ *     handleCommandCenterAbort. For one-shot tabs, the tab is closed in
+ *     `finalize()` regardless of abort so we don't leak workers.
+ *   - `onChunk` receives FULL ACCUMULATED text (the pool emits per-chunk
+ *     deltas; we accumulate before forwarding to match the existing
+ *     contract SSE consumers depend on).
+ *   - `usage` is `{}` because ACP `session/update` notifications don't
+ *     surface token counts; trackEngineUsage is a no-op on `{}`.
+ *   - Tool calls are not surfaced (sub-task B/C don't plumb `tool_call`
+ *     notifications into a callback). Matches CC's pool trade-off.
+ *   - Honors `timeoutMs`. On timeout: cancels the prompt, closes the tab
+ *     (so the next call rebuilds against a clean process), resolves with
+ *     `{ code: 1, stderr: 'doc-chat-pool: timeout after Xms' }`. The
+ *     legacy direct path's `timeout` kills the CLI process; closing the
+ *     tab is the pool equivalent.
+ *
+ * Why we deliberately skip `docSessions` updates on this path: pool ACP
+ * session IDs are valid only inside the live worker process. Persisting
+ * them risks the next call seeing a "session unchanged + _docHash
+ * matches → skip document content" path after the idle reaper (10 min)
+ * kills the worker, silently starving the new ACP session of the
+ * document body. Always re-sending extraContext is correctness-safe; the
+ * pool's warm-process saving is preserved regardless.
+ */
+function _invokeDocChatViaPool({ prompt, model, effort, engineConfig, systemPrompt, sessionKey, freshSession, timeoutMs, onChunk }) {
+  const oneShot = !!freshSession;
+  const tabKey = oneShot
+    ? 'doc-chat:fresh:' + shared.uid()
+    : 'doc-chat:' + (sessionKey || 'default');
+  let cancelled = false;
+  let settled = false;
+  let accumulated = '';
+  let sessionHandle = null;
+  let timeoutTimer = null;
+  let resolveResult;
+  const promise = new Promise((resolve) => { resolveResult = resolve; });
+  const finalize = (envelope) => {
+    if (settled) return;
+    settled = true;
+    if (timeoutTimer) { clearTimeout(timeoutTimer); timeoutTimer = null; }
+    if (oneShot) {
+      // One-shot worker: tear down so freshSession callers don't leak a
+      // persistent ACP process per call.
+      try { ccWorkerPool.closeTab(tabKey); } catch { /* swallow */ }
+    }
+    resolveResult(envelope);
+  };
+  promise.abort = () => {
+    cancelled = true;
+    try { sessionHandle && sessionHandle.cancel(); } catch { /* swallow */ }
+    // User-disconnect = strong "give up this conversation" signal. Mirror
+    // handleCommandCenterAbort's closeTab for the same reason: prevents
+    // partial/cancelled assistant output from polluting the next turn's
+    // ACP context. The cost (lose warmth on next visit) is accepted.
+    try { ccWorkerPool.closeTab(tabKey); } catch { /* swallow */ }
+  };
+  if (timeoutMs && Number.isFinite(timeoutMs) && timeoutMs > 0) {
+    timeoutTimer = setTimeout(() => {
+      try { sessionHandle && sessionHandle.cancel(); } catch { /* swallow */ }
+      try { ccWorkerPool.closeTab(tabKey); } catch { /* swallow */ }
+      finalize({
+        text: accumulated,
+        sessionId: sessionHandle ? sessionHandle.sessionId : null,
+        code: 1,
+        usage: {},
+        raw: accumulated,
+        stderr: `doc-chat-pool: timeout after ${timeoutMs}ms`,
+      });
+    }, timeoutMs);
+    if (typeof timeoutTimer.unref === 'function') timeoutTimer.unref();
+  }
+  (async () => {
+    try {
+      sessionHandle = await ccWorkerPool.getSession({
+        tabId: tabKey,
+        model,
+        effort,
+        mcpServers: (engineConfig && engineConfig.mcpServers) || [],
+        systemPromptHash: _docChatPromptHash,
+      });
+    } catch (err) {
+      return finalize({
+        text: '',
+        sessionId: null,
+        code: 1,
+        usage: {},
+        raw: '',
+        stderr: String((err && err.message) || err || 'cc-worker-pool spawn failed'),
+      });
+    }
+    if (cancelled) {
+      try { sessionHandle.cancel(); } catch { /* swallow */ }
+      return finalize({ text: accumulated, sessionId: sessionHandle.sessionId, code: 0, usage: {}, raw: accumulated, stderr: '' });
+    }
+    await sessionHandle.stream(prompt, {
+      systemPromptText: systemPrompt,
+      onChunk: (delta) => {
+        accumulated += delta;
+        if (onChunk) {
+          try { onChunk(accumulated); } catch { /* swallow */ }
+        }
+      },
+      onDone: () => {
+        finalize({ text: accumulated, sessionId: sessionHandle.sessionId, code: 0, usage: {}, raw: accumulated, stderr: '' });
+      },
+      onError: (err) => {
+        finalize({
+          text: accumulated,
+          sessionId: sessionHandle.sessionId,
+          code: cancelled ? 0 : 1,
+          usage: {},
+          raw: accumulated,
+          stderr: String((err && err.message) || err || 'cc-worker-pool stream error'),
+        });
+      },
+    });
+  })();
+  return promise;
+}
+
 /**
  * Core LLM call — shared by CC panel and doc modals.
  * @param {string} message - User message
@@ -2454,8 +2592,13 @@ async function _preflightModelCheck({ runtime: cliOverride, model: modelOverride
  * @param {number} opts.timeout - Timeout in ms
  * @param {number} opts.maxTurns - Max tool-use turns
  * @param {string} opts.allowedTools - Comma-separated tool list
+ * @param {boolean} [opts.freshSession] - When true (doc-chat one-shot flows like Create Plan
+ *   from meeting), pool-routed calls (sub-task D of W-mp2w003600196c51) use a unique
+ *   short-lived tabKey so the one-shot cannot inherit/pollute the persistent doc-chat
+ *   conversation for the same file. The legacy direct path is unaffected — freshSession
+ *   semantics there are owned by ccDocCall, which deletes docSessions before invoking.
  */
-async function ccCall(message, { store = 'cc', sessionKey, extraContext, label = 'command-center', timeout = CC_CALL_TIMEOUT_MS, maxTurns, allowedTools = 'Bash,Read,Write,Edit,Glob,Grep,WebFetch,WebSearch', skipStatePreamble = false, skipPreflight = false, model, onAbortReady, systemPrompt = CC_STATIC_SYSTEM_PROMPT, transcript, turnId } = {}) {
+async function ccCall(message, { store = 'cc', sessionKey, extraContext, label = 'command-center', timeout = CC_CALL_TIMEOUT_MS, maxTurns, allowedTools = 'Bash,Read,Write,Edit,Glob,Grep,WebFetch,WebSearch', skipStatePreamble = false, skipPreflight = false, model, onAbortReady, systemPrompt = CC_STATIC_SYSTEM_PROMPT, transcript, turnId, freshSession = false } = {}) {
   if (!maxTurns) maxTurns = CONFIG.engine?.ccMaxTurns || shared.ENGINE_DEFAULTS.ccMaxTurns;
   if (!model) model = CONFIG.engine?.ccModel || shared.ENGINE_DEFAULTS.ccModel;
   const ccEffort = CONFIG.engine?.ccEffort || shared.ENGINE_DEFAULTS.ccEffort;
@@ -2468,6 +2611,37 @@ async function ccCall(message, { store = 'cc', sessionKey, extraContext, label =
     }
   }
 
+  // Sub-task D of W-mp2w003600196c51: route doc-chat through the persistent
+  // ACP worker pool when ccUseWorkerPool is on. The pool keeps one warm
+  // process per `doc-chat:<sessionKey>` tabId, saving the session/new + MCP
+  // boot cost on subsequent doc-chat turns. CC's path is wired separately
+  // in _invokeCcStream (handleCommandCenterStream); CC's non-stream ccCall
+  // path intentionally stays on the per-turn spawn (this branch is
+  // store==='doc' only). We deliberately do NOT call updateSession() — pool
+  // ACP session IDs aren't durable across worker eviction; persisting them
+  // alongside docSessions._docHash would risk the next call hitting the
+  // "doc unchanged → skip context" branch after the idle reaper killed the
+  // worker, silently starving the new ACP session of the doc body.
+  if (store === 'doc' && CONFIG.engine && CONFIG.engine.ccUseWorkerPool && sessionKey) {
+    const poolPrompt = (function buildPoolPrompt() {
+      const parts = !skipStatePreamble ? [`## Current Minions State (${new Date().toISOString().slice(0, 16)})\n\n${buildCCStatePreamble()}`] : [];
+      if (extraContext) parts.push(extraContext);
+      const turnHeader = _ccTurnHeaderPart(turnId);
+      if (turnHeader) parts.push(turnHeader);
+      parts.push(message);
+      return parts.join('\n\n---\n\n');
+    })();
+    const p = _invokeDocChatViaPool({
+      prompt: poolPrompt, sessionKey, model, effort: ccEffort,
+      engineConfig: CONFIG.engine, systemPrompt,
+      freshSession, timeoutMs: timeout,
+    });
+    if (onAbortReady) onAbortReady(p.abort);
+    const result = await p;
+    llm.trackEngineUsage(label, result.usage);
+    return result;
+  }
+
   const existing = resolveSession(store, sessionKey);
   let sessionId = existing ? existing.sessionId : null;
   const currentRuntime = shared.resolveCcCli(CONFIG.engine);
@@ -2570,7 +2744,7 @@ async function ccCall(message, { store = 'cc', sessionKey, extraContext, label =
   return result;
 }
 
-async function ccCallStreaming(message, { store = 'cc', sessionKey, extraContext, label = 'command-center', timeout = CC_CALL_TIMEOUT_MS, maxTurns, allowedTools = 'Bash,Read,Write,Edit,Glob,Grep,WebFetch,WebSearch', skipStatePreamble = false, skipPreflight = false, model, onAbortReady, onChunk, onToolUse, onRetry, systemPrompt = CC_STATIC_SYSTEM_PROMPT, transcript, turnId } = {}) {
+async function ccCallStreaming(message, { store = 'cc', sessionKey, extraContext, label = 'command-center', timeout = CC_CALL_TIMEOUT_MS, maxTurns, allowedTools = 'Bash,Read,Write,Edit,Glob,Grep,WebFetch,WebSearch', skipStatePreamble = false, skipPreflight = false, model, onAbortReady, onChunk, onToolUse, onRetry, systemPrompt = CC_STATIC_SYSTEM_PROMPT, transcript, turnId, freshSession = false } = {}) {
   if (!maxTurns) maxTurns = CONFIG.engine?.ccMaxTurns || shared.ENGINE_DEFAULTS.ccMaxTurns;
   if (!model) model = CONFIG.engine?.ccModel || shared.ENGINE_DEFAULTS.ccModel;
   const ccEffort = CONFIG.engine?.ccEffort || shared.ENGINE_DEFAULTS.ccEffort;
@@ -2583,6 +2757,33 @@ async function ccCallStreaming(message, { store = 'cc', sessionKey, extraContext
     }
   }
 
+  // Sub-task D of W-mp2w003600196c51: streaming counterpart of the ccCall
+  // pool branch. See ccCall for the rationale; the streaming variant
+  // additionally forwards onChunk so the SSE writer (handleDocChatStream)
+  // keeps receiving accumulated text per the callLLMStreaming contract.
+  // We also do NOT call updateSession() — see ccCall for the
+  // docSessions-eviction-vs-_docHash staleness rationale.
+  if (store === 'doc' && CONFIG.engine && CONFIG.engine.ccUseWorkerPool && sessionKey) {
+    const poolPrompt = (function buildPoolPrompt() {
+      const parts = !skipStatePreamble ? [`## Current Minions State (${new Date().toISOString().slice(0, 16)})\n\n${buildCCStatePreamble()}`] : [];
+      if (extraContext) parts.push(extraContext);
+      const turnHeader = _ccTurnHeaderPart(turnId);
+      if (turnHeader) parts.push(turnHeader);
+      parts.push(message);
+      return parts.join('\n\n---\n\n');
+    })();
+    const p = _invokeDocChatViaPool({
+      prompt: poolPrompt, sessionKey, model, effort: ccEffort,
+      engineConfig: CONFIG.engine, systemPrompt,
+      onChunk,
+      freshSession, timeoutMs: timeout,
+    });
+    if (onAbortReady) onAbortReady(p.abort);
+    const result = await p;
+    llm.trackEngineUsage(label, result.usage);
+    return result;
+  }
+
   const existing = resolveSession(store, sessionKey);
   let sessionId = existing ? existing.sessionId : null;
   const currentRuntime = shared.resolveCcCli(CONFIG.engine);
@@ -2798,8 +2999,19 @@ function _docChatResultLooksSuccessful(result) {
 // 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);
+//
+// usePool: when true (caller is on the worker-pool path), force `existing=null`
+// so the docUnchanged optimization never fires. Pool ACP session IDs are valid
+// only inside the live worker process; when the idle reaper kills the worker
+// (10 min), the server restarts, or the operator flips ccUseWorkerPool with
+// prior legacy history on disk, a stale docSessions._docHash matching the
+// current doc would otherwise emit docUnchanged:true → _formatDocChatContext
+// replaces the doc body with "unchanged from the previous turn" → the fresh
+// ACP worker answers from an empty document context. Always re-sending the doc
+// body on the pool path is the simplest correctness-safe contract; the pool's
+// warm-process savings are preserved regardless.
+function _buildDocChatPass({ docSlice, title, filePath, selection, canEdit, isJson, sessionKey, freshSession, usePool }) {
+  const existing = (freshSession || usePool) ? 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({
@@ -3006,16 +3218,27 @@ async function ccDocCall({ message, document, title, filePath, selection, canEdi
     // Skip persistDocSessions() here — the post-call cleanup below handles persistence.
   }
 
+  // Sub-task D of W-mp2w003600196c51: when the worker pool is enabled,
+  // ccCall routes this call through _invokeDocChatViaPool. The pool path
+  // gets a fresh ACP worker on flag flip / reaper / restart, so the
+  // docUnchanged optimization (read side) and the _docHash write-back
+  // (write side) must both be disabled — otherwise the next call silently
+  // ships the "unchanged from the previous turn" sentinel against a worker
+  // that has never seen the doc. See _buildDocChatPass for the read-side
+  // rationale; see the post-call write-back below for the symmetric write
+  // guard.
+  const usePool = !!(CONFIG.engine && CONFIG.engine.ccUseWorkerPool && sessionKey);
+
   // Build the pass once for the first call; the retry helper invokes runOnce()
   // with no args after invalidating the session, so a fresh build there reflects
   // the new (no-session) state correctly.
   const initialPass = _buildDocChatPass({
-    docSlice, title, filePath, selection, canEdit, isJson, sessionKey, freshSession,
+    docSlice, title, filePath, selection, canEdit, isJson, sessionKey, freshSession, usePool,
   });
 
   const runOnce = async (passOverride) => {
     const { extraContext } = passOverride || _buildDocChatPass({
-      docSlice, title, filePath, selection, canEdit, isJson, sessionKey, freshSession,
+      docSlice, title, filePath, selection, canEdit, isJson, sessionKey, freshSession, usePool,
     });
     return ccCall(message, {
       store: 'doc', sessionKey,
@@ -3030,6 +3253,11 @@ async function ccDocCall({ message, document, title, filePath, selection, canEdi
       turnId,
       ...(model ? { model } : {}),
       onAbortReady,
+      // Sub-task D of W-mp2w003600196c51: forward freshSession so the pool
+      // path can use a one-shot tabKey for one-shot flows (Create Plan
+      // from meeting etc.) — prevents the one-shot from inheriting OR
+      // polluting the persistent doc-chat conversation for the same file.
+      freshSession,
     });
   };
 
@@ -3041,8 +3269,10 @@ async function ccDocCall({ message, document, title, filePath, selection, canEdi
     // bleed into future interactions under the same key.
     docSessions.delete(sessionKey);
     schedulePersistDocSessions();
-  } else if (_docChatResultLooksSuccessful(result) && result.sessionId) {
-    // Store doc hash for next call's unchanged check
+  } else if (!usePool && _docChatResultLooksSuccessful(result) && result.sessionId) {
+    // Store doc hash for next call's unchanged check (legacy path only —
+    // pool path skips this so a future call cannot silently ride a stale
+    // hash into the docUnchanged branch against a fresh ACP worker).
     const session = resolveSession('doc', sessionKey);
     if (session) session._docHash = initialPass.docHash;
   }
@@ -3075,14 +3305,19 @@ async function ccDocCallStreaming({ message, document, title, filePath, selectio
     docSessions.delete(sessionKey);
   }
 
+  // Sub-task D of W-mp2w003600196c51: see ccDocCall above for the
+  // read-side / write-side rationale; the streaming variant mirrors the
+  // same usePool guard.
+  const usePool = !!(CONFIG.engine && CONFIG.engine.ccUseWorkerPool && sessionKey);
+
   // Build the pass once; see ccDocCall for the dedup rationale.
   const initialPass = _buildDocChatPass({
-    docSlice, title, filePath, selection, canEdit, isJson, sessionKey, freshSession,
+    docSlice, title, filePath, selection, canEdit, isJson, sessionKey, freshSession, usePool,
   });
 
   const runOnce = async (passOverride) => {
     const { extraContext } = passOverride || _buildDocChatPass({
-      docSlice, title, filePath, selection, canEdit, isJson, sessionKey, freshSession,
+      docSlice, title, filePath, selection, canEdit, isJson, sessionKey, freshSession, usePool,
     });
     return ccCallStreaming(message, {
       store: 'doc', sessionKey,
@@ -3099,6 +3334,9 @@ async function ccDocCallStreaming({ message, document, title, filePath, selectio
       onChunk: streamStripper,
       onToolUse,
       onRetry,
+      // Sub-task D of W-mp2w003600196c51: forward freshSession — see
+      // ccDocCall for the one-shot pool-isolation rationale.
+      freshSession,
     });
   };
 
@@ -3108,7 +3346,8 @@ async function ccDocCallStreaming({ message, document, title, filePath, selectio
   if (freshSession && sessionKey) {
     docSessions.delete(sessionKey);
     schedulePersistDocSessions();
-  } else if (_docChatResultLooksSuccessful(result) && result.sessionId) {
+  } else if (!usePool && _docChatResultLooksSuccessful(result) && result.sessionId) {
+    // Legacy path only — see ccDocCall for the pool-path skip rationale.
     const session = resolveSession('doc', sessionKey);
     if (session) session._docHash = initialPass.docHash;
   }
@@ -8085,6 +8324,9 @@ module.exports = {
   _normalizeMeetingParticipants: normalizeMeetingParticipants,
   parsePinnedEntries,
   _formatDocChatContext,
+  _buildDocChatPass,
+  _docSessionsForTesting: docSessions,
+  _docChatPromptHashForTesting: _docChatPromptHash,
   _isCompletedMeetingJson,
   _finalizeDocChatEdit,
   _makeDocChatStreamStripper,

package/engine/copilot-models.json

@@ -0,0 +1,5 @@
+{
+  "runtime": "copilot",
+  "models": null,
+  "cachedAt": "2026-05-13T23:13:36.239Z"
+}

package/engine/dispatch.js

@@ -176,9 +176,10 @@ function addToDispatch(item) {
 
 // ─── Pre-Dispatch Acceptance Criteria Gate (P-a2d6b9c7, Ripley §3) ──────────
 //
-// Optional cheap-LLM validation gate that runs *before* queue insertion so
+// Cheap-LLM validation gate that runs *before* queue insertion so
 // impossible/ambiguous work items are routed to a review queue rather than
-// burning a full agent run. Opt-in via ENGINE_DEFAULTS.enablePreDispatchEval.
+// burning a full agent run. On by default via ENGINE_DEFAULTS.enablePreDispatchEval
+// (P-d2a9f6e5); per-project disable available via the dashboard config UI.
 //
 // Wired from engine.js discoverWork(); kept as a separate async wrapper so
 // the existing synchronous addToDispatch() call sites are unaffected.
@@ -248,7 +249,17 @@ async function addToDispatchWithValidation(item, opts = {}) {
 
   const wi = item?.meta?.item;
   const criteria = wi && (wi.acceptance_criteria || wi.acceptanceCriteria);
-  if (!Array.isArray(criteria) || criteria.length === 0) {
+  const hasCriteria = Array.isArray(criteria) && criteria.length > 0;
+  // P-d2a9f6e5: also let the validator run when criteria are absent but the
+  // work item carries a rich description — defense-in-depth for noop dispatches
+  // authored from description-only WIs (same incident class as P-a4f7c2d8).
+  // The threshold lives in pre-dispatch-eval.js (DESCRIPTION_MIN_CHARS); we
+  // duplicate the bypass check here so we don't even spin up the validator
+  // when there's nothing usable to evaluate.
+  const { DESCRIPTION_MIN_CHARS } = require('./pre-dispatch-eval');
+  const description = ((wi && wi.description) || '').trim();
+  const hasUsableDescription = description.length >= DESCRIPTION_MIN_CHARS;
+  if (!hasCriteria && !hasUsableDescription) {
     return addToDispatch(item);
   }
 
@@ -454,6 +465,11 @@ function completeDispatch(id, result = DISPATCH_RESULT.SUCCESS, reason = '', res
   const agentRetryable = normalizeRetryableDecision(opts.agentRetryable ?? opts.retryable);
   let item = null;
   let completedSourceWorkItem = false;
+  // Pre-spawn failures (e.g. worktree creation) move the item from pending →
+  // completed without it ever entering active. Track this so the human-feedback
+  // dedupe-clear below can skip clearing the completed entry — otherwise the
+  // engine immediately re-queues a fix that has no chance of succeeding (#2454).
+  let wasPending = false;
 
   mutateDispatch((dispatch) => {
     // Check active list first
@@ -463,7 +479,10 @@ function completeDispatch(id, result = DISPATCH_RESULT.SUCCESS, reason = '', res
     } else {
       // Also check pending list (e.g., worktree failure before spawn)
       idx = dispatch.pending.findIndex(d => d.id === id);
-      if (idx >= 0) item = dispatch.pending.splice(idx, 1)[0];
+      if (idx >= 0) {
+        item = dispatch.pending.splice(idx, 1)[0];
+        wasPending = true;
+      }
     }
 
     if (!item) return dispatch;
@@ -625,14 +644,21 @@ function completeDispatch(id, result = DISPATCH_RESULT.SUCCESS, reason = '', res
           else log('info', `Skipped pendingFix restore for ${prId} — PR is no longer tracked`);
         } catch (e) { log('warn', `restore pendingFix: ${e.message}`); }
       }
-      // Clear completed dispatch entry so dedup doesn't block re-dispatch
-      if (item.meta?.dispatchKey) {
+      // Clear completed dispatch entry so dedup doesn't block re-dispatch.
+      // SKIP this clear when the failure happened before spawn (e.g. worktree
+      // creation failure, #2454) — otherwise the engine sees no recent dispatch
+      // history, clears the cooldown as "stale", and re-queues immediately on
+      // the very next tick, looping forever for structural failures like a
+      // stale-locked worktree entry that the agent can't fix on its own.
+      if (item.meta?.dispatchKey && !wasPending) {
         try {
           mutateDispatch((dp) => {
             dp.completed = Array.isArray(dp.completed) ? dp.completed.filter(d => d.meta?.dispatchKey !== item.meta.dispatchKey) : [];
             return dp;
           });
         } catch (e) { log('warn', 'clear human-feedback dispatch for retry: ' + e.message); }
+      } else if (item.meta?.dispatchKey && wasPending) {
+        log('info', `Preserving completed dispatch entry for ${item.meta.dispatchKey} (pre-spawn failure) — cooldown will throttle retry`);
       }
     }
   }

package/engine/pre-dispatch-eval.js

@@ -6,10 +6,17 @@
  *
  * Conservative scope (per task contract):
  *   - Validation only — never rewrites or "fixes" criteria.
- *   - Opt-in via `ENGINE_DEFAULTS.enablePreDispatchEval` (default false) so it
- *     can be enabled per-environment without forcing fleet-wide rollout.
+ *   - Default behavior is governed by `ENGINE_DEFAULTS.enablePreDispatchEval`
+ *     (P-d2a9f6e5: now `true` by default; per-project override via the
+ *     dashboard config UI).
+ *   - When `acceptance_criteria` are absent but the work item carries a rich
+ *     `description` (≥ DESCRIPTION_MIN_CHARS after trim), the validator
+ *     evaluates the description instead of fail-open bypassing — so noop
+ *     dispatches authored from a description-only WI are still caught
+ *     (P-d2a9f6e5; defense-in-depth for the same incident class as
+ *     P-a4f7c2d8 dashboard depends_on bug).
  *   - Fail-open: any LLM error / runtime-unavailable / parse failure resolves
- *     `{ valid: true }` so the gate cannot wedge dispatch on its own.
+ *     `{ valid: true }` so the gate cannot wedge dispatch.
  *
  * Wired from engine/dispatch.js → addToDispatchWithValidation().
  *
@@ -17,6 +24,8 @@
  *   knowledge/architecture/2026-05-11-ripley-daily-architecture-bug-review-ripley-s-investigati.md
  *   (Daily Architecture & Bug Review — 2026-05-11). Lambert + Rebecca debate
  *   rounds reaffirmed: validate-only, no auto-rewrite, opt-in flag.
+ *   P-d2a9f6e5 (architecture meeting 2026-05-13): flip default to true and
+ *   broaden validator to read description when criteria are missing.
  */
 
 const shared = require('./shared');
@@ -26,6 +35,10 @@ const { callLLM } = require('./llm');
 const SYSTEM_PROMPT = 'Output only JSON.';
 const DEFAULT_TIMEOUT_MS = 60000;
 const DEFAULT_MODEL = 'haiku'; // claude shorthand; the runtime adapter expands it (see engine/runtimes/claude.js resolveModel)
+// Minimum trimmed description length that justifies a description-only LLM
+// validation. Below this we fail-open without burning an LLM call — short
+// descriptions don't carry enough signal for the gate to add value.
+const DESCRIPTION_MIN_CHARS = 80;
 
 function _extractCriteria(workItem) {
   if (!workItem || typeof workItem !== 'object') return [];
@@ -36,18 +49,30 @@ function _extractCriteria(workItem) {
   return [];
 }
 
+function _extractDescription(workItem) {
+  if (!workItem || typeof workItem !== 'object') return '';
+  return (workItem.description || '').trim();
+}
+
 function _buildPrompt(workItem, criteria) {
   const title = workItem.title || workItem.name || workItem.id || 'untitled';
-  const description = (workItem.description || '').trim();
+  const description = _extractDescription(workItem);
   const lines = [
     `Work item: ${title}`,
   ];
+  const hasCriteria = Array.isArray(criteria) && criteria.length > 0;
   if (description) lines.push('', 'Description:', description);
-  lines.push('', 'Acceptance criteria:');
-  for (const c of criteria) lines.push(`- ${c}`);
-  lines.push('',
-    'Are these acceptance criteria clear, actionable, and testable?',
-    'Reply with JSON: {"valid": true|false, "reason": "..."}.');
+  if (hasCriteria) {
+    lines.push('', 'Acceptance criteria:');
+    for (const c of criteria) lines.push(`- ${c}`);
+    lines.push('',
+      'Are these acceptance criteria clear, actionable, and testable?',
+      'Reply with JSON: {"valid": true|false, "reason": "..."}.');
+  } else {
+    lines.push('',
+      'Is this work item description clear, actionable, and testable?',
+      'Reply with JSON: {"valid": true|false, "reason": "..."}.');
+  }
   return lines.join('\n');
 }
 
@@ -67,6 +92,12 @@ function _parseResponse(text) {
 /**
  * Validate a work item's acceptance criteria with a fast/cheap LLM call.
  *
+ * Validation modes (P-d2a9f6e5):
+ *   1. Criteria present → evaluate the criteria (legacy behavior).
+ *   2. No criteria but description ≥ DESCRIPTION_MIN_CHARS → evaluate the
+ *      description (defense-in-depth for description-only work items).
+ *   3. Otherwise → fail-open with `{ valid: true }`.
+ *
  * @param {object} workItem - work item with `acceptance_criteria` (or
  *   `acceptanceCriteria`) plus title/description for context.
  * @param {object} [opts]
@@ -78,7 +109,11 @@ function _parseResponse(text) {
  */
 async function validateAcceptanceCriteria(workItem, opts = {}) {
   const criteria = _extractCriteria(workItem);
-  if (criteria.length === 0) {
+  const description = _extractDescription(workItem);
+  const hasCriteria = criteria.length > 0;
+  const hasUsableDescription = description.length >= DESCRIPTION_MIN_CHARS;
+
+  if (!hasCriteria && !hasUsableDescription) {
     return { valid: true, reason: 'no acceptance criteria to validate' };
   }
 
@@ -115,9 +150,12 @@ async function validateAcceptanceCriteria(workItem, opts = {}) {
     log('warn', 'pre-dispatch-eval: response missing boolean valid field — failing open');
     return { valid: true, reason: 'validator response unparseable' };
   }
+  const defaultReason = hasCriteria
+    ? (parsed.valid ? 'criteria look testable' : 'criteria not clear/actionable/testable')
+    : (parsed.valid ? 'description looks testable' : 'description not clear/actionable/testable');
   return {
     valid: parsed.valid,
-    reason: String(parsed.reason || '').trim() || (parsed.valid ? 'criteria look testable' : 'criteria not clear/actionable/testable'),
+    reason: String(parsed.reason || '').trim() || defaultReason,
   };
 }
 
@@ -125,6 +163,8 @@ module.exports = {
   validateAcceptanceCriteria,
   // Exposed for unit testing — engine code MUST go through validateAcceptanceCriteria.
   _extractCriteria,
+  _extractDescription,
   _buildPrompt,
   _parseResponse,
+  DESCRIPTION_MIN_CHARS,
 };

package/engine/restart-health.js

@@ -43,6 +43,25 @@ function isProcessAlive(pid) {
   }
 }
 
+function isPortListening(port) {
+  const n = Number(port);
+  if (!Number.isInteger(n) || n <= 0) return false;
+  try {
+    if (process.platform === 'win32') {
+      const out = execSync(`netstat -ano -p TCP`, {
+        encoding: 'utf8', windowsHide: true, timeout: 3000, maxBuffer: 4 * 1024 * 1024,
+      });
+      const re = new RegExp(`\\s127\\.0\\.0\\.1:${n}\\s+\\S+\\s+LISTENING`, 'i');
+      const re6 = new RegExp(`\\s\\[::1?\\]:${n}\\s+\\S+\\s+LISTENING`, 'i');
+      return re.test(out) || re6.test(out);
+    }
+    const out = execSync(`ss -ltn 'sport = :${n}' 2>/dev/null || netstat -ltn 2>/dev/null`, {
+      encoding: 'utf8', timeout: 3000, shell: true,
+    });
+    return new RegExp(`[:.]${n}\\b`).test(out);
+  } catch { return false; }
+}
+
 function httpGetJson(url, timeoutMs = 1000) {
   return new Promise(resolve => {
     let settled = false;
@@ -81,9 +100,12 @@ function httpGetJson(url, timeoutMs = 1000) {
 async function checkRestartHealth(options = {}) {
   const {
     minionsHome,
-    dashboardUrl = 'http://127.0.0.1:7331/api/health',
+    dashboardUrl,
+    dashboardPid,
+    dashboardPort = 7331,
     readControl = readEngineControl,
     isProcessAlive: isAlive = isProcessAlive,
+    isPortListening: portCheck = isPortListening,
     httpGetJson: getJson = httpGetJson,
   } = options;
 
@@ -92,9 +114,42 @@ async function checkRestartHealth(options = {}) {
   const engineAlive = pid ? isAlive(pid) : false;
   const engineOk = control && control.state === 'running' && engineAlive;
 
-  const dashboard = await getJson(dashboardUrl, 3000);
-  const dashboardStatus = dashboard && dashboard.json && dashboard.json.status;
-  const dashboardOk = !!(dashboard && dashboard.ok && dashboardStatus === 'healthy');
+  // Two strategies for the dashboard check:
+  //   1) Process + port-listening (preferred from `minions restart` since
+  //      `bin/minions.js` knows the dashboard PID it just spawned). This avoids
+  //      a roundtrip through the dashboard's Node event loop, which can be
+  //      blocked for 15-25s during a cold `getStatus()` rebuild while still
+  //      being healthy.
+  //   2) HTTP `/api/health` — legacy path retained for tests that mock
+  //      httpGetJson + dashboardUrl, and for external probes that genuinely
+  //      want a response-level check.
+  // Strategy 1 wins when `dashboardPid` is supplied; otherwise we fall back to
+  // HTTP using the default URL or whatever the caller injected.
+  let dashboardOk;
+  let dashboardDetail;
+  let dashboardKind;
+  let dashboardSnapshot;
+  if (dashboardPid != null && !dashboardUrl) {
+    dashboardKind = 'process';
+    const dpid = normalizePid(dashboardPid);
+    const dashAlive = dpid ? isAlive(dpid) : false;
+    const portOpen = portCheck(dashboardPort);
+    dashboardOk = !!(dashAlive && portOpen);
+    dashboardDetail = `pid=${dpid || 'none'} alive=${dashAlive ? 'yes' : 'no'} port=${dashboardPort} listening=${portOpen ? 'yes' : 'no'}`;
+    dashboardSnapshot = { kind: 'process', pid: dpid, alive: dashAlive, port: dashboardPort, listening: portOpen };
+  } else {
+    dashboardKind = 'http';
+    const url = dashboardUrl || `http://127.0.0.1:${dashboardPort}/api/health`;
+    const dashboard = await getJson(url, 3000);
+    const dashboardStatus = dashboard && dashboard.json && dashboard.json.status;
+    dashboardOk = !!(dashboard && dashboard.ok && dashboardStatus === 'healthy');
+    dashboardDetail = dashboard && dashboard.error
+      ? dashboard.error.message
+      : dashboard && dashboard.statusCode
+        ? `HTTP ${dashboard.statusCode}${dashboardStatus ? `, status=${dashboardStatus}` : ''}`
+        : 'no response';
+    dashboardSnapshot = { kind: 'http', url, ok: !!(dashboard && dashboard.ok), statusCode: dashboard && dashboard.statusCode, status: dashboardStatus };
+  }
 
   const errors = [];
   if (!engineOk) {
@@ -103,18 +158,16 @@ async function checkRestartHealth(options = {}) {
     errors.push(`Engine is not healthy (state=${state}, pid=${pidLabel}, alive=${engineAlive ? 'yes' : 'no'})`);
   }
   if (!dashboardOk) {
-    const detail = dashboard && dashboard.error
-      ? dashboard.error.message
-      : dashboard && dashboard.statusCode
-        ? `HTTP ${dashboard.statusCode}${dashboardStatus ? `, status=${dashboardStatus}` : ''}`
-        : 'no response';
-    errors.push(`Dashboard failed health check at ${dashboardUrl} (${detail})`);
+    const where = dashboardKind === 'http'
+      ? (dashboardUrl || `http://127.0.0.1:${dashboardPort}/api/health`)
+      : `dashboard pid=${normalizePid(dashboardPid) || 'none'} port=${dashboardPort}`;
+    errors.push(`Dashboard failed health check at ${where} (${dashboardDetail})`);
   }
 
   return {
     ok: engineOk && dashboardOk,
     engine: { state: control && control.state, pid, alive: engineAlive },
-    dashboard: { url: dashboardUrl, ok: !!(dashboard && dashboard.ok), statusCode: dashboard && dashboard.statusCode, status: dashboardStatus },
+    dashboard: dashboardSnapshot,
     errors,
   };
 }
@@ -163,6 +216,7 @@ module.exports = {
   _private: {
     httpGetJson,
     isProcessAlive,
+    isPortListening,
     readEngineControl,
     normalizePid,
   },

package/engine/shared.js

@@ -1100,7 +1100,7 @@ const ENGINE_DEFAULTS = {
   botCommentLogins: [], // P-a3f9b2c1: opt-in shared-minions GH login list — comments from these logins are suppressed ONLY when body matches positive-signal markers (Verification SUCCESS / VERDICT:APPROVE / noop:true). Narrower than ignoredCommentAuthors which suppresses all comments by login.
   agentBusyReassignMs: 600000, // 10min — reassign work item to another agent if preferred agent is busy beyond this threshold
   ccEffort: null, // effort level for CC/doc-chat (null, 'low', 'medium', 'high')
-  enablePreDispatchEval: false, // opt-in: cheap LLM gate before queueing — see engine/pre-dispatch-eval.js (Ripley §3 recommendation, 2026-05-11 architecture review)
+  enablePreDispatchEval: true, // P-d2a9f6e5: cheap LLM gate before queueing — on by default. See engine/pre-dispatch-eval.js (Ripley §3 recommendation, 2026-05-11 architecture review). Validates from acceptance_criteria when present, falls back to description when criteria are absent but description is rich (≥80 chars). Fail-open on any validator error.
 
   // ── Runtime fleet (P-3b8e5f1d) ──────────────────────────────────────────────
   // Single source of truth for which CLI runtime + model every spawn uses.

package/engine.js

@@ -573,6 +573,39 @@ async function runWorktreeAdd(rootDir, worktreePath, args, gitOpts, worktreeCrea
   if (lastErr) throw lastErr;
 }
 
+// Detect and remove worktree registrations whose backing directory is missing
+// on disk. `git worktree add` fails with "branch is already used by worktree
+// at <path>" when a prior crash left such an entry behind, sometimes still in
+// `locked: initializing` state. Single -f errors out with "cannot remove a
+// locked working tree, lock reason: initializing" — must use -f -f.
+// Returns the number of stale entries removed (so callers can decide whether
+// to retry the worktree add).
+async function pruneStaleWorktreeForBranch(rootDir, branchName, gitOpts) {
+  if (!branchName) return 0;
+  let trees = [];
+  try {
+    const out = await execAsync(`git worktree list --porcelain`, { ...gitOpts, cwd: rootDir, timeout: 10000 });
+    trees = shared.parseWorktreePorcelain(out);
+  } catch (e) {
+    log('warn', `pruneStaleWorktreeForBranch list: ${e.message?.split('\n')[0]}`);
+    return 0;
+  }
+  const stale = trees.filter(w => w.branch === branchName && w.path && !fs.existsSync(w.path));
+  if (stale.length === 0) return 0;
+  let removed = 0;
+  for (const w of stale) {
+    try {
+      await execAsync(`git worktree remove -f -f "${w.path}"`, { ...gitOpts, cwd: rootDir, timeout: 15000 });
+      removed++;
+      log('warn', `Removed stale worktree entry for ${branchName} at missing path ${w.path}${w.locked ? ' (was locked)' : ''}`);
+    } catch (e) {
+      log('warn', `git worktree remove -f -f failed for stale ${w.path}: ${e.message?.split('\n')[0]}`);
+    }
+  }
+  try { await execAsync(`git worktree prune`, { ...gitOpts, cwd: rootDir, timeout: 10000 }); } catch { /* best-effort */ }
+  return removed;
+}
+
 async function recoverPartialWorktree(rootDir, worktreePath, branchName, gitOpts) {
   if (!branchName) return false;
   const existingWt = await findExistingWorktree(rootDir, branchName);
@@ -717,7 +750,16 @@ async function spawnAgent(dispatchItem, config) {
                   shared.assertWorktreeOutsideProject(existingWtPath, rootDir);
                   log('info', `Shared branch ${branchName} already checked out at ${existingWtPath} — reusing`);
                   worktreePath = existingWtPath;
-                } else { throw eShared; }
+                } else {
+                  // Branch is registered but path is missing on disk (#2454).
+                  // git keeps the entry — sometimes locked: initializing — and
+                  // every subsequent add fails identically. Force-prune and retry.
+                  const pruned = await pruneStaleWorktreeForBranch(rootDir, branchName, _gitOpts);
+                  if (pruned > 0) {
+                    log('info', `Pruned ${pruned} stale worktree entry(ies) for shared branch ${branchName}; retrying worktree add`);
+                    await runWorktreeAdd(rootDir, worktreePath, `"${branchName}"`, _worktreeGitOpts, 0);
+                  } else { throw eShared; }
+                }
               } else if (eShared.message?.includes('invalid reference') || eShared.message?.includes('not a valid ref')) {
                 // Branch doesn't exist yet (first item in plan) — create it from main
                 const mainRef = sanitizeBranch(shared.resolveMainBranch(rootDir, project.mainBranch));
@@ -800,9 +842,14 @@ async function spawnAgent(dispatchItem, config) {
           cwd = worktreePath;
           log('warn', `Proceeding with recovered worktree after add failure for ${branchName}`);
         } else {
+          // Include err.stderr (where git's "fatal: ..." text lives) and use a
+          // larger budget than 200 chars — the issue title is unreadable when
+          // the slice cuts off mid-"fatal:" leaving just "fa" (#2454).
+          const stderrSnippet = err.stderr ? '\n' + err.stderr.toString().trim() : '';
+          const fullMsg = `${err.message || ''}${stderrSnippet}`.trim();
           log('error', `Failed to create worktree for ${branchName}: ${err.message}${err.stderr ? '\n' + err.stderr.toString().slice(0, 500) : ''}`);
           _cleanupPromptFiles();
-          completeDispatch(id, DISPATCH_RESULT.ERROR, 'Worktree creation failed: ' + (err.message || '').slice(0, 200));
+          completeDispatch(id, DISPATCH_RESULT.ERROR, 'Worktree creation failed: ' + fullMsg.slice(0, 800));
           cleanupTempAgent(agentId);
           return null;
         }
@@ -5075,6 +5122,7 @@ module.exports = {
   reconcileItemsWithPrs, detectDependencyCycles,
   parseConflictFiles, pruneAncestorDeps, preflightMergeSimulation, // exported for testing
   isWorktreeRetryableError, removeStaleIndexLock, syncReusedWorktree, // exported for testing
+  pruneStaleWorktreeForBranch, // exported for testing
   _maxTurnsForType, buildProjectContext, normalizeAc, _buildAgentSpawnFlags, _classifyAgentFailure, // exported for testing
   promoteCheckpointSteeringForClose, // exported for testing
   normalizePrBranch, resolvePrBranch, prCausePart, getPrCauseHead, getPrCauseBase, getPrAutomationCauseKey, getPrAutomationDispatchKey, // exported for testing

package/package.json

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