@yemi33/minions 0.1.2238 → 0.1.2240

package/engine/queries.js

@@ -526,6 +526,61 @@ function _wiIdFromNoteFrontmatter(fm) {
   return fm.work_item || fm.wi || fm.sourceItem || null;
 }
 
+// Archive notes-by-WI cache. The archive dir accumulates thousands of
+// immutable note files (2000+ and growing); reading + frontmatter-parsing all
+// of them was the single dominant SYNCHRONOUS cost inside getWorkItems()
+// (measured: multiple seconds with a cold OS file cache, a few hundred ms warm)
+// — and getWorkItems runs on a 1 s TTL, so the dashboard re-read the whole
+// archive every few seconds. That blocked the dashboard event loop and starved
+// the Command Center SSE heartbeat into stalls + reconnects. Archive files are
+// written once (consolidation moves inbox → archive and never edits in place),
+// so an mtime-gated cache on the archive DIRECTORY is safe: any add/remove
+// bumps the dir mtime and busts the cache; the TTL is a belt-and-suspenders
+// backstop. Inbox is NOT cached here — it is tiny and churns constantly, so
+// _buildNotesByWiMap scans it fresh every call (see below).
+let _archiveNotesByWiCache = null;
+let _archiveNotesByWiCacheAt = 0;
+let _archiveNotesByWiCacheMtime = null;
+// The dir-mtime gate is the PRIMARY freshness signal (NTFS/POSIX bump the
+// archive dir mtime on every add/remove/rename, so a newly-archived note busts
+// the cache on the next call). The TTL is only a belt-and-suspenders backstop
+// for the rare FS that misses an mtime update — kept long so we don't pay the
+// full multi-thousand-file re-read on a fixed cadence when nothing changed.
+const ARCHIVE_NOTES_BY_WI_TTL = 300000; // 5 min
+
+function _buildArchiveNotesByWiMap() {
+  let dirMtime = null;
+  try { dirMtime = fs.statSync(ARCHIVE_DIR).mtimeMs; } catch { dirMtime = null; }
+  const now = Date.now();
+  if (_archiveNotesByWiCache
+    && (now - _archiveNotesByWiCacheAt) < ARCHIVE_NOTES_BY_WI_TTL
+    && _archiveNotesByWiCacheMtime === dirMtime) {
+    return _archiveNotesByWiCache;
+  }
+  const out = Object.create(null);
+  for (const f of safeReadDir(ARCHIVE_DIR)) {
+    if (!f.endsWith('.md')) continue;
+    const fm = _parseNoteFrontmatter(safeRead(path.join(ARCHIVE_DIR, f)));
+    const wiId = _wiIdFromNoteFrontmatter(fm);
+    if (!wiId) continue;
+    if (!out[wiId]) out[wiId] = [];
+    out[wiId].push('archive:' + f);
+  }
+  _archiveNotesByWiCache = out;
+  _archiveNotesByWiCacheAt = now;
+  _archiveNotesByWiCacheMtime = dirMtime;
+  return out;
+}
+
+// Test/maintenance hook — drop the archive notes cache (mirrors the other
+// invalidate* helpers). Not normally needed: the cache self-heals via the
+// dir-mtime gate + TTL.
+function invalidateArchiveNotesByWiCache() {
+  _archiveNotesByWiCache = null;
+  _archiveNotesByWiCacheAt = 0;
+  _archiveNotesByWiCacheMtime = null;
+}
+
 // Build a wiId → [filename, ...] map by scanning the inbox + archive dirs.
 // Archive entries are prefixed with `archive:` so the dashboard renderer can
 // tell them apart (matches the convention already used by _artifacts.notes).
@@ -537,17 +592,18 @@ function _buildNotesByWiMap() {
     if (!out[wiId]) out[wiId] = [];
     if (!out[wiId].includes(token)) out[wiId].push(token);
   };
+  // Inbox: tiny and churns constantly — scan fresh every call.
   for (const f of safeReadDir(INBOX_DIR)) {
     if (!f.endsWith('.md')) continue;
     const fm = _parseNoteFrontmatter(safeRead(path.join(INBOX_DIR, f)));
     const wiId = _wiIdFromNoteFrontmatter(fm);
     if (wiId) addNote(wiId, f);
   }
-  for (const f of safeReadDir(ARCHIVE_DIR)) {
-    if (!f.endsWith('.md')) continue;
-    const fm = _parseNoteFrontmatter(safeRead(path.join(ARCHIVE_DIR, f)));
-    const wiId = _wiIdFromNoteFrontmatter(fm);
-    if (wiId) addNote(wiId, 'archive:' + f);
+  // Archive: large + immutable — served from the mtime-gated cache so we don't
+  // re-read thousands of files on every getWorkItems() rebuild.
+  const archiveMap = _buildArchiveNotesByWiMap();
+  for (const wiId in archiveMap) {
+    for (const token of archiveMap[wiId]) addNote(wiId, token);
   }
   return out;
 }
@@ -635,7 +691,11 @@ function getAgentStatus(agentId) {
     const staleOrphanTimeout = config.engine?.heartbeatTimeout || ENGINE_DEFAULTS.heartbeatTimeout;
     const staleThresholdMs = staleOrphanTimeout * 2;
     const now = Date.now();
-    const allItems = getWorkItems(config);
+    // Lean read — this fallback only inspects core fields (dispatched_to,
+    // status, dispatched_at, …), never _pr/_artifacts/_notes. Skipping
+    // enrichment keeps the per-idle-agent getAgents() roster build off the
+    // heavy detail-modal path. (Fix #3 — dashboard event-loop perf.)
+    const allItems = getWorkItems(config, { enrich: false });
     const latestInFlight = allItems
       .filter(w => {
         if ((w.dispatched_to || '').toLowerCase() !== String(agentId).toLowerCase()) return false;
@@ -1711,10 +1771,24 @@ function getKnowledgeBaseIndex() {
 let _workItemsCache = null;
 let _workItemsCacheAt = 0;
 let _workItemsCacheMtimes = null;
+// Lean cache for getWorkItems(config, { enrich: false }) — core fields only,
+// skipping the PR cross-reference + per-item _artifacts/_notes detail-modal
+// enrichment (the synchronous KB-scan + agent-dir reads that the detail modal
+// needs but hot callers don't). getAgentStatus()'s per-idle-agent fallback and
+// count-only callers use this so the agent roster / CC preamble never pay the
+// enrichment cost. Held separately so an enrich:false caller can't poison the
+// enriched cache (and vice-versa) — readAllWorkItems() returns fresh row
+// objects each call, so the two caches never share mutable references.
+let _workItemsLeanCache = null;
+let _workItemsLeanCacheAt = 0;
+let _workItemsLeanCacheMtimes = null;
 function invalidateWorkItemsCache() {
   _workItemsCache = null;
   _workItemsCacheAt = 0;
   _workItemsCacheMtimes = null;
+  _workItemsLeanCache = null;
+  _workItemsLeanCacheAt = 0;
+  _workItemsLeanCacheMtimes = null;
 }
 
 function _workItemsFilePaths(config) {
@@ -1744,14 +1818,29 @@ function _workItemsMtimesDiffer(prev, curr) {
   return false;
 }
 
-function getWorkItems(config) {
+// getWorkItems(config, { enrich })
+//   enrich (default true): also cross-reference PRs and populate the
+//     detail-modal _artifacts/_notes fields. The /api/work-items list payload
+//     needs these (PR badges + note chips).
+//   enrich: false — core fields only (status, dispatched_to, depends_on, …)
+//     plus the cheap dispatch cross-reference. Skips the synchronous PR
+//     cross-ref and per-item KB/agent-dir enrichment. Use from hot callers that
+//     never read _artifacts/_notes (getAgentStatus fallback, count-only callers)
+//     so the agent roster / CC preamble don't pay the enrichment cost on every
+//     cold rebuild.
+function getWorkItems(config, opts) {
+  const enrich = !(opts && opts.enrich === false);
   const now = Date.now();
   config = config || getConfig();
-  if (_workItemsCache && (now - _workItemsCacheAt) < 1000) {
+  if (enrich) {
+    if (_workItemsCache && (now - _workItemsCacheAt) < 1000) {
+      const currMtimes = _snapshotWorkItemsMtimes(config);
+      if (!_workItemsMtimesDiffer(_workItemsCacheMtimes, currMtimes)) return _workItemsCache;
+    }
+  } else if (_workItemsLeanCache && (now - _workItemsLeanCacheAt) < 1000) {
     const currMtimes = _snapshotWorkItemsMtimes(config);
-    if (!_workItemsMtimesDiffer(_workItemsCacheMtimes, currMtimes)) return _workItemsCache;
+    if (!_workItemsMtimesDiffer(_workItemsLeanCacheMtimes, currMtimes)) return _workItemsLeanCache;
   }
-  const projects = getProjects(config);
   let allItems = [];
 
   // SQL is the canonical (and only) work-items store after Phase 9.
@@ -1795,6 +1884,10 @@ function getWorkItems(config) {
     }
   }
 
+  // Detail-modal enrichment (PR cross-ref + _artifacts/_notes). Skipped for
+  // enrich:false callers — see the getWorkItems header.
+  if (enrich) {
+  const projects = getProjects(config);
   // Cross-reference with PRs
   const allPrs = getPullRequests(config);
   for (const item of allItems) {
@@ -1890,6 +1983,7 @@ function getWorkItems(config) {
     const mentions = _notesByWi[item.id];
     if (mentions && mentions.length > 0) item._notes = mentions;
   }
+  } // end if (enrich)
 
   const statusOrder = {
     pending: 0,
@@ -1906,9 +2000,16 @@ function getWorkItems(config) {
     return (b.created || '').localeCompare(a.created || '');
   });
 
-  _workItemsCache = allItems;
-  _workItemsCacheAt = now;
-  _workItemsCacheMtimes = _snapshotWorkItemsMtimes(config);
+  const cacheMtimes = _snapshotWorkItemsMtimes(config);
+  if (enrich) {
+    _workItemsCache = allItems;
+    _workItemsCacheAt = now;
+    _workItemsCacheMtimes = cacheMtimes;
+  } else {
+    _workItemsLeanCache = allItems;
+    _workItemsLeanCacheAt = now;
+    _workItemsLeanCacheMtimes = cacheMtimes;
+  }
   return allItems;
 }
 
@@ -3103,7 +3204,7 @@ module.exports = {
   getKnowledgeBaseEntries, getKnowledgeBaseEntriesSnapshot, getKnowledgeBaseIndex,
 
   // Work items & PRD
-  getWorkItems, invalidateWorkItemsCache, getPrdInfo,
+  getWorkItems, invalidateWorkItemsCache, invalidateArchiveNotesByWiCache, getPrdInfo,
 
   // W-mq5uzmc6001d708f — test hooks for the defensive PR enrichment cache.
   _resetPrEnrichmentCacheForTest,

package/engine/shared.js

@@ -2958,19 +2958,20 @@ const ENGINE_DEFAULTS = {
   copilotSuppressAgentsMd: true,     // Copilot --no-custom-instructions: stop AGENTS.md auto-load from fighting Minions playbook prompts
   copilotStreamMode: 'on',           // Copilot --stream <on|off>: 'on' streams assistant.message_delta events live; 'off' batches them
   copilotReasoningSummaries: false,  // Copilot --enable-reasoning-summaries (Anthropic-family models only)
-  // P-mcp-storm — Copilot loads `~/.copilot/mcp-config.json` (the operator's
-  // user-scope MCP servers) UNCONDITIONALLY on every process start: it is NOT
-  // gated by `--add-dir`, cwd, or `hermeticHarness` (proven empirically — a
-  // copilot spawned from a neutral dir with no `--add-dir ~/.copilot` still
-  // connects every server). So every spawned Copilot agent boots the operator's
-  // full interactive MCP stack; on Windows each `type:local`/`stdio` server
-  // (e.g. playwright, maestro) launches its own visible console window and
-  // playwright opens browser tabs. The only lever Copilot exposes is
-  // `--disable-mcp-server <name>` (repeatable). This list names the servers the
-  // engine disables for autonomous agent dispatches. Default [] = inherit ALL
-  // (no behavior change). Per-agent override `agent.copilotAgentDisabledMcpServers`.
-  // Resolved through `shared.resolveCopilotAgentDisabledMcpServers(agent, engine)`.
-  // NOTE: `hermeticHarness` does NOT suppress these (it only strips `--add-dir`).
+  // P-mcp-storm — Copilot SPAWNS every server in its `mcp-config.json` on every
+  // process start and authenticates it. `--disable-mcp-server <name>` only hides
+  // a server's TOOLS from the model; it does NOT stop the server process (proven
+  // empirically — agents spawned azmcp/workiq even with the flag set), so any
+  // auth-requiring server pops a Microsoft sign-in window on EVERY agent spawn.
+  // The ONLY real lever is the CONFIG: a server absent from the config can't be
+  // spawned. The engine therefore points agents at a private COPILOT_HOME
+  // (`shared.resolveAgentCopilotHome`) whose mcp-config is a copy of the operator's
+  // `~/.copilot/mcp-config.json` MINUS the names in this list (see engine.js
+  // `_applyAgentCopilotHome`). Default [] = inherit ALL of the operator's MCP
+  // servers for agents (non-breaking). Add a name to disable it for agents only;
+  // the operator's interactive `~/.copilot` is never touched. Per-agent override
+  // `agent.copilotAgentDisabledMcpServers`. Resolved through
+  // `shared.resolveCopilotAgentDisabledMcpServers(agent, engine)`.
   copilotAgentDisabledMcpServers: [],
   ccUseWorkerPool: false,            // Sub-task C of W-mp2w003600196c51 (CC perf): when true AND CC runtime is copilot, _invokeCcStream routes through engine/cc-worker-pool.js (persistent `copilot --acp` per CC tab) instead of spawning a fresh CLI per turn. Off by default — opt-in feature flag. **Structurally copilot-only**: the pool spawns `copilot --acp` (Agent Client Protocol); Claude Code does not implement ACP, so resolveCcUseWorkerPool returns false on non-copilot CC runtimes even with explicit-true (W-mphlriic00095f69 — prevents silent runtime switch). Engine/agent dispatch path stays per-process regardless.
   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
@@ -3375,13 +3376,15 @@ function resolveAgentBareMode(agent, engine) {
 }
 
 // P-mcp-storm — Resolve the list of MCP server names to disable for spawned
-// Copilot agents (emitted as `--disable-mcp-server <name>`). Chain: per-agent
+// Copilot agents. The engine FILTERS these out of the agent's seeded
+// COPILOT_HOME mcp-config (engine.js `_applyAgentCopilotHome`) — a server absent
+// from the config can't be spawned, which is the only effective disable
+// (`--disable-mcp-server` does not stop the process). Chain: per-agent
 // `agent.copilotAgentDisabledMcpServers` → `engine.copilotAgentDisabledMcpServers`
 // → `[]` (inherit all). Tolerant of either an array OR a comma/whitespace-
 // separated string (Settings UI / `MINIONS_*` env deliver strings). Always
 // returns a deduped array of trimmed, non-empty strings. See ENGINE_DEFAULTS
-// for why this exists (Copilot loads ~/.copilot MCP config unconditionally;
-// `hermeticHarness` does NOT suppress it).
+// for the full rationale.
 function _normalizeMcpServerList(v) {
   if (v == null) return null;
   const raw = Array.isArray(v) ? v : String(v).split(/[\s,]+/);
@@ -4297,7 +4300,9 @@ const FAILURE_CLASS = {
   INVALID_MANAGED_SPAWN: 'invalid-managed-spawn', // P-7a3b1c92: agents/<id>/managed-spawn.json failed validator (bad schema, broken workdir, executable/env not on allowlist, healthcheck shape wrong). Engine refuses to spawn any spec — agent must fix file; never retryable as-is.
   MANAGED_SPAWN_HEALTHCHECK_FAILED: 'managed-spawn-healthcheck-failed', // P-7a3b1c92: at least one managed-spawn spec was spawned but failed its healthcheck within timeout_s. Engine killed the failing PIDs; siblings stay alive. Dispatch ERROR with the failing spec name + log tail surfaced in the inbox alert.
   INJECTION_FLAGGED: 'injection-flagged', // F5 (W-mpeklod3000we69c): the agent set `securityFlags.injectionAttempt:true` in its completion report after spotting a prompt-injection attempt inside an <UNTRUSTED-INPUT> fence. Engine writes a security inbox note + stamps `_securityFlag` on the WI and treats the dispatch as non-retryable so a human can review the source before the agent re-runs.
-  LIVE_CHECKOUT_DIRTY: 'live-checkout-dirty', // P-a3f9b204 (live-checkout dispatch mode): spawnAgent ran prepareLiveCheckout against project.localPath and `git status --porcelain` reported uncommitted changes. Engine refused to spawn (it never runs `git reset`/`git clean` against the operator tree). Inbox alert lists dirty files; WI is stamped `_pendingReason: 'live_checkout_dirty'`. Non-retryable — operator must commit/stash/discard before re-dispatch.
+  LIVE_CHECKOUT_DIRTY: 'live-checkout-dirty', // P-a3f9b204 (live-checkout dispatch mode): spawnAgent ran prepareLiveCheckout against project.localPath and `git status --porcelain` reported uncommitted changes. Engine refused to spawn (it never runs `git reset`/`git clean` against the operator tree). Inbox alert lists dirty files; WI is stamped `_pendingReason: 'live_checkout_dirty'`. Non-retryable — operator must commit/stash/discard before re-dispatch. RESERVED for confirmed dirty status results only — a thrown helper/git exception is LIVE_CHECKOUT_FAILED, not this (#305).
+  LIVE_CHECKOUT_FAILED: 'live-checkout-failed', // #305 (live-checkout dispatch mode): prepareLiveCheckout THREW before agent spawn (helper guard, ref validation, or a transient `git status`/`rev-parse`/`checkout` failure) — distinct from the confirmed-dirty result (LIVE_CHECKOUT_DIRTY) which the helper returns, not throws. A thrown error is NOT proof the tree is dirty, so it must not be over-classified as dirty. Retryable with bounded backoff (NOT in dispatch.js neverRetry): racy branch-lock handoff, just-finished sibling dispatch, or transient git errors frequently clear on the next attempt; the engine auto-retries up to ENGINE_DEFAULTS.maxRetries before giving up. Genuinely terminal underlying reasons (auth, validation) still short-circuit via the reason-string check in isRetryableFailureReason.
+  LIVE_CHECKOUT_MID_OPERATION: 'live-checkout-mid-operation', // P-a7f3c1d9 (live-checkout dispatch mode): spawnAgent could not switch/create the target branch in project.localPath because the operator tree is mid-operation — an in-progress merge/rebase/cherry-pick/bisect or a detached HEAD. Distinct from LIVE_CHECKOUT_DIRTY (uncommitted changes): here the tree may be clean but the branch op cannot proceed. Engine refuses to spawn (it never runs `git reset`/`git clean`/`git rebase --abort` against the operator tree). Non-retryable — operator must finish or abort the in-progress operation, or checkout a branch, before re-dispatch.
   INVALID_WORKDIR: 'invalid-workdir',     // P-714ef144: dispatch carried a meta.workdir override that failed validation — non-string, absolute path, drive-letter prefix, null byte, ".." segment, or post-resolve containment escape against project.localPath / worktree root. Engine refuses to spawn (the subpath would either be unreachable on disk or point outside the operator's allowed surface). Non-retryable — operator must fix the WI's meta.workdir before re-dispatch. Inbox alert lists the offending value + the resolved-vs-base mismatch.
   MODEL_UNAVAILABLE: 'model-unavailable', // W-mpg6isvy000xca4d: requested model returned overloaded_error / 503 / service_unavailable. Retriable — engine swaps in the runtime-appropriate fallback model on next spawn (Claude leans on --fallback-model already plumbed; Copilot overrides --model with engine.copilotFallbackModel).
   WORKSPACE_MANIFEST_REPO: 'workspace-manifest-repo-forbidden', // W-mq07avbk000m5543: dispatch routed an agent to a project/repo not present in its workspace_manifest.allowed_repos. Structural — never retryable until the manifest is widened or a different agent is chosen.
@@ -5635,6 +5640,32 @@ function resolveProjectRootDir(localPath, minionsDir) {
   return fallback;
 }
 
+/**
+ * Resolve a stable, repo-EXTERNAL COPILOT_HOME for spawned copilot agents.
+ *
+ * Copilot loads `$COPILOT_HOME/mcp-config.json` and SPAWNS every server in it on
+ * every process start. `--disable-mcp-server <name>` only hides a server's tools
+ * from the model — it does NOT stop the server PROCESS from launching, so any
+ * server that does interactive auth (azure-kusto/azmcp, DevBox, workiq, loop, …)
+ * still pops a Microsoft sign-in window on EVERY agent spawn. With minions
+ * spawning agents continuously that is an unbounded popup storm.
+ *
+ * The only effective lever is to give agents a COPILOT_HOME whose mcp-config has
+ * NO user servers (the engine seeds `{"mcpServers":{}}` there). Copilot auth is
+ * unaffected — it uses GH_TOKEN / the OS credential store, not files under the
+ * home — and the operator's real `~/.copilot` (interactive copilot) is untouched.
+ *
+ * Placed on the MINIONS_DIR volume (copilot's session-store can grow to GBs, so
+ * keep it off a possibly-full system drive) but OUTSIDE the repo, at the drive
+ * root, so concurrent git branch switches in the working tree can never delete or
+ * dirty it. Stable path so copilot session resume (`--resume`) stays consistent
+ * across spawns. Falls back to the user home when no minionsDir is given.
+ */
+function resolveAgentCopilotHome(minionsDir) {
+  const base = minionsDir ? path.parse(path.resolve(String(minionsDir))).root : os.homedir();
+  return path.join(base, '.minions-agent-copilot-home');
+}
+
 // ── Spawn cwd vs worktree placement (W-mp73x32w000l143d) ──────────────────────
 // Work types that don't need a git worktree — they read repo state but don't
 // produce code changes. Centralized here so engine.js spawnAgent and any
@@ -8929,6 +8960,7 @@ module.exports = {
   parseWorktreePorcelain,
   assertWorktreeOutsideProject,
   resolveProjectRootDir,
+  resolveAgentCopilotHome,
   resolveSpawnPaths,
   validateWorkItemWorkdir,
   applyWorkdir,

package/engine/timeout.js

@@ -748,7 +748,16 @@ function checkTimeouts(config) {
         // mid-multi-turn session. Confirmed 2026-05-11: agents on both Copilot and
         // Claude died at turn boundaries with claude/copilot.exe still actively
         // making API calls, with the sentinel + claude events interleaved in the log.
-        if (processAlive) {
+        //
+        // PID requirement: the alive guard is only reliable when a verifiable OS PID
+        // is present. A PID-less tracked object (e.g. stale in-memory handle after
+        // engine restart, or a Copilot spawn that never resolved its PID) has no
+        // real process behind it — isTrackedProcessAlive falls back to `!!proc &&
+        // !proc.killed` which is unverifiable. Trusting it loops forever (#319).
+        // When the PID is null, the terminal sentinel is the strongest available
+        // signal; complete from output unconditionally.
+        const pidVerifiable = trackedProcessPid(procInfo) !== null;
+        if (processAlive && pidVerifiable) {
           log('warn', `${item.id}: [process-exit] code=${processExitCode} sentinel found in live-output.log but tracked process (pid=${trackedProcessPid(procInfo) || '?'}) is still alive — treating sentinel as stale/premature, skipping completion`);
         } else {
           completeFromOutput(item, liveLogPath, processExitCode, liveLogTail, hasProcess);

package/engine/watchdog.js

@@ -46,6 +46,54 @@ const WATCHDOG_LOG_NAME = 'watchdog-stdio.log';
 // over months. Truncates to half-size on overflow (oldest lines dropped).
 const WATCHDOG_LOG_MAX_BYTES = 2 * 1024 * 1024;
 
+// Post-spawn grace beacon (P-b2d6c14a). Each watchdog tick is a fresh OS-
+// scheduled process with NO in-memory memory of the previous tick, and the
+// engine writes its PID to control.json LATE in boot. So on a slow Windows
+// cold-start the next scheduled tick can read a not-yet-written PID, conclude
+// "dead", and fire a SECOND `minions start` before the first finished binding
+// — re-introducing the documented duplicate-engine/dashboard storm class. The
+// in-process supervisor avoids this with an in-memory POST_SPAWN_GRACE_MS
+// (engine/supervisor.js:76); the watchdog can't keep state across ticks, so it
+// persists a tiny timestamp beacon to disk and stands down inside the window.
+const WATCHDOG_SPAWN_BEACON_NAME = 'watchdog-spawn.json';
+// Floor for the grace window. The effective window is max(2 × interval, floor)
+// so a fast cadence (e.g. --interval=1) still leaves a slow cold-start time to
+// finish, while a long cadence scales the window up with the interval.
+const POST_SPAWN_GRACE_FLOOR_MS = 90 * 1000;
+
+function watchdogSpawnBeaconPath(minionsHome) {
+  return path.join(minionsHome, 'engine', WATCHDOG_SPAWN_BEACON_NAME);
+}
+
+// Effective grace window: max(2 × interval, 90s). intervalMin defaults to the
+// scheduler's default cadence when the caller doesn't thread one through.
+function resolvePostSpawnGraceMs(intervalMin) {
+  const iv = Number.isFinite(intervalMin) && intervalMin > 0 ? intervalMin : DEFAULT_INTERVAL_MIN;
+  return Math.max(2 * iv * 60 * 1000, POST_SPAWN_GRACE_FLOOR_MS);
+}
+
+// Read the last-spawn timestamp (ms epoch) from the beacon. Returns null when
+// the beacon is missing, unreadable, or malformed — any of which means "no
+// recent spawn on record", so recovery proceeds (fail-open).
+function readSpawnBeaconTs(minionsHome) {
+  try {
+    const obj = JSON.parse(fs.readFileSync(watchdogSpawnBeaconPath(minionsHome), 'utf8'));
+    const ts = obj && Number(obj.ts);
+    return Number.isFinite(ts) ? ts : null;
+  } catch { return null; }
+}
+
+// Stamp the beacon just before we spawn. Failure is swallowed (fail-open): a
+// beacon we couldn't write must never block the recovery spawn — at worst we
+// lose the double-fire guard for one window, which is the pre-existing risk.
+function writeSpawnBeacon(minionsHome, nowMs, action) {
+  try {
+    const dir = path.join(minionsHome, 'engine');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(watchdogSpawnBeaconPath(minionsHome), JSON.stringify({ ts: nowMs, action }));
+  } catch { /* fail-open — recovery still proceeds */ }
+}
+
 function logLine(minionsHome, msg) {
   try {
     const dir = path.join(minionsHome, 'engine');
@@ -155,6 +203,24 @@ async function tick(opts) {
 
   const partial = engineAlive || dashUp;
   const action = partial ? 'restart' : 'start';
+
+  // Post-spawn grace: if a previous tick already issued a spawn within the
+  // grace window, stand down instead of double-firing. Each tick is a fresh
+  // stateless process, so the only memory is the on-disk beacon. This closes
+  // the slow-cold-start race where control.json's late PID write lets the next
+  // scheduled tick spawn a second daemon stack.
+  const graceMs = resolvePostSpawnGraceMs(opts.intervalMin);
+  const nowMs = now().getTime();
+  const lastSpawnTs = readSpawnBeaconTs(minionsHome);
+  if (lastSpawnTs != null && nowMs - lastSpawnTs < graceMs) {
+    logLine(
+      minionsHome,
+      `unhealthy but recent spawn ${nowMs - lastSpawnTs}ms ago (< grace ${graceMs}ms) ` +
+      `→ standing down (post-spawn grace, avoiding double-fire)`
+    );
+    return { healthy: false, action: 'skip', reason: 'post-spawn-grace' };
+  }
+
   logLine(
     minionsHome,
     `unhealthy engine=${enginePid || '-'}(${engineAlive ? 'alive' : 'dead'}) ` +
@@ -162,6 +228,11 @@ async function tick(opts) {
   );
 
   try {
+    // Stamp the spawn beacon BEFORE spawning so the next tick (which may fire
+    // before the new stack has bound its port / written control.json) sees the
+    // in-flight spawn and stands down. Write failure is swallowed — recovery
+    // proceeds regardless (fail-open).
+    writeSpawnBeacon(minionsHome, nowMs, action);
     // Detach the child so its lifetime is independent of this tick process.
     // The OS scheduler closes our stdio shortly after exit; we don't want
     // that closure to cascade into the new daemon stack.
@@ -477,6 +548,10 @@ module.exports = {
   MAC_PLIST_LABEL,
   LINUX_UNIT_NAME,
   WATCHDOG_LOG_NAME,
+  WATCHDOG_SPAWN_BEACON_NAME,
+  POST_SPAWN_GRACE_FLOOR_MS,
+  watchdogSpawnBeaconPath,
+  resolvePostSpawnGraceMs,
   buildMacPlist,
   buildLinuxService,
   buildLinuxTimer,