@yemi33/minions 0.1.1922 → 0.1.1924

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/settings.js

@@ -97,7 +97,7 @@ async function openSettings() {
       settingsToggle('Allow Temp Agents', 'set-allowTempAgents', !!e.allowTempAgents, 'Spawn ephemeral agents when all permanent agents are busy') +
       settingsToggle('Auto-archive Plans', 'set-autoArchive', !!e.autoArchive, 'Automatically archive plans after verify completes (off = manual archive via dashboard)') +
       settingsToggle('Auto-complete PRs', 'set-autoCompletePrs', !!e.autoCompletePrs, 'Auto-merge PRs when builds pass and review is approved (opt-in)') +
-      settingsToggle('CC Worker Pool', 'set-ccUseWorkerPool', !!e.ccUseWorkerPool, 'Route Command Center / doc-chat through a persistent copilot --acp worker per tab instead of spawning a fresh CLI per turn (opt-in)') +
+      settingsToggle('CC Worker Pool', 'set-ccUseWorkerPool', (e.ccUseWorkerPool === undefined ? ((e.ccCli || e.defaultCli) === 'copilot') : !!e.ccUseWorkerPool), 'Route Command Center / doc-chat through a persistent copilot --acp worker per tab instead of spawning a fresh CLI per turn. Default ON for copilot runtime (cold-spawn is ~20s on Windows); default OFF for claude.') +
     '</div>' +
 
     '<h3 style="font-size:13px;color:var(--blue);margin-bottom:8px">PR Polling &amp; Dispatch Gates</h3>' +

package/dashboard.js

@@ -2622,7 +2622,7 @@ async function ccCall(message, { store = 'cc', sessionKey, extraContext, label =
   // 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) {
+  if (store === 'doc' && shared.resolveCcUseWorkerPool(CONFIG.engine) && 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);
@@ -2763,7 +2763,7 @@ async function ccCallStreaming(message, { store = 'cc', sessionKey, extraContext
   // 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) {
+  if (store === 'doc' && shared.resolveCcUseWorkerPool(CONFIG.engine) && 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);
@@ -3227,7 +3227,7 @@ async function ccDocCall({ message, document, title, filePath, selection, canEdi
   // 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);
+  const usePool = !!(shared.resolveCcUseWorkerPool(CONFIG.engine) && 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
@@ -3308,7 +3308,7 @@ async function ccDocCallStreaming({ message, document, title, filePath, selectio
   // 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);
+  const usePool = !!(shared.resolveCcUseWorkerPool(CONFIG.engine) && sessionKey);
 
   // Build the pass once; see ccDocCall for the dedup rationale.
   const initialPass = _buildDocChatPass({
@@ -6089,7 +6089,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       // per-tab handles in dashboard state, and matches "tab close" semantics
       // — if the user explicitly aborted, we don't owe them a warm process).
       // Off when the flag is off so legacy SIGTERM-only behavior is preserved.
-      if (CONFIG.engine && CONFIG.engine.ccUseWorkerPool) {
+      if (shared.resolveCcUseWorkerPool(CONFIG.engine)) {
         try { ccWorkerPool.closeTab(tabId); } catch { /* swallow */ }
       }
       _clearCcLiveStream(tabId);
@@ -6234,7 +6234,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
    * test enforces engine.js does not import cc-worker-pool).
    */
   function _invokeCcStream({ prompt, sessionId, liveState, toolUses, model, effort, maxTurns, engineConfig, systemPrompt = CC_STATIC_SYSTEM_PROMPT, tabId }) {
-    if (engineConfig && engineConfig.ccUseWorkerPool) {
+    if (shared.resolveCcUseWorkerPool(engineConfig)) {
       return _invokeCcStreamViaPool({ prompt, liveState, model, effort, engineConfig, systemPrompt, tabId });
     }
     const { callLLMStreaming } = require('./engine/llm');

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

@@ -1213,6 +1213,27 @@ function resolveCcCli(engine) {
   return ENGINE_DEFAULTS.defaultCli;
 }
 
+/**
+ * Resolve whether the Command Center / doc-chat path should route through the
+ * persistent ACP worker pool. Priority:
+ *   1. `engine.ccUseWorkerPool` explicit true/false — operator override always wins
+ *   2. Runtime-aware default: ON when CC runtime resolves to `copilot`
+ *      (Copilot's cold-spawn is 18-21s on Windows — pool turns subsequent turns
+ *      from 47-140s back into a few seconds). Claude's cold-spawn is much
+ *      cheaper and the ACP pool wasn't designed for it, so it stays OFF there.
+ *   3. ENGINE_DEFAULTS.ccUseWorkerPool — final fallback
+ *
+ * Strict boolean check on the override so a literal `false` opts out even on
+ * Copilot, matching `_isMeaningful` semantics for boolean flags.
+ */
+function resolveCcUseWorkerPool(engine) {
+  if (engine && (engine.ccUseWorkerPool === true || engine.ccUseWorkerPool === false)) {
+    return engine.ccUseWorkerPool;
+  }
+  if (resolveCcCli(engine) === 'copilot') return true;
+  return !!ENGINE_DEFAULTS.ccUseWorkerPool;
+}
+
 /**
  * Resolve the model for a per-agent spawn. Priority:
  *   1. `agent.model`            — per-agent override
@@ -3698,7 +3719,7 @@ module.exports = {
   KB_CATEGORIES,
   classifyInboxItem,
   ENGINE_DEFAULTS,
-  resolveAgentCli, resolveCcCli, resolveAgentModel, resolveCcModel,
+  resolveAgentCli, resolveCcCli, resolveCcUseWorkerPool, resolveAgentModel, resolveCcModel,
   resolveAgentMaxBudget, resolveAgentBareMode,
   applyLegacyCcModelMigration, _resetLegacyCcModelMigrationFlag,
   runtimeConfigWarnings,

package/engine.js

@@ -606,6 +606,111 @@ async function pruneStaleWorktreeForBranch(rootDir, branchName, gitOpts) {
   return removed;
 }
 
+// ─── assertCleanSharedWorktree (#2439) ──────────────────────────────────────
+// Engine-side preflight that prevents shared-branch dispatches from spawning
+// into a dirty worktree. Without this, the shared-branch playbook's "git status
+// + bail out" guard fires AFTER dispatch — converting an orchestration hygiene
+// problem into a fake implementation failure that also cascades to dependent
+// work items.
+//
+// Behavior:
+//   1. Run `git status --porcelain` in the target worktree.
+//   2. If clean → { clean: true, healed: false }.
+//   3. If dirty, decide whether self-heal is safe:
+//      - Block (preserve dirty tree for inspection) when ANOTHER active
+//        dispatch claims the same branch (ownership ambiguity).
+//      - Block when local commits exist that aren't on origin/<branch>
+//        (would lose unpushed work).
+//      - Otherwise reset --hard + clean -fd, then re-verify.
+//   4. Return { clean, healed, reason, dirtyFiles } so the caller can fail
+//      fast with a first-class DIRTY_WORKTREE reason and retry semantics.
+async function assertCleanSharedWorktree(rootDir, worktreePath, branchName, dispatchId, gitOpts = {}) {
+  const result = { clean: false, healed: false, reason: null, dirtyFiles: [] };
+  // 1. Status probe
+  let statusOut = '';
+  try {
+    const r = await execAsync('git status --porcelain', { ...gitOpts, cwd: worktreePath, timeout: 10000 });
+    statusOut = (r || '').toString().trim();
+  } catch (e) {
+    result.reason = 'status-failed';
+    result.error = e.message;
+    return result;
+  }
+  if (!statusOut) {
+    result.clean = true;
+    return result;
+  }
+  result.dirtyFiles = statusOut.split('\n').map(l => l.trim()).filter(Boolean);
+
+  // 2. Ownership check — another live dispatch on the same branch?
+  const sanitized = sanitizeBranch(branchName);
+  let otherActive = false;
+  try {
+    mutateDispatch((dp) => {
+      otherActive = (dp.active || []).some(d => {
+        if (d.id === dispatchId) return false;
+        const dBranch = d.meta?.branch ? sanitizeBranch(d.meta.branch) : '';
+        return dBranch === sanitized;
+      });
+      return dp;
+    });
+  } catch (e) {
+    log('warn', `assertCleanSharedWorktree: dispatch read failed (${e.message}) — assuming contended`);
+    otherActive = true;
+  }
+  if (otherActive) {
+    result.reason = 'other-dispatch-active';
+    return result;
+  }
+
+  // 3. Unpushed-commit check — refuse to clean when local work would be lost.
+  //    `git log @{u}..HEAD --oneline` returns non-empty when there are commits
+  //    ahead of the upstream. If there is no upstream at all, treat as unsafe
+  //    to clean (we can't prove the local commits exist on origin).
+  let hasUnpushed = false;
+  try {
+    const r = await execAsync('git log @{u}..HEAD --oneline', { ...gitOpts, cwd: worktreePath, timeout: 10000 });
+    hasUnpushed = (r || '').toString().trim().length > 0;
+  } catch (e) {
+    // No upstream configured (e.g., branch never pushed) — be conservative.
+    hasUnpushed = true;
+  }
+  if (hasUnpushed) {
+    result.reason = 'has-unpushed-commits';
+    return result;
+  }
+
+  // 4. Safe to self-heal: reset + clean
+  try {
+    await execAsync('git reset --hard HEAD', { ...gitOpts, cwd: worktreePath, timeout: 30000 });
+    await execAsync('git clean -fd', { ...gitOpts, cwd: worktreePath, timeout: 30000 });
+  } catch (e) {
+    result.reason = 'clean-failed';
+    result.error = e.message;
+    return result;
+  }
+
+  // 5. Re-verify
+  try {
+    const r2 = await execAsync('git status --porcelain', { ...gitOpts, cwd: worktreePath, timeout: 10000 });
+    const after = (r2 || '').toString().trim();
+    if (after) {
+      result.reason = 'dirty-after-clean';
+      result.dirtyFiles = after.split('\n').map(l => l.trim()).filter(Boolean);
+      return result;
+    }
+  } catch (e) {
+    result.reason = 'recheck-failed';
+    result.error = e.message;
+    return result;
+  }
+
+  log('info', `assertCleanSharedWorktree: auto-healed dirty shared-branch worktree ${worktreePath} on ${branchName} (${result.dirtyFiles.length} dirty files reset)`);
+  result.clean = true;
+  result.healed = true;
+  return result;
+}
+
 async function recoverPartialWorktree(rootDir, worktreePath, branchName, gitOpts) {
   if (!branchName) return false;
   const existingWt = await findExistingWorktree(rootDir, branchName);
@@ -856,6 +961,31 @@ async function spawnAgent(dispatchItem, config) {
       }
     }
 
+    // Shared-branch preflight (#2439): refuse to dispatch into a dirty shared
+    // worktree. Auto-heals when safe (no other dispatch claims the branch and
+    // no unpushed commits); blocks dispatch with a retryable DIRTY_WORKTREE
+    // failure otherwise. Without this, the playbook's `git status + bail` guard
+    // fires AFTER spawn — converting orchestration hygiene into fake
+    // implementation failures and cascading dependent items.
+    if (worktreePath && fs.existsSync(worktreePath) && meta?.branchStrategy === 'shared-branch' && branchName) {
+      const cleanResult = await assertCleanSharedWorktree(rootDir, worktreePath, branchName, id, _gitOpts);
+      if (!cleanResult.clean) {
+        const previewFiles = (cleanResult.dirtyFiles || []).slice(0, 5).join(', ');
+        const reasonMsg = `DIRTY_WORKTREE: shared branch ${branchName} worktree at ${worktreePath} is dirty (${cleanResult.reason}); ${cleanResult.dirtyFiles?.length || 0} file(s)${previewFiles ? ': ' + previewFiles : ''}`;
+        log('error', reasonMsg);
+        _cleanupPromptFiles();
+        completeDispatch(
+          id,
+          DISPATCH_RESULT.ERROR,
+          reasonMsg.slice(0, 500),
+          `Engine preflight refused to spawn into a dirty shared-branch worktree (#2439). Reason: ${cleanResult.reason}.`,
+          { agentRetryable: true },
+        );
+        cleanupTempAgent(agentId);
+        return null;
+      }
+    }
+
     // Merge dependency PR branches into worktree (applies to both reused and new worktrees)
     if (worktreePath && fs.existsSync(worktreePath)) {
       cwd = worktreePath;
@@ -5121,7 +5251,7 @@ module.exports = {
   // Shared helpers (used by lifecycle.js and tests)
   reconcileItemsWithPrs, detectDependencyCycles,
   parseConflictFiles, pruneAncestorDeps, preflightMergeSimulation, // exported for testing
-  isWorktreeRetryableError, removeStaleIndexLock, syncReusedWorktree, // exported for testing
+  isWorktreeRetryableError, removeStaleIndexLock, syncReusedWorktree, assertCleanSharedWorktree, // exported for testing
   pruneStaleWorktreeForBranch, // exported for testing
   _maxTurnsForType, buildProjectContext, normalizeAc, _buildAgentSpawnFlags, _classifyAgentFailure, // exported for testing
   promoteCheckpointSteeringForClose, // exported for testing

package/package.json

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