@yemi33/minions 0.1.2305 → 0.1.2306

package/engine/live-checkout.js

@@ -188,6 +188,65 @@ function _collectAutoCleanablePaths(dirtyFiles) {
   return cleanable.length > 0 ? cleanable : null;
 }
 
+// issue #608 — detects a branch name that the ENGINE created for a live-mode
+// dispatch (never the operator's own branch). Matches ONLY the literal
+// `work/<wi-id>` convention produced by `shared.deriveWorkItemBranchName` —
+// deliberately narrow so an operator's own `user/...`/`feature/...` branch is
+// never mistaken for agent litter. Used by the orphaned-agent-branch self-heal
+// below (prepareLiveCheckout) to recognize a stray branch left behind by an
+// earlier dispatch whose dispatch-end restore did not complete.
+function _looksLikeAgentBranch(name) {
+  return typeof name === 'string' && /^work\//.test(name.trim());
+}
+
+// issue #608 — pull the current local branch name out of the `## <branch>...`
+// header line that `git status --porcelain=v1 -b` already returns, so the
+// orphaned-agent-branch self-heal below needs ZERO extra git calls on the
+// common (non-stray) dirty path — preserving the existing "no extra git calls
+// when the tree isn't all-artifact-cleanable" contract asserted by
+// test/unit/prepare-live-checkout.test.js. Returns '' for a detached HEAD
+// (`## HEAD (no branch)`) or an unparsable header.
+function _extractBranchFromPorcelainHeader(branchInfo) {
+  if (!branchInfo || typeof branchInfo !== 'string') return '';
+  const body = branchInfo.replace(/^##\s*/, '');
+  const firstToken = body.split(' ')[0] || '';
+  const localBranch = firstToken.split('...')[0];
+  return (!localBranch || localBranch === 'HEAD') ? '' : localBranch;
+}
+
+// issue #608 — commit whatever is staged/unstaged onto the CURRENT branch
+// with bounded retry+backoff, specifically to survive a transient
+// `.git/index.lock` collision against a sibling git process (the root cause
+// of the 2026-06-30 incident: two live-checkout dispatches raced `git add -A`
+// / `git commit` against the same working tree, the commit lost the lock race
+// once, and the prior code gave up on the first failure with no retry). Only
+// RETRIES when the failure looks like transient lock contention; any other
+// failure (e.g. "nothing to commit") returns immediately so callers fall
+// through to their existing best-effort handling. Never throws — callers get
+// `{ ok:false, error }` on exhaustion.
+async function _commitAgentWipWithRetry(git, baseOpts, message, options = {}) {
+  const attempts = Number.isFinite(options.attempts) ? options.attempts : 3;
+  const baseDelayMs = Number.isFinite(options.baseDelayMs) ? options.baseDelayMs : 300;
+  const sleep = typeof options.sleep === 'function'
+    ? options.sleep
+    : (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+  let lastErr = null;
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    try {
+      await git(['add', '-A'], baseOpts);
+      await git(['commit', '--no-verify', '-m', message], baseOpts);
+      return { ok: true, attempts: attempt };
+    } catch (e) {
+      lastErr = e;
+      const msg = String((e && e.message) || '');
+      const transientLock = /index\.lock/i.test(msg) || /another git process/i.test(msg);
+      if (!transientLock || attempt === attempts) break;
+      await sleep(baseDelayMs * attempt);
+    }
+  }
+  return { ok: false, error: lastErr, attempts };
+}
+
 // W-mqvejug6000eeb20 — production default for resolving the live-checkout
 // auto-reset decision when the caller (engine.js spawnAgent) does not pass an
 // explicit `autoReset` boolean. engine.js is intentionally not threading the
@@ -237,6 +296,7 @@ async function prepareLiveCheckout(opts = {}) {
     _rm,        // private injection for testing — defaults to fs.rmSync (recursive, force)
     _resolveAutoReset, // private injection for testing — defaults to config-based resolver
     _writeInboxNote,   // private injection for testing — defaults to dispatch.writeInboxAlert
+    _sleep,            // private injection for testing — defaults to a real setTimeout-based sleep
   } = opts;
 
   // ── Required-arg guards. Throw rather than return {ok:false} so a
@@ -319,6 +379,52 @@ async function prepareLiveCheckout(opts = {}) {
         const reRaw = await git(['status', '--porcelain=v1', '-b'], baseOpts);
         ({ branchInfo, dirtyFiles } = parsePorcelain(reRaw));
       }
+      // issue #608 — orphaned-agent-branch self-heal. If the tree is STILL dirty
+      // and HEAD is sitting on a DIFFERENT engine-created branch than the one
+      // THIS dispatch is about to use, the dirt is provably leftover from an
+      // earlier dispatch whose dispatch-end restore never completed (e.g. an
+      // `.git/index.lock` race against a sibling dispatch — see
+      // restoreLiveCheckoutAtDispatchEnd). Left alone, the ORIGINAL-REF CAPTURE
+      // below (Step 3) would adopt that stray branch as `originalRef`, and every
+      // future dispatch would inherit it in turn — the tree never stops
+      // orbiting agent branches and every dispatch fails LIVE_CHECKOUT_DIRTY
+      // forever (321 incidents / 12 days). Since the branch was created BY the
+      // engine (matched narrowly via `_looksLikeAgentBranch` — the literal
+      // `work/<id>` convention from shared.deriveWorkItemBranchName, never the
+      // operator's own branch), committing the leftover WIP there is exactly as
+      // safe as the existing dispatch-end self-heal: additive, fully
+      // recoverable from that branch's own history, and never touches the
+      // operator's real branch. Unconditional (not opt-in) because it is
+      // non-destructive, unlike the auto-reset path below. After committing,
+      // switch back to `mainRef` — the one ref that is always a real,
+      // non-agent baseline — so the tree stops drifting onto agent branches.
+      if (dirtyFiles.length > 0) {
+        const strayBranch = _extractBranchFromPorcelainHeader(branchInfo);
+        if (strayBranch && strayBranch !== branchName && _looksLikeAgentBranch(strayBranch)) {
+          const commitRes = await _commitAgentWipWithRetry(
+            git, baseOpts,
+            `minions: auto-save orphaned WIP from ${strayBranch} (dispatch ${dispatchId || '(unknown)'})`,
+            { sleep: _sleep },
+          );
+          if (commitRes.ok) {
+            logFn(`[live-checkout] self-healed orphaned agent branch '${strayBranch}' — committed WIP` +
+              (commitRes.attempts > 1 ? ` after ${commitRes.attempts} attempts` : '') +
+              `, switching back to '${mainRef}'`, 'info');
+            try {
+              await git(['checkout', mainRef], baseOpts);
+            } catch (backErr) {
+              logFn(`[live-checkout] could not switch back to '${mainRef}' after self-healing '${strayBranch}': ${backErr && backErr.message}`, 'warn');
+            }
+            // Re-run the dirty check. Either the tree is now clean (self-heal
+            // succeeded end-to-end) or something new appeared (rare) — either
+            // way the normal auto-reset / dirty-bail logic below sees fresh state.
+            const healRaw = await git(['status', '--porcelain=v1', '-b'], baseOpts);
+            ({ branchInfo, dirtyFiles } = parsePorcelain(healRaw));
+          } else {
+            logFn(`[live-checkout] could not self-heal orphaned agent branch '${strayBranch}' (commit failed): ${commitRes.error && commitRes.error.message}`, 'warn');
+          }
+        }
+      }
       if (dirtyFiles.length > 0) {
         // W-mqvejug6000eeb20 — opt-in auto-reset. Default behavior is to bail with
         // reason:'dirty' (spawnAgent translates to non-retryable LIVE_CHECKOUT_DIRTY
@@ -641,6 +747,7 @@ async function restoreLiveCheckoutAtDispatchEnd(opts = {}) {
     log,
     writeInboxAlert,
     _git, // private injection for testing — defaults to shared.shellSafeGit
+    _sleep, // private injection for testing — defaults to a real setTimeout-based sleep
   } = opts;
 
   const logFn = (typeof log === 'function') ? log : () => {};
@@ -750,16 +857,27 @@ async function restoreLiveCheckoutAtDispatchEnd(opts = {}) {
           onAgentBranch = cur && cur === branchName;
         } catch { /* best-effort */ }
         if (onAgentBranch) {
-          try {
-            await git(['add', '-A'], baseOpts);
-            // --no-verify: skip operator commit hooks that may fail headless.
-            await git(['commit', '--no-verify', '-m', `minions: auto-save agent WIP (dispatch ${did})`], baseOpts);
+          // issue #608 — bounded retry+backoff on the commit. The 2026-06-30
+          // incident was caused by exactly this commit losing a transient
+          // `.git/index.lock` race against a sibling dispatch's git process;
+          // the previous single-attempt code gave up immediately and left the
+          // stage half-committed, which then perpetuated as a stray agent
+          // branch for every subsequent dispatch (see the orphaned-agent-branch
+          // self-heal in prepareLiveCheckout). `--no-verify` skips operator
+          // commit hooks that may fail headless.
+          const commitRes = await _commitAgentWipWithRetry(
+            git, baseOpts,
+            `minions: auto-save agent WIP (dispatch ${did})`,
+            { sleep: _sleep },
+          );
+          if (commitRes.ok) {
             result.autoCommitted = true;
-            logFn('info', `live-checkout: auto-committed agent WIP onto ${branchName} before restore (dispatch ${did})`);
-          } catch (commitErr) {
+            logFn('info', `live-checkout: auto-committed agent WIP onto ${branchName} before restore (dispatch ${did})` +
+              (commitRes.attempts > 1 ? ` after ${commitRes.attempts} attempts` : ''));
+          } else {
             // Leave the tree as-is; the plain checkout below will refuse and the
             // fallback alert fires. Never force, never discard.
-            logFn('warn', `live-checkout: could not auto-save agent WIP onto ${branchName} for ${did}: ${commitErr && commitErr.message}`);
+            logFn('warn', `live-checkout: could not auto-save agent WIP onto ${branchName} for ${did}: ${commitRes.error && commitRes.error.message}`);
           }
         }
       }
@@ -906,5 +1024,8 @@ module.exports = {
   _isPartialCloneBlobError,
   _isAutoCleanableArtifact,
   _collectAutoCleanablePaths,
+  _looksLikeAgentBranch,
+  _extractBranchFromPorcelainHeader,
+  _commitAgentWipWithRetry,
   LIVE_CHECKOUT_AUTO_CLEAN_PATTERNS,
 };

package/engine/playbook.js

@@ -13,7 +13,7 @@ const { wrapUntrusted, buildSource } = require('./untrusted-fence');
 const { MINIONS_BRAND_URL } = require('./comment-format');
 
 const { safeJson, safeRead, getProjects, log, ts, dateStamp, truncateTextBytes, ENGINE_DEFAULTS, WI_STATUS, WORK_TYPE, PR_STATUS, DISPATCH_RESULT, getProjectOrg } = shared;
-const { getConfig, getDispatch, getNotes, getAgentCharter, getPrs, getKnowledgeBaseIndex, AGENTS_DIR } = queries;
+const { getConfig, getDispatch, getNotes, getPrs, getKnowledgeBaseIndex, AGENTS_DIR } = queries;
 
 const MINIONS_DIR = shared.MINIONS_DIR;
 const PLAYBOOKS_DIR = path.join(MINIONS_DIR, 'playbooks');
@@ -1052,7 +1052,7 @@ function _checkPlaybookSections(content, context = '') {
 // Lean system prompt: agent identity + rules only (~2-4KB, never grows)
 function buildSystemPrompt(agentId, config, project) {
   const agent = config.agents[agentId] || tempAgents.get(agentId) || { name: agentId, role: 'Temporary Agent', expertise: [] };
-  const charter = getAgentCharter(agentId); // returns '' for temp agents (no charter file)
+  const charter = safeRead(path.join(AGENTS_DIR, agentId, 'charter.md')); // returns '' for temp agents (no charter file)
   project = project || getProjects(config)[0] || {};
 
   let prompt = '';

package/engine/queries.js

@@ -722,10 +722,6 @@ function getAgentStatus(agentId) {
 // setAgentStatus removed — agent status is derived from dispatch.json.
 // Status.json files no longer exist.
 
-function getAgentCharter(agentId) {
-  return safeRead(path.join(AGENTS_DIR, agentId, 'charter.md'));
-}
-
 function getAgents(config) {
   config = config || getConfig();
   // Fall back to DEFAULT_AGENTS if config has no agents (uninitialized repo)
@@ -2063,13 +2059,21 @@ function getWorkItems(config, opts) {
   });
 
   const cacheMtimes = _snapshotWorkItemsMtimes(config);
+  // Use Date.now() here (not the `now` captured at function entry) so the
+  // 1 s TTL is measured from when the cache was BUILT, not from when the
+  // call started. On a slow or loaded machine the first cold call can take
+  // > 1 s while DB migrations run; if we used the entry-time `now`, the
+  // very next call would see (entry_time_of_call_2 − entry_time_of_call_1)
+  // >= 1 000 ms and miss the cache, defeating the cache entirely.
+  // (W-mr00aooc000i1d6b — queries-work-items-cache CI failure on slow runners)
+  const cacheSetAt = Date.now();
   if (enrich) {
     _workItemsCache = allItems;
-    _workItemsCacheAt = now;
+    _workItemsCacheAt = cacheSetAt;
     _workItemsCacheMtimes = cacheMtimes;
   } else {
     _workItemsLeanCache = allItems;
-    _workItemsLeanCacheAt = now;
+    _workItemsLeanCacheAt = cacheSetAt;
     _workItemsLeanCacheMtimes = cacheMtimes;
   }
   return allItems;
@@ -3320,7 +3324,7 @@ module.exports = {
   _buildNotesByWiMap, // exported for testing
 
   // Agents
-  getAgentStatus, getAgentCharter, getAgents, getAgentDetail,
+  getAgentStatus, getAgents, getAgentDetail,
 
   // Pull requests
   getPrs, getPullRequests,

package/engine/shared.js

@@ -3254,11 +3254,12 @@ const ENGINE_DEFAULTS = {
   // When ON, a dirty/broken live-checkout tree is `git fetch origin` +
   // `git reset --hard origin/<branch>`'d before dispatch instead of failing
   // LIVE_CHECKOUT_DIRTY. Per-project `project.liveCheckoutAutoReset` overrides
-  // this. Default OFF — auto-reset is destructive (it discards the operator's
-  // uncommitted changes), so it is strictly opt-in. Resolution precedence lives
-  // in `resolveLiveCheckoutAutoReset`. Fires ONLY on confirmed dirty-tree
-  // detection, never on mid-operation / blob-fetch / tooling failures.
-  liveCheckoutAutoReset: false,
+  // this. Default ON — discarding uncommitted dirt via reset-to-remote keeps
+  // live-checkout branches from diverging (the old `false` default accumulated
+  // `minions: auto-save agent WIP` commits on every dirty exit). Resolution
+  // precedence lives in `resolveLiveCheckoutAutoReset`. Fires ONLY on confirmed
+  // dirty-tree detection, never on mid-operation / blob-fetch / tooling failures.
+  liveCheckoutAutoReset: true,
   orphanHolderScanTimeoutMs: 5000,          // 5s ceiling for the cross-platform holder scan (PowerShell / /proc walk / lsof)
   ccMaxTurns: 50, // max tool-use turns per CC/doc-chat call before CLI stops (per response, not per session)
   ccWorkerIdleTimeoutMs: 30 * 60 * 1000, // W-mr0qs0vw: idle-reaper window for the persistent `copilot --acp` worker pool (engine/cc-worker-pool.js). After this much inactivity with no in-flight turn the warm ACP process is killed; the next message cold-spawns a fresh session with NO memory of prior turns (CC shows a "context cleared after inactivity" notice). Tradeoff: shorter = less idle memory/process footprint, longer = more context durability across gaps between messages. Wired into the pool via ccWorkerPool.setIdleTimeoutMs() on every reloadConfig(); clamped to [60000, 28800000] (1min–8h) in the settings POST handler.

package/engine/supervisor.js

@@ -5,7 +5,14 @@
  * Spawned `detached: true` by `minions start`/`restart` after the engine and
  * dashboard are up. Polls every SUPERVISOR_INTERVAL_MS:
  *   - engine PID from `engine/control.json`
- *   - dashboard PID via port-listener probe (port 7331 by default)
+ *   - dashboard via a port-listener probe (port 7331 by default) AND, when the
+ *     port is bound, an HTTP `/api/health` probe. The HTTP layer catches the
+ *     "frozen but still listening" dashboard (wedged event loop) that the
+ *     port-listen probe alone reports as healthy — it respawns only after
+ *     DASH_HEALTH_MAX_FAILS consecutive failed probes so a dashboard merely
+ *     busy with a heavy synchronous getStatus() rebuild isn't killed. What
+ *     counts as "responsive" (and why engine 'degraded'/'stopped' does NOT mean
+ *     the dashboard is frozen) is documented at _probeDashboardHealth.
  *
  * When either is dead AND the stop-intent flag is NOT set, respawns the dead
  * one in the same way the CLI does (detached, stdio routed to the engine-
@@ -76,6 +83,16 @@ function _resolveDashPort() {
 const POST_SPAWN_GRACE_MS = Number(process.env.MINIONS_SUPERVISOR_GRACE_MS) || 15000;
 // #421 — heartbeat age threshold before supervisor considers the engine event loop frozen.
 const SUPERVISOR_STALE_ENGINE_HEARTBEAT_MS = Number(process.env.MINIONS_SUPERVISOR_STALE_HEARTBEAT_MS) || 180000; // 3 min
+// Dashboard HTTP liveness (frozen-but-listening detection). A dashboard whose
+// event loop is wedged keeps the socket LISTENING, so the port-listen probe
+// alone reports it healthy while the in-browser SPA shows the "unreachable"
+// banner forever. We layer an HTTP /api/health probe on top: only respawn after
+// DASH_HEALTH_MAX_FAILS *consecutive* failed probes so a dashboard that is
+// merely busy with a heavy synchronous getStatus() rebuild (documented to block
+// the loop 15-25s) isn't mistaken for a hang. With the default 30s interval,
+// 3 strikes ≈ 90s of continuous unresponsiveness before we act.
+const DASH_HEALTH_TIMEOUT_MS = Number(process.env.MINIONS_SUPERVISOR_DASH_HEALTH_TIMEOUT_MS) || 5000;
+const DASH_HEALTH_MAX_FAILS = Number(process.env.MINIONS_SUPERVISOR_DASH_HEALTH_FAILS) || 3;
 const isWin = process.platform === 'win32';
 
 function safeReadJson(p) {
@@ -354,6 +371,39 @@ function spawnDashboard() {
 // the engine.
 let _lastEngineRespawnAt = 0;
 let _lastDashboardRespawnAt = 0;
+// Consecutive failed dashboard HTTP health probes. Reset on any healthy probe,
+// after a respawn, and inside the post-spawn grace window.
+let _dashHealthFailStreak = 0;
+
+// Lazy, defensive HTTP health probe. Reuses restart-health.js's httpGetJson
+// (rule: reuse before re-implementing) but never lets a load failure (e.g. a
+// mid-upgrade broken shared.js that restart-health requires at module top)
+// break the supervisor. Returns null when the probe helper is unavailable so
+// the caller can FALL BACK to port-only liveness instead of false-respawning a
+// healthy dashboard.
+function _probeDashboardHealth(port, timeoutMs = DASH_HEALTH_TIMEOUT_MS) {
+  let getJson = null;
+  try {
+    const rh = require('./restart-health');
+    if (rh && rh._private && typeof rh._private.httpGetJson === 'function') {
+      getJson = rh._private.httpGetJson;
+    }
+  } catch { /* restart-health/shared unavailable — fall through */ }
+  if (!getJson) return Promise.resolve(null);
+  return getJson(`http://127.0.0.1:${port}/api/health`, timeoutMs)
+    // "Responsive" == the dashboard event loop executed handleHealth and returned
+    // a well-formed 2xx envelope, REGARDLESS of the engine-derived status value.
+    // /api/health reports 'degraded' when the engine is paused/stopping and
+    // 'stopped' when the engine is down — those are legitimate ENGINE states
+    // (owned by checkEngine/checkEngineHung), not evidence the DASHBOARD process
+    // is frozen. Gating on status==='healthy' would respawn a perfectly
+    // responsive dashboard every time an operator pauses the engine, tearing
+    // down the socket and tripping the in-browser "unreachable" banner for no
+    // reason. Only a failed/timed-out request (res.ok false or a rejection)
+    // means the dashboard's own event loop is actually wedged.
+    .then(res => !!(res && res.ok && res.json && typeof res.json.status === 'string'))
+    .catch(() => false);
+}
 
 // Window during which a `null` pid + recent `restarted_at` is interpreted as
 // "another watchdog is currently respawning the engine — don't double-spawn."
@@ -364,12 +414,29 @@ let _lastDashboardRespawnAt = 0;
 // to enter cli.js:443 and write its own PID on cold Windows boots.
 const RESPAWN_IN_PROGRESS_WINDOW_MS = Number(process.env.MINIONS_SUPERVISOR_RESPAWN_WINDOW_MS) || 60000;
 
+// #3758 — 'degraded' is a FAILURE state (set by dashboard.js's frozen-tick
+// watchdog, see dashboard.js#_markEngineAsDegradedIfFrozen), not a deliberate
+// user-intent state like 'paused'/'stopping'/'stopped'. When a frozen tick loop
+// finally unblocks, engine.js#tickInner reads control.state !== 'running' and
+// calls process.exit(0) — self-exiting exactly BECAUSE it saw 'degraded'. The
+// dashboard.js comment documents the expected recovery: "the PID-dead watchdog
+// then auto-restarts it." Excluding 'degraded' here left that promise unmet —
+// the engine PID goes away and the control plane silently stays down until a
+// manual `minions restart`. Respawn eligibility must include both 'running'
+// (still up) and 'degraded' (crashed/crashing out of a real failure); only
+// 'paused', 'stopping', and 'stopped' reflect actual user intent to stay down.
+function _isRespawnEligibleEngineState(state) {
+  return state === 'running' || state === 'degraded';
+}
+
 function checkEngine(now) {
   if (now - _lastEngineRespawnAt < POST_SPAWN_GRACE_MS) return;
   const control = safeReadJson(CONTROL_PATH_FN());
-  // Only respawn when control.json says "running" — paused/stopped/stopping
-  // are legitimate states the supervisor must not override.
-  if (!control || control.state !== 'running') return;
+  // Respawn when control.json says "running" (PID died unexpectedly) or
+  // "degraded" (watchdog-flagged failure state — see _isRespawnEligibleEngineState
+  // above). "paused"/"stopped"/"stopping" are legitimate user-intent states the
+  // supervisor must not override.
+  if (!control || !_isRespawnEligibleEngineState(control.state)) return;
   if (control.pid && isPidAlive(control.pid)) return;
 
   // Cross-watchdog race guard: dashboard.js's in-process engine watchdog
@@ -403,7 +470,11 @@ function checkEngine(now) {
 function checkEngineHung(now) {
   if (now - _lastEngineRespawnAt < POST_SPAWN_GRACE_MS) return;
   const control = safeReadJson(CONTROL_PATH_FN());
-  if (!control || control.state !== 'running') return;
+  // Include 'degraded' (see _isRespawnEligibleEngineState) so a permanently
+  // frozen tick loop that never gets a chance to self-exit (tickInner never
+  // re-enters) still gets force-restarted once its own heartbeat goes stale,
+  // instead of being ignored forever the moment the state flips to 'degraded'.
+  if (!control || !_isRespawnEligibleEngineState(control.state)) return;
   // Only acts when the PID is alive — a dead PID is handled by checkEngine().
   if (!control.pid || !isPidAlive(control.pid)) return;
 
@@ -424,31 +495,69 @@ function checkEngineHung(now) {
   console.log(`[supervisor] Engine restarted due to stale heartbeat (new PID: ${newPid})`);
 }
 
-function checkDashboard(now) {
-  if (now - _lastDashboardRespawnAt < POST_SPAWN_GRACE_MS) return;
+async function checkDashboard(now) {
+  if (now - _lastDashboardRespawnAt < POST_SPAWN_GRACE_MS) { _dashHealthFailStreak = 0; return; }
   const dashPort = _resolveDashPort();
   const pids = listeningPidsForPort(dashPort);
-  if (pids.length > 0) return;
-
-  console.log(`[supervisor] Dashboard not listening on port ${dashPort} — respawning...`);
-  // Reap stray dashboards first. Besides bounding the count, this collapses the
-  // port-desync case: orphan dashboards holding other ports are killed, freeing
-  // the canonical port for the fresh one whose beacon _resolveDashPort() reads.
-  reapStrayProcesses(path.join(MINIONS_DIR, 'dashboard.js'), 'dashboard');
-  const newPid = spawnDashboard();
-  _lastDashboardRespawnAt = now;
-  console.log(`[supervisor] Dashboard respawned (new PID: ${newPid})`);
+
+  const respawn = (why) => {
+    console.log(`[supervisor] Dashboard ${why} on port ${dashPort} — respawning...`);
+    // Reap stray dashboards first. Besides bounding the count, this collapses the
+    // port-desync case: orphan dashboards holding other ports are killed, freeing
+    // the canonical port for the fresh one whose beacon _resolveDashPort() reads.
+    // Critically, for the frozen-but-listening case the reap also KILLS the wedged
+    // process still holding the port so spawnDashboard() can bind it.
+    reapStrayProcesses(path.join(MINIONS_DIR, 'dashboard.js'), 'dashboard');
+    const newPid = spawnDashboard();
+    _lastDashboardRespawnAt = now;
+    _dashHealthFailStreak = 0;
+    console.log(`[supervisor] Dashboard respawned (new PID: ${newPid})`);
+  };
+
+  // Hard-down: nothing bound to the port → respawn immediately.
+  if (pids.length === 0) {
+    _dashHealthFailStreak = 0;
+    respawn('not listening');
+    return;
+  }
+
+  // Port is bound. Verify the event loop is actually responsive — a frozen-but-
+  // listening dashboard keeps the socket LISTENING yet serves the in-browser
+  // "unreachable" banner. Probe /api/health; only respawn after a streak of
+  // failures so a legitimately busy getStatus() rebuild isn't mistaken for a hang.
+  const healthy = await _probeDashboardHealth(dashPort);
+  if (healthy === null) {
+    // Probe helper unavailable — fall back to port-only liveness (the pre-existing
+    // behavior). Don't count this as a failure; we won't respawn a bound dashboard
+    // we can't actually prove is frozen.
+    _dashHealthFailStreak = 0;
+    return;
+  }
+  if (healthy) { _dashHealthFailStreak = 0; return; }
+
+  _dashHealthFailStreak++;
+  console.log(`[supervisor] Dashboard bound but unresponsive on port ${dashPort} (${_dashHealthFailStreak}/${DASH_HEALTH_MAX_FAILS} strikes)`);
+  if (_dashHealthFailStreak < DASH_HEALTH_MAX_FAILS) return;
+  respawn('frozen (health probe failed)');
 }
 
-function tick() {
+let _tickInFlight = false;
+async function tick() {
+  // The dashboard health probe is async; guard against a slow probe overlapping
+  // the next interval fire. setInterval invoking an async fn is fire-and-forget,
+  // so this flag is the only thing preventing concurrent ticks.
+  if (_tickInFlight) return;
+  _tickInFlight = true;
   try {
     if (isStopIntentSet()) return;
     const now = Date.now();
     checkEngine(now);
     checkEngineHung(now);
-    checkDashboard(now);
+    await checkDashboard(now);
   } catch (e) {
     console.error(`[supervisor] tick error: ${e && e.message}`);
+  } finally {
+    _tickInFlight = false;
   }
 }
 
@@ -517,8 +626,11 @@ module.exports = {
     openAppendFd,
     checkEngine,
     checkEngineHung,
+    _isRespawnEligibleEngineState,
     checkDashboard,
+    _probeDashboardHealth,
     SUPERVISOR_STALE_ENGINE_HEARTBEAT_MS,
+    DASH_HEALTH_MAX_FAILS,
     tick,
     // Path getters honor MINIONS_TEST_DIR via shared.ENGINE_DIR, so test
     // isolation correctly redirects writes/reads under createTestMinionsDir.

package/engine.js

@@ -138,7 +138,7 @@ const worktreePool = require('./engine/worktree-pool');
 // ─── State Readers (delegated to engine/queries.js) ─────────────────────────
 
 const { getConfig, getControl, getDispatch, getNotes,
-  getAgentStatus, getAgentCharter, getInboxFiles,
+  getAgentStatus, getInboxFiles,
   collectSkillFiles, getSkillIndex, getKnowledgeBaseIndex,
   getPrs, SKILLS_DIR } = queries;
 
@@ -10564,7 +10564,7 @@ module.exports = {
 
   // State readers/writers
   getConfig, getControl, getDispatch, getRouting, getNotes,
-  getAgentStatus, getAgentCharter, getInboxFiles, getPrs,
+  getAgentStatus, getInboxFiles, getPrs,
   validateConfig,
 
   // Dispatch management (re-exported from engine/dispatch.js)

package/package.json

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