@yemi33/minions 0.1.2232 → 0.1.2234

package/bin/minions.js

@@ -373,6 +373,24 @@ function spawnSupervisor() {
 // at function-definition time.
 const _supervisorPidPath = () => path.join(MINIONS_HOME, 'engine', 'supervisor.pid');
 
+/**
+ * Resolve the cold-start restart-health budget (ms) from config, falling back
+ * to ENGINE_DEFAULTS.restartHealthTimeoutMs. Mirrors the Settings clamp range
+ * [15000, 300000] so a config typo can't wedge `minions restart` for an hour
+ * or shrink the budget back below a real cold boot. W-mqpx0tpi.
+ */
+function _resolveRestartHealthTimeoutMs() {
+  const home = process.env.MINIONS_HOME || (typeof MINIONS_HOME !== 'undefined' ? MINIONS_HOME : null);
+  let cfg = null;
+  try {
+    if (home) cfg = JSON.parse(fs.readFileSync(path.join(home, 'config.json'), 'utf8'));
+  } catch { /* config may not exist yet */ }
+  const D = shared.ENGINE_DEFAULTS;
+  const raw = cfg && cfg.engine && Number(cfg.engine.restartHealthTimeoutMs);
+  const resolved = Number.isFinite(raw) && raw > 0 ? raw : D.restartHealthTimeoutMs;
+  return Math.min(300000, Math.max(15000, resolved));
+}
+
 /**
  * Spawn engine + dashboard + supervisor, verify health, optionally open browser.
  * Shared by `minions start` and `minions restart` — restart layers a kill phase
@@ -412,6 +430,7 @@ function spawnFullStackAndVerify({ rest, forceOpen, dashWasUp, restartStartMs })
       minionsHome: MINIONS_HOME,
       dashboardPid: dashProc.pid,
       dashboardPort: actualPort,
+      timeoutMs: _resolveRestartHealthTimeoutMs(),
     });
     if (!result.ok) {
       console.error(formatRestartHealthError(result));
@@ -720,7 +739,13 @@ const DASHBOARD_PORT = resolveDashboardPort(rest).port;
 // spawning dashboard.js.
 process.env.MINIONS_PORT = String(DASHBOARD_PORT);
 const POST_UPDATE_INIT_TIMEOUT_MS = 120000;
-const POST_UPDATE_RESTART_TIMEOUT_MS = 60000;
+// W-mqpx0tpi — the post-update `minions restart` runs as a child of `minions
+// update` under this wall-clock cap. It must outlive the restart-health budget
+// (now up to ~60s for a cold post-`npm install` dashboard boot) plus spawn +
+// port-file-wait overhead, or the parent would SIGKILL a perfectly healthy
+// slow boot and print a scary failure. Give comfortable headroom above the
+// resolved health timeout.
+const POST_UPDATE_RESTART_TIMEOUT_MS = Math.max(120000, _resolveRestartHealthTimeoutMs() + 60000);
 
 function isSubpath(parent, child) {
   const rel = path.relative(path.resolve(parent), path.resolve(child));
@@ -1042,7 +1067,9 @@ function runPostUpdateRestart() {
     console.error(`\n  ERROR: Post-update restart failed (${detail}).`);
   }
   console.error('  Runtime files were synchronized, but the engine/dashboard were not restarted.');
-  console.error('  Run this command to finish the update without using the Windows command shim:');
+  console.error(`  If this was a timeout, the dashboard may still be finishing a cold start —`);
+  console.error(`  re-check http://localhost:${DASHBOARD_PORT} or run \`minions status\` first.`);
+  console.error('  If it is genuinely down, run this command to finish the update:');
   console.error(`    ${formatPackageCliCommand(args)}\n`);
   process.exit(1);
 }

package/dashboard/js/render-other.js

@@ -513,14 +513,37 @@ function _scanSelectNone() {
   document.querySelectorAll('[data-scan-idx]').forEach(function(cb) { if (!cb.disabled) cb.checked = false; });
 }
 
+// Stamp a per-repo Added/Failed status onto a scan-result row. Uses DOM
+// construction with textContent (no innerHTML) so server-provided error text
+// is rendered safely without tripping the no-unsanitized lint gate.
+function _markScanRow(label, ok, text) {
+  if (!label) return;
+  var prev = label.querySelector('.scan-row-status');
+  if (prev) prev.remove();
+  label.style.borderColor = ok ? 'var(--green)' : 'var(--red)';
+  var badge = document.createElement('span');
+  badge.className = 'scan-row-status';
+  badge.style.flex = '0 0 auto';
+  badge.style.marginLeft = '8px';
+  badge.style.maxWidth = '45%';
+  badge.style.fontSize = 'var(--text-sm)';
+  badge.style.fontWeight = '600';
+  badge.style.textAlign = 'right';
+  badge.style.color = ok ? 'var(--green)' : 'var(--red)';
+  badge.textContent = (ok ? '✓ ' : '✗ ') + text;
+  label.appendChild(badge);
+}
+
 async function _addSelectedProjects() {
-  var checkboxes = document.querySelectorAll('[data-scan-idx]:checked:not(:disabled)');
+  var checkboxes = Array.prototype.slice.call(document.querySelectorAll('[data-scan-idx]:checked:not(:disabled)'));
   if (checkboxes.length === 0) { alert('Select at least one repo'); return; }
   var repos = window._scanRepos || [];
   var added = 0;
+  var failed = 0;
   for (var cb of checkboxes) {
     var repo = repos[parseInt(cb.dataset.scanIdx)];
     if (!repo) continue;
+    var label = cb.closest('label');
     try {
       var res = await fetch('/api/projects/add', {
         method: 'POST', headers: { 'Content-Type': 'application/json' },
@@ -537,11 +560,21 @@ async function _addSelectedProjects() {
           localPath: data.path || repo.path,
         });
         cb.disabled = true;
-        cb.closest('label').style.opacity = '0.5';
-        showToast('scan-toast', added + ' project(s) added', true);
+        cb.checked = true;
+        if (label) { label.style.opacity = '0.5'; _markScanRow(label, true, 'Added'); }
+      } else {
+        failed++;
+        if (label) _markScanRow(label, false, 'Failed: ' + (data.error || ('HTTP ' + res.status)));
       }
-    } catch { /* continue with next */ }
+    } catch (e) {
+      failed++;
+      if (label) _markScanRow(label, false, 'Failed: ' + ((e && e.message) ? e.message : 'network error'));
+    }
   }
+  // Summary toast: success styling only when everything added cleanly; any
+  // failure flips it to the error color so the count is unmistakable.
+  var summary = added + ' added' + (failed ? ', ' + failed + ' failed' : '');
+  showToast('scan-toast', summary, added > 0 && failed === 0);
   if (added > 0) {
     refresh();
   }

package/dashboard/js/render-work-items.js

@@ -894,13 +894,11 @@ function _wiRenderDetail(item) {
   }
   if (artPills) html += field('Artifacts', '<div style="display:flex;flex-wrap:wrap;gap:4px">' + artPills + '</div>');
 
-  // P-d5a6f7c4 (Harness Transparency, Stage 3 — surface). Render the grounded
-  // harness usage the agent self-reported and the engine cross-checked. Shape:
-  // { skills:[{name,source,path,grounded}], mcpServers:[{name,scope,grounded}],
-  //   commands:[{name,scope,grounded}], docs:[{path,why,grounded}] }. Entries
-  // with grounded:false are KEPT and visually distinguished — they flag a claim
-  // the engine has no record of exposing (stale path, renamed skill, out-of-band
-  // tool, or hallucination) for a human to adjudicate.
+  // P-d5a6f7c4 (Harness Transparency, Stage 3 — surface). Render the harness
+  // usage the agent self-reported. Shape:
+  // { skills:[{name,source,path}], mcpServers:[{name,scope}],
+  //   commands:[{name,scope}], docs:[{path,why}] }. Every entry renders as a
+  // plain solid pill; the engine's internal grounding flag is not surfaced.
   (function() {
     var hu = item._harnessUsed;
     if (!hu || typeof hu !== 'object') return;
@@ -911,35 +909,23 @@ function _wiRenderDetail(item) {
       { key: 'docs', icon: '📄', label: 'Doc', primary: 'path', secondary: 'why' },
     ];
     var pills = '';
-    var anyUngrounded = false;
+    var pStyle = 'display:inline-flex;align-items:center;gap:4px;padding:2px 8px;border-radius:10px;font-size:var(--text-sm);background:var(--surface2);border:1px solid var(--border);color:var(--text)';
     kinds.forEach(function(k) {
       var entries = Array.isArray(hu[k.key]) ? hu[k.key] : [];
       entries.forEach(function(e) {
         if (!e || typeof e !== 'object') return;
         var primary = e[k.primary];
         if (typeof primary !== 'string' || !primary) return;
-        var grounded = e.grounded === true;
-        if (!grounded) anyUngrounded = true;
         var secondary = (typeof e[k.secondary] === 'string') ? e[k.secondary] : '';
-        // grounded → solid surface; ungrounded → dashed yellow border + ⚠ marker
-        var pStyle = grounded
-          ? 'display:inline-flex;align-items:center;gap:4px;padding:2px 8px;border-radius:10px;font-size:var(--text-sm);background:var(--surface2);border:1px solid var(--border);color:var(--text)'
-          : 'display:inline-flex;align-items:center;gap:4px;padding:2px 8px;border-radius:10px;font-size:var(--text-sm);background:rgba(210,153,34,0.08);border:1px dashed var(--yellow);color:var(--text)';
-        var title = grounded
-          ? k.label + ' — engine confirmed this affordance was exposed' + (secondary ? ' (' + secondary + ')' : '')
-          : k.label + ' — NOT grounded: the agent reports using this but the engine has no record of exposing it' + (secondary ? ' (' + secondary + ')' : '');
+        var title = k.label + (secondary ? ' (' + secondary + ')' : '');
         pills += '<span style="' + pStyle + '" title="' + escapeHtml(title) + '">'
           + k.icon + ' ' + escapeHtml(primary)
           + (secondary ? ' <span style="color:var(--muted);font-size:var(--text-xs)">' + escapeHtml(secondary) + '</span>' : '')
-          + (grounded ? '' : ' <span style="color:var(--yellow);font-weight:700" title="not grounded">&#x26A0;</span>')
           + '</span> ';
       });
     });
     if (!pills) return;
-    var legend = anyUngrounded
-      ? '<div style="font-size:var(--text-xs);color:var(--muted);margin-top:4px">&#x26A0; dashed = agent-reported, not verified by the engine</div>'
-      : '';
-    html += field('Repo harnesses used', '<div style="display:flex;flex-wrap:wrap;gap:4px">' + pills + '</div>' + legend);
+    html += field('Repo harnesses used', '<div style="display:flex;flex-wrap:wrap;gap:4px">' + pills + '</div>');
   })();
 
   // P-34fa5d79 — Mentions: notes whose YAML frontmatter cites this WI

package/dashboard/js/settings.js

@@ -381,6 +381,7 @@ async function openSettings() {
       settingsField('Worktree Create Retries', 'set-worktreeCreateRetries', e.worktreeCreateRetries || 1, '', 'Retry count for transient worktree add failures (0-3)') +
       settingsField('Worktree Root', 'set-worktreeRoot', e.worktreeRoot || '../worktrees', '', 'Relative or absolute path for git worktrees; on Windows prefer a short path like C:\\wt') +
       settingsField('Assert-Clean Status Probe Timeout', 'set-assertCleanStatusTimeoutMs', e.assertCleanStatusTimeoutMs || 10000, 'ms', 'Timeout for the `git status --porcelain` preflight probe in assertCleanSharedWorktree. Raise this (e.g. 60000) on GVFS/Plastic-backed monorepos where sparse hydration runs longer than the 10s default. On timeout the engine quarantines the bad worktree and emits a RETRYABLE failure so the next dispatch starts fresh. Clamped 1000–120000ms.') +
+      settingsField('Restart-health Timeout', 'set-restartHealthTimeoutMs', e.restartHealthTimeoutMs || 60000, 'ms', 'Cold-start budget for `minions restart` / post-update restart verification. The dashboard runs node:sqlite migrations + SPA HTML assembly + initial state reads synchronously BEFORE it binds its port, so right after `npm install` on a slow/loaded box the PID is alive but the port is unbound for tens of seconds. Below this budget that no longer prints a false "Restart verification failed" + exit(1) — the verifier keeps polling until the port listens. A genuinely crashed spawn (PID dies) still fails fast, well under the full budget. Clamped 15000–300000ms.') +
       settingsField('Orphan-holder scan timeout', 'set-orphanHolderScanTimeoutMs', e.orphanHolderScanTimeoutMs || 5000, 'ms', 'Cap on the cross-platform scan (PowerShell / /proc walk / lsof) that identifies the OS process holding a stuck worktree\'s cwd. Bumps up only matter on heavily-loaded hosts where the holder scan races the sweep tick. Clamped 1000–30000ms.') +
       settingsField('Worktree-holder reap probe timeout', 'set-statusProbeKillTimeoutMs', e.statusProbeKillTimeoutMs || 12000, 'ms', 'Windows-only. Timeout for the pre-quarantine worktree-holder reap probe (legacy git.exe-cmdline sweep + PEB-CWD scan that kills an orphaned agent process tree whose CWD pins the worktree dir, causing EBUSY on rename AND `git worktree remove --force`). The old hardcoded 2000ms was the proximate cause of the reaper being a no-op under concurrent-agent load (PowerShell cold-start + process enumeration exceeded 2s → ETIMEDOUT → reaped nothing). ETIMEDOUT is always swallowed (reap nothing; quarantine still proceeds), so raising this only widens the success window. Clamped 2000–60000ms.') +
     '</div>';
@@ -983,6 +984,7 @@ async function saveSettings() {
       worktreeCreateRetries: document.getElementById('set-worktreeCreateRetries').value,
       worktreeRoot: document.getElementById('set-worktreeRoot').value,
       assertCleanStatusTimeoutMs: document.getElementById('set-assertCleanStatusTimeoutMs').value,
+      restartHealthTimeoutMs: document.getElementById('set-restartHealthTimeoutMs')?.value,
       idleAlertMinutes: document.getElementById('set-idleAlertMinutes').value,
       shutdownTimeout: document.getElementById('set-shutdownTimeout').value,
       restartGracePeriod: document.getElementById('set-restartGracePeriod').value,

package/dashboard.js

@@ -10525,6 +10525,12 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           // 2min ceiling (covers even a GVFS-backed sparse hydration without
           // letting a config typo wedge dispatch for an hour).
           assertCleanStatusTimeoutMs: [1000, 120000],
+          // W-mqpx0tpi — cold-start restart-health budget. 15s floor (anything
+          // shorter re-introduces the false-failure bug on a post-`npm install`
+          // dashboard boot); 5min ceiling (a config typo shouldn't let a wedged
+          // boot hang `minions restart` indefinitely — a dead PID still fails
+          // fast well before the budget).
+          restartHealthTimeoutMs: [15000, 300000],
           // W-mq6f2fe0000557fa — cap on the cross-platform holder scan for the
           // orphan-worktree GC. 1s floor (PowerShell startup alone is 0.5–1s);
           // 30s ceiling (the scan runs once per orphan-sweep tick and a slow

package/docs/completion-reports.md

@@ -261,10 +261,27 @@ Defined in `engine/shared.js` as `FAILURE_CLASS`. Use the canonical hyphenated s
 | `out-of-context` | Context window exhausted | Flag for human review |
 | `max-turns` | Claude CLI `error_max_turns` — work in progress | Retry same agent |
 | `completion-nonce-mismatch` | Completion JSON missing or mismatched `nonce` (forged completion). See [Trust boundary](#trust-boundary). | Never retry (untrusted) |
+| `worktree-preflight` | Pre-spawn worktree validation rejected the dispatch (nested-in-project, drive-root collapse, missing base). See [Pre-spawn preflight vs agent failure](#pre-spawn-preflight-vs-agent-failure). | Never retry |
+| `live-checkout-dirty` | Live-checkout project tree had uncommitted changes; engine refused to spawn in-place. See [Pre-spawn preflight vs agent failure](#pre-spawn-preflight-vs-agent-failure). | Never retry |
+| `workspace-manifest-repo-forbidden` | Dispatch routed an agent to a repo not in its `workspace_manifest.allowed_repos`. See [Pre-spawn preflight vs agent failure](#pre-spawn-preflight-vs-agent-failure). | Never retry |
 | `unknown` | Unclassified failure | Default retry logic |
 
 Use `"N/A"` when `status` is `success` or `partial` without a failure.
 
+## Pre-spawn preflight vs agent failure
+
+A handful of `failure_class` values are written by the **engine at dispatch time**, *before the agent process is ever spawned*. They are emitted from `spawnAgent` (`engine.js`) while it sets up the worktree, validates the checkout, or enforces the workspace manifest — the engine calls `completeDispatch(... DISPATCH_RESULT.ERROR ...)` and returns without launching any runtime. **A completion report carrying one of these classes does not imply the agent ran any work**; no prompt was sent, no edits were attempted, and there is no agent-authored `note` or output to interpret.
+
+| `failure_class` | Pre-spawn trigger | `engine/shared.js` |
+|---|---|---|
+| `worktree-preflight` | Worktree placement validation failed: the worktree would nest inside the project, the resolved root collapsed to a drive root, or the base directory was missing. | `FAILURE_CLASS.WORKTREE_PREFLIGHT` (~`shared.js:4279`) |
+| `live-checkout-dirty` | Live-checkout mode (`project.checkoutMode: 'live'`) found uncommitted changes in `project.localPath`; the engine never `reset`/`clean`s the operator tree, so it refuses to spawn. | `FAILURE_CLASS.LIVE_CHECKOUT_DIRTY` (~`shared.js:4289`) |
+| `workspace-manifest-repo-forbidden` | The dispatch routed the agent to a repo not listed in its `workspace_manifest.allowed_repos`. Structural — widen the manifest or route the work elsewhere. | `FAILURE_CLASS.WORKSPACE_MANIFEST_REPO` (~`shared.js:4292`) |
+
+`WORKTREE_ROOTDIR_COLLAPSED_TO_DRIVE_ROOT` is **not** a standalone enum value: it is an `Error.code` thrown by the worktree path resolver (`shared.js`) which `spawnAgent` catches and maps to the non-retryable `worktree-preflight` class (`engine.js`). It surfaces in logs/diagnostics, but the report's `failure_class` is always `worktree-preflight`.
+
+All three classes are **never retryable** — they signal a structural/environment problem the same agent would hit again. Resolve the underlying cause (clean the live tree, fix the worktree root, widen the manifest) before re-dispatching.
+
 ## No-op semantics
 
 A no-op completion declares that the agent correctly **declined** to do the work — the change was already shipped on master, the dispatch premise was wrong, the flagged review comment was an author-note, etc.

package/docs/worktree-lifecycle.md

@@ -7,7 +7,7 @@ the **quarantine path** (dirty/divergent → quarantine dir + retry), and the
 Lifecycle keeps the cross-cutting invariants; the detail lives here.
 
 > Source of truth: `engine/worktree-pool.js`, `engine/shared.js#removeWorktree`
-> + `_retryFsOp`, `engine.js` (`_quarantineDirtyWorktree`, `_renameWithRetry`,
+> + `_retryFsOp`, `engine.js` (`_quarantineDirtyWorktree`,
 > `_killGitDescendantsForWorktree`, `pruneOrphanWorktrees*`, `gcDispatchWorktreeIfOrphan`),
 > `engine/cleanup.js`. Last verified: 2026-06-09.
 
@@ -93,11 +93,15 @@ the `.git/index.lock` acquire around the untracked-cache refresh inside
 place. **Most incidents are closed by 1b alone.**
 Toggle: `ENGINE_DEFAULTS.statusProbeUseNoOptionalLocks` (default `true`).
 
-### Layer 1a — `_renameWithRetry` with jittered backoff
+### Layer 1a — quarantine rename via `shared._retryFsOp` with jittered backoff
 
-6 attempts × 250 ms base × 2^N exponential + 200 ms random jitter
-(~16 s worst-case). Only retries on `EBUSY|EPERM|EACCES|ENOTEMPTY`;
-rethrows other codes immediately. Toggles:
+The quarantine rename (`fs.renameSync(worktreePath, quarantinedPath)`) is wrapped
+in `shared._retryFsOp` (P-a1c4f7e2 collapsed the former bespoke
+`engine.js#_renameWithRetry` into the shared helper). 6 attempts × 250 ms base ×
+2^N exponential + 200 ms random jitter (~16 s worst-case). Only retries on
+`EBUSY|EPERM|EACCES|ENOTEMPTY` (`shared._WORKTREE_RETRYABLE_CODES`); rethrows
+other codes immediately. `_quarantineDirtyWorktree` passes the rename-specific
+budget explicitly. Toggles:
 `ENGINE_DEFAULTS.quarantineRenameRetryAttempts` (6),
 `quarantineRenameRetryBaseMs` (250).
 

package/engine/cleanup.js

@@ -1591,6 +1591,34 @@ function runPeriodicWorktreeSweep(config) {
   let scanned = 0, kept = 0, evicted = 0, failed = 0, outOfRootEvicted = 0, prunedRegistry = 0;
   let missingDirReclaimed = 0, missingDirSkippedLive = 0;
   const _writeToInbox = (a, s, c) => { try { return shared.writeToInbox(a, s, c); } catch (_e) { return false; } };
+
+  // P-d8f1a3c6 — shell `git worktree list --porcelain` at most once per project
+  // per tick and share the parsed trees with BOTH registry-based pruners
+  // (out-of-root + missing-dir reclaim) instead of each self-shelling. Keyed on
+  // the resolved localPath so projects sharing a parent repo only list once. A
+  // project missing from the map (list/shell failure here) falls back to the
+  // consumer's own self-shelling path. `pruneOrphanWorktrees` (r1, fs-readdir
+  // based) never lists and is unaffected.
+  const parsedTreesByProject = new Map();
+  for (const project of projects) {
+    if (!project || !project.localPath) continue;
+    let rootDir;
+    try { rootDir = path.resolve(String(project.localPath)); } catch { continue; }
+    if (parsedTreesByProject.has(rootDir)) continue; // dedup shared-parent projects
+    let rootExists = false;
+    try { rootExists = fs.existsSync(rootDir); } catch { rootExists = false; }
+    if (!rootExists) continue;
+    try {
+      const raw = String(shared.execSilent('git --no-optional-locks worktree list --porcelain', {
+        cwd: rootDir, timeout: 15000, windowsHide: true,
+      }) || '');
+      parsedTreesByProject.set(rootDir, shared.parseWorktreePorcelain(raw));
+    } catch (e) {
+      // Leave unset → the consumer self-shells (existing fallback path).
+      log('warn', `worktree-gc periodic list ${project.name || rootDir}: ${e.message}`);
+    }
+  }
+
   try {
     const r1 = worktreeGc.pruneOrphanWorktrees({
       projects, dispatchSnap, worktreeRootRel, log: _log, config, writeToInbox: _writeToInbox,
@@ -1604,6 +1632,7 @@ function runPeriodicWorktreeSweep(config) {
   try {
     const r2 = worktreeGc.pruneOrphanWorktreesFromGitRegistry({
       projects, dispatchSnap, worktreeRootRel, log: _log, config, writeToInbox: _writeToInbox,
+      parsedTreesByProject,
     });
     scanned += r2.scanned || 0;
     kept += r2.kept || 0;
@@ -1620,7 +1649,7 @@ function runPeriodicWorktreeSweep(config) {
   // interrupted `git worktree add` bricks the branch until a human intervenes.
   try {
     const r3 = worktreeGc.reclaimMissingDirWorktrees({
-      projects, log: _log, config,
+      projects, log: _log, config, parsedTreesByProject,
     });
     missingDirReclaimed += r3.reclaimed || 0;
     missingDirSkippedLive += r3.skippedLive || 0;

package/engine/restart-health.js

@@ -3,9 +3,22 @@ const path = require('path');
 const http = require('http');
 const https = require('https');
 const { execSync } = require('child_process');
+const shared = require('./shared');
 
-const DEFAULT_RESTART_HEALTH_TIMEOUT_MS = 15000;
+// W-mqpx0tpi — single source of truth for the cold-start health budget. The
+// old fixed 15s was too short for a post-`npm install` dashboard boot on a
+// slow/loaded machine: the dashboard runs node:sqlite migrations + SPA HTML
+// assembly + initial state reads SYNCHRONOUSLY before it ever reaches
+// server.listen(), so the PID is alive but the port is unbound for the whole
+// window, tripping a false "Restart verification failed" + exit(1). The knob
+// lives in ENGINE_DEFAULTS.restartHealthTimeoutMs (Settings-configurable);
+// the literal is only a fallback if shared somehow failed to load.
+const DEFAULT_RESTART_HEALTH_TIMEOUT_MS =
+  (shared.ENGINE_DEFAULTS && shared.ENGINE_DEFAULTS.restartHealthTimeoutMs) || 60000;
 const DEFAULT_RESTART_HEALTH_INTERVAL_MS = 250;
+// Consecutive dead-PID reads tolerated before fail-fast. A small guard avoids
+// a single flaky tasklist / kill(0) false-negative aborting a healthy boot.
+const DEFAULT_DEAD_POLLS_BEFORE_FAST_FAIL = 2;
 
 function sleep(ms) {
   return new Promise(resolve => setTimeout(resolve, ms));
@@ -182,9 +195,14 @@ async function waitForRestartHealth(options = {}) {
   const timeoutMs = options.timeoutMs ?? DEFAULT_RESTART_HEALTH_TIMEOUT_MS;
   const intervalMs = options.intervalMs ?? DEFAULT_RESTART_HEALTH_INTERVAL_MS;
   const maxAttempts = normalizePid(options.maxAttempts);
+  const deadPollsBeforeFastFail =
+    Number.isInteger(options.deadPollsBeforeFastFail) && options.deadPollsBeforeFastFail > 0
+      ? options.deadPollsBeforeFastFail
+      : DEFAULT_DEAD_POLLS_BEFORE_FAST_FAIL;
   const started = Date.now();
   let attempts = 0;
   let last = null;
+  let consecutiveDead = 0;
 
   while (true) {
     attempts++;
@@ -192,6 +210,25 @@ async function waitForRestartHealth(options = {}) {
     last.attempts = attempts;
     last.elapsedMs = Date.now() - started;
     if (last.ok) return last;
+
+    // W-mqpx0tpi — distinguish "still starting" from "dead". When the dashboard
+    // PID we just spawned is ALIVE but the port isn't listening yet, keep
+    // waiting out the (now much larger) timeout: that's the legitimate cold
+    // start. But if the PID has DIED, fail FAST — a genuinely crashed spawn
+    // should surface in seconds instead of holding the slot for the full
+    // budget. Only the process-kind check exposes `alive`; the HTTP-kind path
+    // has no PID-liveness signal, so it falls through to the timeout as before.
+    const dash = last.dashboard;
+    if (dash && dash.kind === 'process' && dash.alive === false) {
+      consecutiveDead++;
+      if (consecutiveDead >= deadPollsBeforeFastFail) {
+        last.failedFast = true;
+        return last;
+      }
+    } else {
+      consecutiveDead = 0;
+    }
+
     if (maxAttempts && attempts >= maxAttempts) break;
     const remainingMs = timeoutMs - (Date.now() - started);
     if (!maxAttempts && remainingMs <= 0) break;
@@ -210,7 +247,22 @@ function formatRestartHealthError(result) {
   const elapsed = typeof result.elapsedMs === 'number' ? `${result.elapsedMs}ms` : 'unknown time';
   const attempts = result.attempts || 0;
   const details = (result.errors || ['Unknown restart verification failure']).map(err => `  - ${err}`).join('\n');
-  return `\n  ERROR: Restart verification failed after ${elapsed} (${attempts} attempt${attempts === 1 ? '' : 's'}).\n${details}\n`;
+  // W-mqpx0tpi — when the timeout was hit with the dashboard PID alive but the
+  // port not yet listening, the dashboard is almost certainly still finishing a
+  // cold start rather than broken. Point the operator at a re-check instead of
+  // implying breakage.
+  let guidance = '';
+  const dash = result && result.dashboard;
+  if (dash && dash.kind === 'process' && dash.alive && !dash.listening) {
+    const port = dash.port || 7331;
+    guidance =
+      `\n  The dashboard process is alive but has not yet bound port ${port}.\n` +
+      `  It may still be finishing a cold start — node:sqlite migrations, SPA\n` +
+      `  HTML assembly, and the first state reads all run synchronously before\n` +
+      `  the dashboard reaches server.listen(). Re-check http://localhost:${port}\n` +
+      `  or run \`minions status\` before assuming anything is broken.\n`;
+  }
+  return `\n  ERROR: Restart verification failed after ${elapsed} (${attempts} attempt${attempts === 1 ? '' : 's'}).\n${details}\n${guidance}`;
 }
 
 module.exports = {

package/engine/shared.js

@@ -2032,7 +2032,7 @@ function writeToInbox(agentId, slug, content, _inboxDir, metadata) {
 // ── Process Spawning ────────────────────────────────────────────────────────
 // All child process calls go through these to ensure windowsHide: true
 
-const { execSync: _execSync, spawnSync: _spawnSync, spawn: _spawn, exec: _cbExec, execFile: _cbExecFile } = require('child_process');
+const { execSync: _execSync, execFileSync: _execFileSync, spawnSync: _spawnSync, spawn: _spawn, exec: _cbExec, execFile: _cbExecFile } = require('child_process');
 const { promisify: _promisify } = require('util');
 const _execFileAsync = _promisify(_cbExecFile);
 
@@ -2635,6 +2635,17 @@ const ENGINE_DEFAULTS = {
   // raise this knob (e.g. 60000) before tuning anything else. Clamped to
   // [1000, 120000] in dashboard.js POST /api/settings.
   assertCleanStatusTimeoutMs: 10000,
+  // W-mqpx0tpi — cold-start health budget for `minions restart` / post-update
+  // restart verification (engine/restart-health.js#waitForRestartHealth). The
+  // dashboard runs node:sqlite migrations + SPA HTML assembly + initial state
+  // reads SYNCHRONOUSLY before server.listen(), so right after `npm install`
+  // on a slow/loaded box the PID is alive but port 7331 is unbound well past
+  // the old fixed 15s, producing a false "Restart verification failed" +
+  // exit(1) even though the dashboard comes up healthy moments later. Default
+  // 60s comfortably covers a cold boot; a dead PID still fails fast (the
+  // verifier doesn't wait out the full budget for a crashed spawn). Clamped to
+  // [15000, 300000] in dashboard.js POST /api/settings.
+  restartHealthTimeoutMs: 60000,
   workItemCreateDedupWindowMs: 15 * 60 * 1000, // 15min — collapse duplicate CC/API create races
   idleAlertMinutes: 15,
   restartGracePeriod: 1200000, // 20min
@@ -8296,6 +8307,13 @@ function _writeWorktreeSkipLiveInboxNote(worktreePath, callerTag) {
   } catch { /* best-effort — never throw from the skip-note writer */ }
 }
 
+// P-c7e2b405 — INTENTIONAL divergence from worktree-gc.reapAndRemoveWorktree:
+// this is the low-level `git worktree remove --force` → fs.rmSync → rd /s /q
+// removal primitive WITH its own EBUSY/_retryFsOp backoff loop. The engine-side
+// helper INJECTS this function as its `removeWorktree` and owns the
+// reap/escalate/marker-gate orchestration around it. It is deliberately NOT
+// folded into the helper (shared.js must not import the engine-side reaper —
+// layering boundary).
 function removeWorktree(wtPath, gitRoot, worktreeRoot, opts = {}) {
   const resolved = path.resolve(wtPath);
   const resolvedRoot = path.resolve(worktreeRoot) + path.sep;
@@ -8326,14 +8344,24 @@ function removeWorktree(wtPath, gitRoot, worktreeRoot, opts = {}) {
       return false;
     }
   } catch { /* bad gitRoot — fall through to the .git probe */ }
-  try {
-    const st = fs.lstatSync(path.join(resolved, '.git'));
-    if (st && st.isDirectory()) {
-      log('warn', `removeWorktree: refusing to remove ${wtPath} — it is a real git repo (.git is a directory, not a linked-worktree pointer)`);
-      try { bumpWorktreeGcMetric('refusedRealRepo'); } catch { /* metric optional */ }
-      return false;
-    }
-  } catch { /* no .git, or unreadable — normal worktree husk; continue */ }
+  // P-b3d9a162 — the `.git`-is-a-directory refusal, extracted so it can run at
+  // BOTH the top of the function AND again immediately before the fallback
+  // fs.rmSync. A Windows file-lock can release between the two checks — the
+  // primary `git worktree remove --force` failing on that lock drops us into
+  // the catch, where a freshly-exposed real `.git` directory would otherwise be
+  // wiped. Returns true ⇒ the caller MUST abort (refuse the delete).
+  const _refuseIfRealRepo = (resolved) => {
+    try {
+      const st = fs.lstatSync(path.join(resolved, '.git'));
+      if (st && st.isDirectory()) {
+        log('warn', `removeWorktree: refusing to remove ${wtPath} — it is a real git repo (.git is a directory, not a linked-worktree pointer)`);
+        try { bumpWorktreeGcMetric('refusedRealRepo'); } catch { /* metric optional */ }
+        return true;
+      }
+    } catch { /* no .git, or unreadable — normal worktree husk; continue */ }
+    return false;
+  };
+  if (_refuseIfRealRepo(resolved)) return false;
   // W-mq5rwwss000f30a7 — never wipe a worktree while an agent is actively
   // dispatched inside it. isWorktreePathLive fails OPEN (returns true) when
   // the dispatches table is unreachable, so we err on the side of leaking
@@ -8363,12 +8391,19 @@ function removeWorktree(wtPath, gitRoot, worktreeRoot, opts = {}) {
 
   bumpWorktreeGcMetric('attempts');
   try {
-    exec(`git worktree remove "${wtPath}" --force`, { cwd: gitRoot, stdio: 'pipe', timeout: 15000, windowsHide: true });
+    // P-1d7a4f80 — argv form (shell:false) so wtPath can never be re-parsed by a shell.
+    shellSafeGitSync(['worktree', 'remove', wtPath, '--force'], { cwd: gitRoot, timeout: 15000 });
     _removeWorktreeFailures.delete(resolved);
     bumpWorktreeGcMetric('success');
     return true;
   } catch (gitErr) {
     try {
+      // P-b3d9a162 — re-run the real-repo refusal: a lock that released only
+      // AFTER the top-of-function probe (and made the primary `git worktree
+      // remove` throw above) can expose a real `.git` directory right here.
+      // Refuse before the fallback rmSync so we never recurse-delete a real
+      // repo on the fallback path.
+      if (_refuseIfRealRepo(resolved)) return false;
       // W-mq5o6bvy000x7191 (Layer 1): retry fs.rmSync with exponential backoff
       // for transient Windows file-locks (EPERM/EBUSY/EACCES/ENOTEMPTY) before
       // falling through to rd /s /q. A single AV/Explorer/vscode lock during
@@ -8377,7 +8412,7 @@ function removeWorktree(wtPath, gitRoot, worktreeRoot, opts = {}) {
         () => fs.rmSync(resolved, { recursive: true, force: true }),
         `fs.rmSync(${resolved})`
       );
-      try { exec('git worktree prune', { cwd: gitRoot, stdio: 'pipe', timeout: 10000, windowsHide: true }); } catch {}
+      try { shellSafeGitSync(['worktree', 'prune'], { cwd: gitRoot, timeout: 10000 }); } catch {}
       _removeWorktreeFailures.delete(resolved);
       bumpWorktreeGcMetric('success');
       if (attempt > 1) bumpWorktreeGcMetric('successAfterRetry');
@@ -8387,8 +8422,11 @@ function removeWorktree(wtPath, gitRoot, worktreeRoot, opts = {}) {
       // locked files, and partially-deleted directories (not just EPERM)
       if (process.platform === 'win32') {
         try {
-          exec(`cmd /c rd /s /q "${resolved}"`, { stdio: 'pipe', timeout: 15000, windowsHide: true });
-          try { exec('git worktree prune', { cwd: gitRoot, stdio: 'pipe', timeout: 10000, windowsHide: true }); } catch {}
+          // P-1d7a4f80 — argv form (shell:false). `rd` is a cmd.exe builtin so it
+          // must run via `cmd /c`, but the worktree path is passed as a discrete
+          // argv element rather than interpolated into a shell string.
+          _execFileSync('cmd', ['/c', 'rd', '/s', '/q', resolved], { stdio: 'pipe', timeout: 15000, windowsHide: true });
+          try { shellSafeGitSync(['worktree', 'prune'], { cwd: gitRoot, timeout: 10000 }); } catch {}
           _removeWorktreeFailures.delete(resolved);
           bumpWorktreeGcMetric('success');
           return true;