@yemi33/minions 0.1.1658 → 0.1.1660

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.1.1660 (2026-05-01)
+
+### Fixes
+- less rigid agent orphan detection
+
+## 0.1.1659 (2026-05-01)
+
+### Other
+- Harden runtime state writes
+
 ## 0.1.1658 (2026-05-01)
 
 ### Fixes

package/dashboard.js

@@ -31,7 +31,7 @@ const dispatchMod = require('./engine/dispatch');
 const steering = require('./engine/steering');
 const os = require('os');
 
-const { safeRead, safeReadDir, safeWrite, safeJson, safeJsonObj, safeJsonArr, safeUnlink, mutateJsonFileLocked, mutateWorkItems, getProjects: _getProjects, DONE_STATUSES, WI_STATUS, WORK_TYPE, reopenWorkItem } = shared;
+const { safeRead, safeReadDir, safeWrite, safeJson, safeJsonObj, safeJsonArr, safeUnlink, mutateJsonFileLocked, mutateControl, mutateCooldowns, mutateWorkItems, getProjects: _getProjects, DONE_STATUSES, WI_STATUS, WORK_TYPE, reopenWorkItem } = shared;
 const { getAgents, getAgentDetail, getPrdInfo, getWorkItems, getDispatchQueue,
   getSkills, getInbox, getNotesWithMeta, getPullRequests,
   getEngineLog, getMetrics, getKnowledgeBaseEntries, timeSince,
@@ -2116,12 +2116,10 @@ const { cleanDispatchEntries } = require('./engine/dispatch');
 // ── Engine Restart Helpers (used by watchdog + API) ─────────────────────────
 
 function spawnEngine() {
-  const controlPath = path.join(ENGINE_DIR, 'control.json');
   // Don't pre-write 'stopped' — let the new engine process own its state transition.
   // The engine start code already handles state:'running' with a dead PID gracefully.
   // Only set restarted_at + clear stale pid so dashboard shows the restart timestamp.
-  const control = safeJson(controlPath) || {};
-  safeWrite(controlPath, { ...control, pid: null, restarted_at: new Date().toISOString() });
+  mutateControl(control => ({ ...control, pid: null, restarted_at: new Date().toISOString() }));
   const { spawn: cpSpawn } = require('child_process');
   const childEnv = { ...process.env };
   for (const key of Object.keys(childEnv)) {
@@ -2413,12 +2411,10 @@ const server = http.createServer(async (req, res) => {
           }, { defaultValue: { pending: [], active: [], completed: [] } });
         } catch (e) { console.error('dispatch cleanup:', e.message); }
         try {
-          const cooldownPath = path.join(MINIONS_DIR, 'engine', 'cooldowns.json');
-          const cooldowns = safeJsonObj(cooldownPath);
-          if (cooldowns[dispatchKey]) {
+          mutateCooldowns(cooldowns => {
             delete cooldowns[dispatchKey];
-            safeWrite(cooldownPath, cooldowns);
-          }
+            return cooldowns;
+          });
         } catch (e) { console.error('cooldown cleanup:', e.message); }
 
         return jsonReply(res, 200, { ok: true, id, rematerialized: true });
@@ -2463,12 +2459,10 @@ const server = http.createServer(async (req, res) => {
 
       // Clear cooldown so item isn't blocked by exponential backoff
       try {
-        const cooldownPath = path.join(MINIONS_DIR, 'engine', 'cooldowns.json');
-        const cooldowns = safeJsonObj(cooldownPath);
-        if (cooldowns[dispatchKey]) {
+        mutateCooldowns(cooldowns => {
           delete cooldowns[dispatchKey];
-          safeWrite(cooldownPath, cooldowns);
-        }
+          return cooldowns;
+        });
       } catch (e) { console.error('cooldown cleanup:', e.message); }
 
       return jsonReply(res, 200, { ok: true, id });
@@ -2514,13 +2508,12 @@ const server = http.createServer(async (req, res) => {
 
       // Clean cooldown entries so item can be re-created immediately
       try {
-        const cooldownPath = path.join(MINIONS_DIR, 'engine', 'cooldowns.json');
-        const cooldowns = safeJsonObj(cooldownPath);
-        let cleaned = false;
-        for (const key of Object.keys(cooldowns)) {
-          if (key.includes(id)) { delete cooldowns[key]; cleaned = true; }
-        }
-        if (cleaned) safeWrite(cooldownPath, cooldowns);
+        mutateCooldowns(cooldowns => {
+          for (const key of Object.keys(cooldowns)) {
+            if (key.includes(id)) delete cooldowns[key];
+          }
+          return cooldowns;
+        });
       } catch (e) { console.error('cooldown cleanup:', e.message); }
 
       // Reset PRD item status so it doesn't stay 'dispatched' with no work item (#779)
@@ -2579,13 +2572,12 @@ const server = http.createServer(async (req, res) => {
 
       // Clean cooldown entries
       try {
-        const cooldownPath = path.join(MINIONS_DIR, 'engine', 'cooldowns.json');
-        const cooldowns = safeJsonObj(cooldownPath);
-        let cleaned = false;
-        for (const key of Object.keys(cooldowns)) {
-          if (key.includes(id)) { delete cooldowns[key]; cleaned = true; }
-        }
-        if (cleaned) safeWrite(cooldownPath, cooldowns);
+        mutateCooldowns(cooldowns => {
+          for (const key of Object.keys(cooldowns)) {
+            if (key.includes(id)) delete cooldowns[key];
+          }
+          return cooldowns;
+        });
       } catch (e) { console.error('cooldown cleanup on cancel:', e.message); }
 
       invalidateStatusCache();
@@ -2704,12 +2696,10 @@ const server = http.createServer(async (req, res) => {
         }, { defaultValue: { pending: [], active: [], completed: [] } });
       } catch (e) { console.error('dispatch cleanup on reopen:', e.message); }
       try {
-        const cooldownPath = path.join(MINIONS_DIR, 'engine', 'cooldowns.json');
-        const cooldowns = safeJsonObj(cooldownPath);
-        if (cooldowns[dispatchKey]) {
+        mutateCooldowns(cooldowns => {
           delete cooldowns[dispatchKey];
-          safeWrite(cooldownPath, cooldowns);
-        }
+          return cooldowns;
+        });
       } catch (e) { console.error('cooldown cleanup on reopen:', e.message); }
 
       invalidateStatusCache();
@@ -6446,10 +6436,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
 
     // Engine
     { method: 'POST', path: '/api/engine/wakeup', desc: 'Trigger immediate engine tick via control.json signal', handler: async (req, res) => {
-      const controlPath = path.join(MINIONS_DIR, 'engine', 'control.json');
-      const control = shared.safeJson(controlPath) || {};
-      control._wakeupAt = Date.now();
-      shared.safeWrite(controlPath, control);
+      shared.mutateControl(control => ({ ...control, _wakeupAt: Date.now() }));
       return jsonReply(res, 200, { ok: true, message: 'Wakeup signal sent' });
     }},
     { method: 'POST', path: '/api/engine/restart', desc: 'Force-kill engine and restart immediately', handler: handleEngineRestart },

package/engine/cleanup.js

@@ -9,7 +9,7 @@ const shared = require('./shared');
 const queries = require('./queries');
 
 const { exec, execSilent, log, ts, ENGINE_DEFAULTS } = shared;
-const { safeJson, safeWrite, safeReadDir, mutateWorkItems, mutateJsonFileLocked, getProjects, projectWorkItemsPath, projectPrPath,
+const { safeJson, safeWrite, safeReadDir, mutateCooldowns, mutateWorkItems, mutateJsonFileLocked, getProjects, projectWorkItemsPath, projectPrPath,
   sanitizeBranch, KB_CATEGORIES } = shared;
 const { getDispatch, getAgentStatus } = queries;
 
@@ -675,9 +675,9 @@ function runCleanup(config, verbose = false) {
         entries.sort((a, b) => (b[1].timestamp || 0) - (a[1].timestamp || 0));
         const keep = Object.fromEntries(entries.slice(0, COOLDOWN_CAP));
         cleaned.cooldowns = entries.length - COOLDOWN_CAP;
-        safeWrite(cooldownPath, keep);
+        mutateCooldowns(() => keep);
       } else if (dirty) {
-        safeWrite(cooldownPath, cooldowns);
+        mutateCooldowns(() => cooldowns);
       }
     }
   } catch (e) { log('warn', 'cap cooldowns: ' + e.message); }

package/engine/cli.js

@@ -6,7 +6,7 @@
 const fs = require('fs');
 const path = require('path');
 const shared = require('./shared');
-const { safeRead, safeJson, safeWrite, mutateWorkItems, ts, WI_STATUS, WORK_TYPE, PLAN_STATUS, PR_STATUS, DISPATCH_RESULT } = shared;
+const { safeRead, safeJson, safeWrite, mutateControl, mutateWorkItems, ts, WI_STATUS, WORK_TYPE, PLAN_STATUS, PR_STATUS, DISPATCH_RESULT } = shared;
 const queries = require('./queries');
 const { getConfig, getControl, getDispatch, getAgentStatus,
   MINIONS_DIR, ENGINE_DIR, AGENTS_DIR, PLANS_DIR, PRD_DIR, CONTROL_PATH, DISPATCH_PATH } = queries;
@@ -312,7 +312,7 @@ const commands = {
     }
     let codeCommit = null;
     try { codeCommit = require('child_process').execSync('git rev-parse --short HEAD', { cwd: path.resolve(__dirname, '..'), encoding: 'utf8', timeout: 5000, windowsHide: true }).trim(); } catch {}
-    safeWrite(CONTROL_PATH, { state: 'running', pid: process.pid, started_at: e.ts(), codeVersion, codeCommit });
+    mutateControl(() => ({ state: 'running', pid: process.pid, started_at: e.ts(), codeVersion, codeCommit }));
     // Keep .minions-version in sync so `minions version` stays accurate after git pulls
     if (codeVersion) {
       try { fs.writeFileSync(path.join(shared.MINIONS_DIR, '.minions-version'), codeVersion); } catch {}
@@ -599,7 +599,10 @@ const commands = {
       const ctrl = getControl();
       if (ctrl._wakeupAt && Date.now() - ctrl._wakeupAt < 5000) {
         delete ctrl._wakeupAt;
-        safeWrite(CONTROL_PATH, ctrl);
+        mutateControl((control) => {
+          delete control._wakeupAt;
+          return control;
+        });
         e.tick();
       }
     }, 1000);
@@ -669,11 +672,11 @@ const commands = {
       clearInterval(fastPollTimer);
       if (teamsInboxTimer) clearInterval(teamsInboxTimer);
       for (const f of _watchedFiles) { try { fs.unwatchFile(f); } catch { /* cleanup */ } }
-      safeWrite(CONTROL_PATH, { state: 'stopping', pid: process.pid, stopping_at: e.ts() });
+      mutateControl(() => ({ state: 'stopping', pid: process.pid, stopping_at: e.ts() }));
       e.log('info', `Graceful shutdown initiated (${signal})`);
 
       if (e.activeProcesses.size === 0) {
-        safeWrite(CONTROL_PATH, { state: 'stopped', stopped_at: e.ts() });
+        mutateControl(() => ({ state: 'stopped', stopped_at: e.ts() }));
         e.log('info', 'Graceful shutdown complete (no active agents)');
         shared.flushLogs(); // drain buffered log entries before exit
         console.log('No active agents — stopped.');
@@ -687,7 +690,7 @@ const commands = {
       const poll = setInterval(() => {
         if (e.activeProcesses.size === 0) {
           clearInterval(poll);
-          safeWrite(CONTROL_PATH, { state: 'stopped', stopped_at: e.ts() });
+          mutateControl(() => ({ state: 'stopped', stopped_at: e.ts() }));
           e.log('info', 'Graceful shutdown complete (all agents finished)');
           shared.flushLogs(); // drain buffered log entries before exit
           console.log('All agents finished — stopped.');
@@ -695,7 +698,7 @@ const commands = {
         }
         if (Date.now() >= deadline) {
           clearInterval(poll);
-          safeWrite(CONTROL_PATH, { state: 'stopped', stopped_at: e.ts() });
+          mutateControl(() => ({ state: 'stopped', stopped_at: e.ts() }));
           e.log('warn', `Graceful shutdown timed out after ${timeout / 1000}s with ${e.activeProcesses.size} agent(s) still active`);
           shared.flushLogs(); // drain buffered log entries before exit
           console.log(`Shutdown timeout (${timeout / 1000}s) — force exiting with ${e.activeProcesses.size} agent(s) still running.`);
@@ -742,14 +745,14 @@ const commands = {
     if (control.pid && control.pid !== process.pid) {
       try { process.kill(control.pid); } catch { /* process may be dead */ }
     }
-    safeWrite(CONTROL_PATH, { state: 'stopped', stopped_at: e.ts() });
+    mutateControl(() => ({ state: 'stopped', stopped_at: e.ts() }));
     e.log('info', 'Engine stopped');
     console.log('Engine stopped.');
   },
 
   pause() {
     const e = engine();
-    safeWrite(CONTROL_PATH, { state: 'paused', paused_at: e.ts() });
+    mutateControl(() => ({ state: 'paused', paused_at: e.ts() }));
     e.log('info', 'Engine paused');
     console.log('Engine paused. Run `node .minions/engine.js resume` to resume.');
   },
@@ -761,7 +764,7 @@ const commands = {
       console.log('Engine is already running.');
       return;
     }
-    safeWrite(CONTROL_PATH, { state: 'running', resumed_at: e.ts() });
+    mutateControl(() => ({ state: 'running', resumed_at: e.ts() }));
     e.log('info', 'Engine resumed');
     console.log('Engine resumed.');
   },
@@ -932,7 +935,7 @@ const commands = {
   dispatch() {
     const control = getControl();
     if (control.state === 'running' && isEngineProcessAlive(control)) {
-      safeWrite(CONTROL_PATH, { ...control, _wakeupAt: Date.now() });
+      mutateControl((c) => ({ ...c, _wakeupAt: Date.now() }));
       console.log(`Dispatch wakeup requested from running engine (PID ${control.pid}).`);
       return;
     }

package/engine/cooldown.js

@@ -7,7 +7,7 @@ const path = require('path');
 const shared = require('./shared');
 const queries = require('./queries');
 
-const { safeJson, safeWrite, log, ENGINE_DEFAULTS } = shared;
+const { safeJson, mutateCooldowns, log, ENGINE_DEFAULTS } = shared;
 const { ENGINE_DIR } = queries;
 
 /**
@@ -37,6 +37,7 @@ function _truncateContextEntry(entry, maxBytes) {
 
 const COOLDOWN_PATH = path.join(ENGINE_DIR, 'cooldowns.json');
 const dispatchCooldowns = new Map(); // key → { timestamp, failures }
+let _lastDiskCooldownKeys = new Set();
 
 function loadCooldowns() {
   const saved = safeJson(COOLDOWN_PATH);
@@ -48,6 +49,7 @@ function loadCooldowns() {
       dispatchCooldowns.set(k, v);
     }
   }
+  _lastDiskCooldownKeys = new Set(dispatchCooldowns.keys());
   log('info', `Loaded ${dispatchCooldowns.size} cooldowns from disk`);
 }
 
@@ -57,27 +59,35 @@ function saveCooldowns() {
   if (_cooldownWriteTimer) clearTimeout(_cooldownWriteTimer);
   _cooldownWriteTimer = setTimeout(() => {
     _cooldownWriteTimer = null;
-    // Prune expired entries (>24h) before saving
-    const now = Date.now();
-    for (const [k, v] of dispatchCooldowns) {
-      if (now - v.timestamp > 24 * 60 * 60 * 1000) dispatchCooldowns.delete(k);
-    }
-    // Trim pendingContexts arrays before writing to prevent bloat
-    const cap = ENGINE_DEFAULTS.maxPendingContexts;
-    const entryLimit = ENGINE_DEFAULTS.maxPendingContextEntryBytes;
-    for (const [, v] of dispatchCooldowns) {
-      if (Array.isArray(v.pendingContexts)) {
-        if (v.pendingContexts.length > cap) {
-          v.pendingContexts = v.pendingContexts.slice(-cap);
-        }
-        // Also truncate oversized individual entries — #1167 showed
-        // 20 entries × 25 MB each still produced a 500 MB cooldowns.json.
-        v.pendingContexts = v.pendingContexts.map(e => _truncateContextEntry(e, entryLimit));
-      }
-    }
-    const obj = Object.fromEntries(dispatchCooldowns);
     try {
-      safeWrite(COOLDOWN_PATH, obj);
+      mutateCooldowns((diskCooldowns) => {
+        for (const key of Array.from(dispatchCooldowns.keys())) {
+          if (_lastDiskCooldownKeys.has(key) && !Object.prototype.hasOwnProperty.call(diskCooldowns, key)) {
+            dispatchCooldowns.delete(key);
+          }
+        }
+        // Prune expired entries (>24h) before saving
+        const now = Date.now();
+        for (const [k, v] of dispatchCooldowns) {
+          if (now - v.timestamp > 24 * 60 * 60 * 1000) dispatchCooldowns.delete(k);
+        }
+        // Trim pendingContexts arrays before writing to prevent bloat
+        const cap = ENGINE_DEFAULTS.maxPendingContexts;
+        const entryLimit = ENGINE_DEFAULTS.maxPendingContextEntryBytes;
+        for (const [, v] of dispatchCooldowns) {
+          if (Array.isArray(v.pendingContexts)) {
+            if (v.pendingContexts.length > cap) {
+              v.pendingContexts = v.pendingContexts.slice(-cap);
+            }
+            // Also truncate oversized individual entries — #1167 showed
+            // 20 entries × 25 MB each still produced a 500 MB cooldowns.json.
+            v.pendingContexts = v.pendingContexts.map(e => _truncateContextEntry(e, entryLimit));
+          }
+        }
+        const obj = Object.fromEntries(dispatchCooldowns);
+        _lastDiskCooldownKeys = new Set(Object.keys(obj));
+        return obj;
+      });
     } catch (err) {
       log('warn', `saveCooldowns failed writing ${COOLDOWN_PATH}: ${err.message}`);
     }

package/engine/copilot-models.json

@@ -1,5 +1,5 @@
 {
   "runtime": "copilot",
   "models": null,
-  "cachedAt": "2026-05-01T05:22:39.907Z"
+  "cachedAt": "2026-05-01T05:58:00.505Z"
 }

package/engine/queries.js

@@ -101,7 +101,21 @@ function timeSince(ms) {
 }
 
 function readJsonNoRestore(filePath) {
-  try { return JSON.parse(fs.readFileSync(filePath, 'utf8')); } catch { return null; }
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, 'utf8');
+  } catch (e) {
+    if (e && e.code !== 'ENOENT') {
+      console.warn(`[queries] failed to read ${_relativeStatePath(filePath)}: ${e.message}`);
+    }
+    return null;
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (e) {
+    console.warn(`[queries] corrupt JSON in ${_relativeStatePath(filePath)}: ${e.message}`);
+    return null;
+  }
 }
 
 // ── Core State Readers ──────────────────────────────────────────────────────

package/engine/shared.js

@@ -8,6 +8,9 @@ const path = require('path');
 const crypto = require('crypto');
 
 const MINIONS_DIR = process.env.MINIONS_TEST_DIR || path.resolve(__dirname, '..');
+const ENGINE_DIR = path.join(MINIONS_DIR, 'engine');
+const CONTROL_PATH = path.join(ENGINE_DIR, 'control.json');
+const COOLDOWNS_PATH = path.join(ENGINE_DIR, 'cooldowns.json');
 const PR_LINKS_PATH = path.join(MINIONS_DIR, 'engine', 'pr-links.json');
 const PINNED_ITEMS_PATH = path.join(MINIONS_DIR, 'engine', 'kb-pins.json');
 const LOG_PATH = path.join(MINIONS_DIR, 'engine', 'log.json');
@@ -428,6 +431,20 @@ function mutateJsonFileLocked(filePath, mutateFn, {
   }, { retries, retryBackoffMs });
 }
 
+function mutateControl(mutator) {
+  return mutateJsonFileLocked(CONTROL_PATH, (data) => {
+    if (!data || typeof data !== 'object' || Array.isArray(data)) data = {};
+    return mutator(data) || data;
+  }, { defaultValue: { state: 'stopped', pid: null }, skipWriteIfUnchanged: true });
+}
+
+function mutateCooldowns(mutator) {
+  return mutateJsonFileLocked(COOLDOWNS_PATH, (data) => {
+    if (!data || typeof data !== 'object' || Array.isArray(data)) data = {};
+    return mutator(data) || data;
+  }, { defaultValue: {}, skipWriteIfUnchanged: true });
+}
+
 /**
  * Generate a unique ID suffix: timestamp + 4 random chars.
  * Use for filenames that could collide (dispatch IDs, temp files, etc.)
@@ -704,7 +721,19 @@ const ENGINE_DEFAULTS = {
   inboxConsolidateThreshold: 5,
   agentTimeout: 18000000,  // 5h
   heartbeatTimeout: 300000, // 5min — stale-orphan grace after process tracking is lost
-  heartbeatTimeouts: {}, // optional per-type stale-orphan overrides; merged at runtime (see timeout.js)
+  // Per-type stale-orphan overrides (merged with config.engine.heartbeatTimeouts at runtime — see timeout.js).
+  // Heavy work types (multi-file edits, builds, test suites, full verify cycles) routinely go quiet for
+  // longer than the 5-min default when the engine has lost their tracked handle (e.g. across an engine
+  // restart). We give them headroom up to a typical build+tests cycle. Short-running types
+  // (decompose / meeting / etc.) keep the 5-min default by simply not appearing here.
+  heartbeatTimeouts: {
+    implement:       900000, // 15min — refactors, multi-file edits, builds
+    'implement:large': 900000, // 15min — same class of work, larger scope
+    fix:             900000, // 15min — fix runs often include builds + retries
+    test:            900000, // 15min — build-and-test against existing PR
+    verify:          900000, // 15min — full project verification cycle
+    plan:            600000, // 10min — research-heavy
+  },
   maxTurns: 100,
   worktreeCreateTimeout: 300000, // 5min for git worktree add on large Windows repos
   worktreeCreateRetries: 1, // retry once on transient timeout/lock races
@@ -768,7 +797,6 @@ const ENGINE_DEFAULTS = {
   copilotReasoningSummaries: false,  // Copilot --enable-reasoning-summaries (Anthropic-family models only)
   maxBudgetUsd: undefined,       // fleet USD ceiling for --max-budget-usd (per-agent override: agents.<id>.maxBudgetUsd). Honors 0 via ?? so a literal cap of $0 works
   disableModelDiscovery: false,  // skip runtime.listModels() REST calls fleet-wide (settings UI falls back to free-text)
-  heartbeatTimeouts: {},
   maxPendingContexts: 20, // cap pendingContexts arrays in cooldowns.json to prevent unbounded growth
   maxPendingContextEntryBytes: 256 * 1024, // 256 KB — cap each pendingContexts entry to prevent huge PR comments from bloating cooldowns.json
   maxDispatchPromptBytes: 1024 * 1024, // 1 MB — dispatch items with prompts larger than this sidecar to engine/contexts/ to prevent dispatch.json OOM (#1167)
@@ -2304,6 +2332,9 @@ function createThrottleTracker({ label, baseBackoffMs = 60000, maxBackoffMs = 32
 
 module.exports = {
   MINIONS_DIR,
+  ENGINE_DIR,
+  CONTROL_PATH,
+  COOLDOWNS_PATH,
   PR_LINKS_PATH,
   PINNED_ITEMS_PATH,
   LOG_PATH,
@@ -2325,6 +2356,8 @@ module.exports = {
   assertStateFileSize,
   withFileLock,
   mutateJsonFileLocked,
+  mutateControl,
+  mutateCooldowns,
   mutateWorkItems,
   reopenWorkItem,
   mutatePullRequests,

package/engine/timeout.js

@@ -9,7 +9,7 @@ const queries = require('./queries');
 const steering = require('./steering');
 
 const { safeRead, safeWrite, safeJson, mutateJsonFileLocked, getProjects, projectWorkItemsPath, log, ts,
-  ENGINE_DEFAULTS, WI_STATUS, WORK_TYPE, DISPATCH_RESULT, AGENT_STATUS } = shared;
+  ENGINE_DEFAULTS, ENGINE_DIR, WI_STATUS, WORK_TYPE, DISPATCH_RESULT, AGENT_STATUS } = shared;
 const { getDispatch, getAgentStatus } = queries;
 const AGENTS_DIR = queries.AGENTS_DIR;
 const MINIONS_DIR = shared.MINIONS_DIR;
@@ -142,6 +142,23 @@ function isTrackedProcessAlive(procInfo) {
   }
 }
 
+// Last-resort liveness check via the on-disk PID file (engine/tmp/pid-<safeId>.pid).
+// Used by orphan detection to avoid false-positive kills when the engine has lost the
+// tracked process handle (engine restart, never-tracked spawn, etc.) but the OS-level
+// child process is still alive and healthy. The safeId here mirrors engine.js spawn
+// (id.replace(/[:\\/*?"<>|]/g, '-')) — same pattern engine/cli.js uses to re-attach.
+function isOsPidAliveForDispatch(itemId) {
+  const safeId = String(itemId || '').replace(/[:\\/*?"<>|]/g, '-');
+  const pidPath = path.join(ENGINE_DIR, 'tmp', `pid-${safeId}.pid`);
+  let raw;
+  try { raw = fs.readFileSync(pidPath, 'utf8'); }
+  catch { return false; }
+  const pid = parseInt(String(raw).trim(), 10);
+  if (!Number.isFinite(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; }
+  catch { return false; }
+}
+
 function checkTimeouts(config) {
   const activeProcesses = engine().activeProcesses;
   const engineRestartGraceUntil = engine().engineRestartGraceUntil;
@@ -335,6 +352,11 @@ function checkTimeouts(config) {
     } catch { /* ENOENT — keep default */ }
 
     if (!processAlive && silentMs > staleOrphanTimeout && (Date.now() > engineRestartGraceUntil || engineRestartGraceExempt?.has(item.id))) {
+      // Last-resort PID check: lost tracked handle but OS process may still be alive.
+      if (isOsPidAliveForDispatch(item.id)) {
+        log('info', `Orphan check: ${item.agent} (${item.id}) silent ${silentSec}s but OS PID is alive — keeping [${_logState}]`);
+        continue;
+      }
       // No tracked process AND no recent output past stale-orphan timeout AND (grace period expired OR confirmed-dead at restart) → orphaned
       log('warn', `Orphan detected: ${item.agent} (${item.id}) — no live process tracked, silent for ${silentSec}s [${_logState}]`);
       dispatch().updateAgentStatus(item.id, AGENT_STATUS.TIMED_OUT, `Orphaned — no process, silent for ${silentSec}s`);
@@ -424,4 +446,5 @@ module.exports = {
   checkTimeouts,
   checkSteering,
   checkIdleThreshold,
+  isOsPidAliveForDispatch,
 };

package/engine.js

@@ -95,6 +95,7 @@ const safeRead = shared.safeRead;
 const safeWrite = shared.safeWrite;
 const safeUnlink = shared.safeUnlink;
 const mutateJsonFileLocked = shared.mutateJsonFileLocked;
+const mutateControl = shared.mutateControl;
 const mutateWorkItems = shared.mutateWorkItems;
 const mutatePullRequests = shared.mutatePullRequests;
 const withFileLock = shared.withFileLock;
@@ -3557,7 +3558,7 @@ async function tickInner() {
   }
 
   // Write heartbeat so dashboard can detect stale engine
-  try { safeWrite(CONTROL_PATH, { ...control, heartbeat: Date.now() }); } catch (e) { log('warn', 'write heartbeat: ' + e.message); }
+  try { mutateControl(c => ({ ...c, heartbeat: Date.now() })); } catch (e) { log('warn', 'write heartbeat: ' + e.message); }
 
   const config = getConfig();
   tickCount++;

package/package.json

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