@yemi33/minions 0.1.2308 → 0.1.2309

package/bin/minions.js

@@ -391,6 +391,19 @@ function _resolveRestartHealthTimeoutMs() {
   return Math.min(300000, Math.max(15000, resolved));
 }
 
+/**
+ * Read config.json best-effort for callers that spawn engine.js before any
+ * config is loaded into memory. Mirrors _resolveRestartHealthTimeoutMs's
+ * inline read.
+ */
+function _readConfigJsonSafe() {
+  const home = process.env.MINIONS_HOME || (typeof MINIONS_HOME !== 'undefined' ? MINIONS_HOME : null);
+  try {
+    if (home) return JSON.parse(fs.readFileSync(path.join(home, 'config.json'), 'utf8'));
+  } catch { /* config may not exist yet */ }
+  return null;
+}
+
 /**
  * Spawn engine + dashboard + supervisor, verify health, optionally open browser.
  * Shared by `minions start` and `minions restart` — restart layers a kill phase
@@ -401,8 +414,14 @@ function _resolveRestartHealthTimeoutMs() {
 function spawnFullStackAndVerify({ rest, forceOpen, dashWasUp, restartStartMs }) {
   const engineOut = _openStdioLog('engine-stdio.log');
   const engineErr = _openStdioLog('engine-stdio.log');
+  // W-mr2c4i8m0004da94: enable Node's crash-diagnostics report for the
+  // engine.js process so a future silent death (the class investigated in
+  // W-mr2azk6i) leaves a JSON report under engine/diagnostics/crash-reports
+  // instead of vanishing with no trace.
+  const crashDiagEnv = shared.getEngineCrashDiagnosticsEnv(_readConfigJsonSafe());
   const engineProc = spawn(process.execPath, [..._sqliteSpawnFlags(), path.join(MINIONS_HOME, 'engine.js'), 'start', ...rest], {
-    cwd: MINIONS_HOME, stdio: ['ignore', engineOut, engineErr], detached: true, windowsHide: true
+    cwd: MINIONS_HOME, stdio: ['ignore', engineOut, engineErr], detached: true, windowsHide: true,
+    env: { ...process.env, ...crashDiagEnv }
   });
   engineProc.unref();
   console.log(`\n  Engine started (PID: ${engineProc.pid})`);
@@ -934,7 +953,8 @@ function init() {
     ? `\n  Upgrade complete (${pkgVersion}). Restarting engine and dashboard...\n`
     : '\n  Starting engine and dashboard...\n');
   const engineProc = spawn(process.execPath, [..._sqliteSpawnFlags(), path.join(MINIONS_HOME, 'engine.js'), 'start'], {
-    cwd: MINIONS_HOME, stdio: 'ignore', detached: true, windowsHide: true
+    cwd: MINIONS_HOME, stdio: 'ignore', detached: true, windowsHide: true,
+    env: { ...process.env, ...shared.getEngineCrashDiagnosticsEnv(_readConfigJsonSafe()) }
   });
   engineProc.unref();
   console.log(`  Engine started (PID: ${engineProc.pid})`);

package/docs/README.md

@@ -61,6 +61,7 @@ Operational runbooks for engine operators and fleet maintainers.
 - [notes.md](notes.md) — Consolidated team knowledge: patterns, conventions, bugs, and build findings accumulated from agent inbox notes. Read by the engine and injected into agent prompts as shared context.
 - [auto-discovery.md](auto-discovery.md) — Auto-discovery and execution pipeline: the per-tick orchestration loop and the four work-discovery sources.
 - [diagnostics-memory.md](diagnostics-memory.md) — Operator runbook for the in-process memory + perf observability surface: `/api/diagnostics/memory[/history]`, `/api/diagnostics/heap-snapshot` guard-token capture, `MEMORY_BASELINE` log emissions, `--cpu-prof`/`--heap-prof` capture, and the `test/perf/soak.test.js` heap-growth regression gate.
+- [diagnostics-crash-reports.md](diagnostics-crash-reports.md) — Proactive Node crash-diagnostics reports (`--report-on-fatalerror --report-on-signal --diagnostic-dir=...`) for the engine.js process on Windows: where reports land, config/opt-out, and retention.
 - [engine-restart.md](engine-restart.md) — How agents survive an engine restart: state persistence, the 20-minute startup grace period, and orphan reattachment via PID files and `live-output.log`.
 - [human-vs-automated.md](human-vs-automated.md) — Quick reference table of which features humans start, run, decide, and recover, and the two human approval gates.
 - [kb-sweep.md](kb-sweep.md) — Knowledge-base sweep runbook: how `engine/kb-sweep.js` consolidates `notes/inbox/` into `knowledge/` and survives `minions restart`.

package/docs/diagnostics-crash-reports.md

@@ -0,0 +1,132 @@
+# Diagnostics: crash reports for the engine.js process (Windows)
+
+Operator runbook for the proactive crash-diagnostics feature shipped for
+`W-mr2c4i8m0004da94`. Follow-up from `W-mr2azk6i` (2026-07-01 engine.js
+crash-loop investigation): a run of 4 silent `engine.js` deaths left no
+exception/stack trace in `engine-stdio.log`, no Windows Event Viewer
+entries (Application/System logs were empty for the window), and no crash
+dumps in `C:\Windows\Minidump` or `%LOCALAPPDATA%\CrashDumps`. The box had
+no crash-event logging wired up at all, so a genuine native/access-violation
+crash of `node.exe` would have vanished without a trace.
+
+## What this does
+
+Every spawn of `engine.js` — via `minions start`/`restart` (`bin/minions.js`)
+**and** the supervisor's respawn-on-death path (`engine/supervisor.js`) —
+now gets Node's own diagnostic-report flags folded into `NODE_OPTIONS`:
+
+```
+--report-on-fatalerror --report-on-signal --diagnostic-dir=<MINIONS_HOME>/engine/diagnostics/crash-reports
+```
+
+This is a zero-dependency, built-in Node feature (no Sysinternals ProcDump
+or other external tool needed):
+
+- **`--report-on-fatalerror`** — writes a JSON diagnostic report the moment
+  the process hits an unrecoverable V8 error: out-of-memory, JS stack
+  overflow, or a native-addon crash. This is exactly the class of death a
+  silent `node.exe` disappearance on Windows would otherwise hide.
+- **`--report-on-signal`** — lets an operator request a report on demand by
+  sending the configured signal to the running engine PID: `SIGUSR2` on
+  POSIX, `SIGBREAK` on Windows (Node's default `--report-signal`). Useful to
+  capture a report while a hang is in progress, before deciding to kill it.
+- **`--diagnostic-dir=...`** — where both of the above land.
+
+Reports are plain JSON (`report.<timestamp>.<pid>.<seq>.json`) containing
+the JS/native stack, loaded modules, resource usage, and libuv handle
+summary at the moment of the event — see [Node's diagnostic report
+docs](https://nodejs.org/api/report.html) for the full schema.
+
+## Where reports land
+
+`<MINIONS_HOME>/engine/diagnostics/crash-reports/` — a sibling of the
+existing `engine/diagnostics/` directory used for heap snapshots and
+CPU/heap profiles (see [docs/diagnostics-memory.md](diagnostics-memory.md)
+§3–4), in its own subfolder so retention sweeps don't collide. The directory
+is gitignored and created on first spawn if missing
+(`getEngineCrashDiagnosticsEnv`, [`engine/shared.js`](../engine/shared.js)).
+
+## Config + opt-out
+
+```json
+{
+  "engine": {
+    "crashDiagnostics": {
+      "enabled": true,
+      "retainCount": 20
+    }
+  }
+}
+```
+
+- `enabled` (default `true`) — set `false` to disable the NODE_OPTIONS
+  injection entirely (falls back to the pre-existing no-diagnostics
+  behavior).
+- `retainCount` (default `20`) — how many `report.*.json` files are kept
+  before the oldest are pruned. Restart the engine (`minions restart`)
+  after editing `enabled`, since it only takes effect at the next spawn.
+
+Both live in `ENGINE_DEFAULTS.crashDiagnostics`
+([`engine/shared.js`](../engine/shared.js)).
+
+## Retention / cleanup
+
+Reports are pruned by `pruneCrashDiagnosticsReports` (`engine/shared.js`),
+called from `engine/cleanup.js#runCleanup` — the same periodic cleanup pass
+that already runs every `ENGINE_DEFAULTS.cleanupEvery` ticks (default 60
+ticks ≈ 10 min at the default 10 s tick interval). It keeps the newest
+`retainCount` files by mtime and deletes the rest, mirroring the existing
+heap-snapshot retention pattern in `dashboard.js#_heapSnapshotPrune`. Pruning
+is best-effort: a missing directory or a transient Windows file lock is
+swallowed and retried on the next cleanup pass.
+
+## Idempotency across the CLI → supervisor respawn chain
+
+Both `bin/minions.js` (initial spawn) and `engine/supervisor.js` (respawn on
+death) call the same `getEngineCrashDiagnosticsEnv(config)` helper. It checks
+whether the caller's `NODE_OPTIONS` already contains `--diagnostic-dir=`
+(which a spawned child inherits from its parent's env) and returns `{}`
+unchanged if so — so a CLI-spawned engine that later gets respawned by the
+supervisor never accumulates duplicate flags.
+
+## Inspecting a report after a crash
+
+```powershell
+Get-ChildItem "$env:USERPROFILE\.minions\engine\diagnostics\crash-reports" |
+  Sort-Object LastWriteTime -Descending | Select-Object -First 5
+
+Get-Content "$env:USERPROFILE\.minions\engine\diagnostics\crash-reports\report.<ts>.<pid>.001.json" |
+  ConvertFrom-Json | Select-Object javascriptStack, header
+```
+
+Key fields to check first: `header.event` (what triggered the report,
+e.g. `"FatalError"` or `"Signal"`), `javascriptStack`, `nativeStack`, and
+`resourceUsage` (memory/CPU at the moment of the event).
+
+## Requesting a report on demand (hang investigation)
+
+```powershell
+# Find the engine PID from engine/control.json, then:
+# Windows: send SIGBREAK-equivalent via node's report trigger utility, or
+# use Node's process.report.writeReport() interactively if you have a REPL
+# attached. The simplest cross-platform trigger is `process.kill(pid, 'SIGBREAK')`
+# from another Node process on Windows.
+node -e "process.kill(<pid>, 'SIGBREAK')"
+```
+
+A fresh `report.*.json` should appear in the crash-reports directory within
+a second or two, without killing the process.
+
+## Related modules and tests
+
+- Module: [`engine/shared.js`](../engine/shared.js) — `CRASH_REPORTS_DIR`,
+  `getEngineCrashDiagnosticsEnv`, `pruneCrashDiagnosticsReports`,
+  `ENGINE_DEFAULTS.crashDiagnostics`.
+- Spawn wiring: [`bin/minions.js`](../bin/minions.js)
+  (`spawnFullStackAndVerify`, the post-install/upgrade auto-start path) and
+  [`engine/supervisor.js`](../engine/supervisor.js) (`spawnEngine`).
+- Cleanup wiring: [`engine/cleanup.js`](../engine/cleanup.js) `runCleanup`.
+- Tests: [`test/unit/crash-diagnostics.test.js`](../test/unit/crash-diagnostics.test.js).
+- Related: [docs/diagnostics-memory.md](diagnostics-memory.md) (memory/GC/heap
+  observability — the sibling diagnostics surface this doc's directory lives
+  next to).

package/engine/cleanup.js

@@ -1633,6 +1633,19 @@ async function runCleanup(config, verbose = false) {
     cleaned.knowledgeScratch = reapKnowledgeScratch();
   } catch (e) { log('warn', `reapKnowledgeScratch: ${e.message}`); }
 
+  // 18. Prune old Node crash-diagnostics reports (W-mr2c4i8m0004da94). Node
+  // writes `report.*.json` to CRASH_REPORTS_DIR on a fatal V8 error or
+  // `--report-on-signal` request — see getEngineCrashDiagnosticsEnv. Keep
+  // only the newest config.engine.crashDiagnostics.retainCount (default 20)
+  // so a crash-loop or repeated on-demand reports don't accumulate unbounded.
+  cleaned.crashReports = 0;
+  try {
+    cleaned.crashReports = shared.pruneCrashDiagnosticsReports(config);
+    if (cleaned.crashReports > 0) {
+      log('info', `cleanup: pruned ${cleaned.crashReports} old crash-diagnostics report(s)`);
+    }
+  } catch (e) { log('warn', `pruneCrashDiagnosticsReports: ${e.message}`); }
+
   return cleaned;
 }
 

package/engine/shared.js

@@ -58,6 +58,13 @@ const MINIONS_DIR = process.env.MINIONS_TEST_DIR || resolveMinionsHome(false, {
   preferSourceCheckout: true,
 });
 const ENGINE_DIR = path.join(MINIONS_DIR, 'engine');
+// W-mr2c4i8m0004da94: Node's built-in `--diagnostic-dir` target for the
+// engine.js process's crash-diagnostics report (see
+// getEngineCrashDiagnosticsEnv / pruneCrashDiagnosticsReports below and
+// docs/diagnostics-crash-reports.md). Sibling of the existing
+// engine/diagnostics/ heap-snapshot dir, own subfolder so retention sweeps
+// don't collide with heap-snapshot pruning.
+const CRASH_REPORTS_DIR = path.join(ENGINE_DIR, 'diagnostics', 'crash-reports');
 const CONTROL_PATH = path.join(ENGINE_DIR, 'control.json');
 const COOLDOWNS_PATH = path.join(ENGINE_DIR, 'cooldowns.json');
 // W-mp60tw0u000j3931: Persistent cross-restart engine state (migration markers,
@@ -1633,6 +1640,69 @@ function openAppendLogFd(name, dir, opts) {
   }
 }
 
+// W-mr2c4i8m0004da94: proactive crash diagnostics for the engine.js node
+// process on Windows. Follow-up from W-mr2azk6i (2026-07-01 crash-loop
+// investigation): 4 silent engine.js deaths with no exception in
+// engine-stdio.log, no Windows Event Viewer entries, and no crash dumps —
+// this box had no crash-event logging wired up for a genuine native/AV
+// crash. Node's own diagnostic-report feature is a zero-dependency fix:
+// `--report-on-fatalerror` writes a JSON report on unrecoverable V8 errors
+// (OOM, stack overflow, native-addon segfault) and `--report-on-signal`
+// lets an operator request one on demand (SIGUSR2 on POSIX, SIGBREAK on
+// Windows) without installing anything (e.g. Sysinternals ProcDump).
+//
+// Callers: bin/minions.js (CLI `start`/`restart` spawn) and
+// engine/supervisor.js (respawn-on-death). Both spawn engine.js as a fresh
+// process before any config is loaded into memory, so this reads config.json
+// directly rather than expecting an already-parsed config object — pass the
+// parsed object in if the caller already has it (e.g. from its own
+// best-effort config.json read), or `null`/`undefined` to use the defaults.
+//
+// Idempotent: if the caller's NODE_OPTIONS already carries
+// `--diagnostic-dir=`, returns `{}` unchanged so the CLI's spawn -> a later
+// supervisor respawn -> another respawn chain never piles up duplicate
+// flags (child processes inherit NODE_OPTIONS from their parent env).
+function getEngineCrashDiagnosticsEnv(config, baseEnv) {
+  const env = baseEnv || process.env;
+  const cfg = (config && config.engine && config.engine.crashDiagnostics) || {};
+  const defaults = ENGINE_DEFAULTS.crashDiagnostics || {};
+  const enabled = cfg.enabled !== undefined ? cfg.enabled !== false : defaults.enabled !== false;
+  if (!enabled) return {};
+  const existing = String(env.NODE_OPTIONS || '');
+  if (existing.includes('--diagnostic-dir=')) return {};
+  try { fs.mkdirSync(CRASH_REPORTS_DIR, { recursive: true }); } catch { /* best effort — Node still tries to write on crash */ }
+  const flags = `--report-on-fatalerror --report-on-signal --diagnostic-dir=${CRASH_REPORTS_DIR}`;
+  return { NODE_OPTIONS: existing ? `${existing} ${flags}` : flags };
+}
+
+// Prune `report.*.json` files in CRASH_REPORTS_DIR down to the most-recent
+// `retainCount` (config.engine.crashDiagnostics.retainCount, default 20) by
+// mtime, mirroring dashboard.js's `_heapSnapshotPrune` retention pattern so
+// a leak-hunt session (or a genuine crash-loop) doesn't fill the disk with
+// reports unbounded. Best-effort: missing dir / unreadable stat / failed
+// unlink are swallowed. Called from engine/cleanup.js#runCleanup (fires
+// every ENGINE_DEFAULTS.cleanupEvery ticks, ~10 min at default tick
+// interval) so retention happens automatically without a dedicated sweep.
+function pruneCrashDiagnosticsReports(config) {
+  const cfg = (config && config.engine && config.engine.crashDiagnostics) || {};
+  const defaults = ENGINE_DEFAULTS.crashDiagnostics || {};
+  const retain = Number.isFinite(cfg.retainCount) ? cfg.retainCount : (defaults.retainCount || 20);
+  let names;
+  try { names = fs.readdirSync(CRASH_REPORTS_DIR); } catch { return 0; }
+  const candidates = names.filter(n => n.startsWith('report.') && n.endsWith('.json'));
+  if (candidates.length <= retain) return 0;
+  const stamped = candidates.map(n => {
+    try { return { n, mtime: fs.statSync(path.join(CRASH_REPORTS_DIR, n)).mtimeMs }; }
+    catch { return { n, mtime: 0 }; }
+  });
+  stamped.sort((a, b) => b.mtime - a.mtime); // newest first
+  let removed = 0;
+  for (const s of stamped.slice(retain)) {
+    try { fs.unlinkSync(path.join(CRASH_REPORTS_DIR, s.n)); removed++; } catch { /* best effort */ }
+  }
+  return removed;
+}
+
 function withFileLock(lockPath, fn, {
   timeoutMs = 5000,
   retryDelayMs = 25,
@@ -3156,6 +3226,19 @@ const ENGINE_DEFAULTS = {
   // at the default 10s tickInterval. Set to 0 (or any non-positive integer)
   // to disable both the log emission and sidecar write cleanly (operator opt-out).
   memoryBaselineEveryTicks: 6,
+  // W-mr2c4i8m0004da94: proactive crash diagnostics for the engine.js
+  // node.exe process. When enabled (default), every spawn of engine.js
+  // (bin/minions.js `start`/`restart` AND engine/supervisor.js respawn-on-
+  // death) gets NODE_OPTIONS += `--report-on-fatalerror --report-on-signal
+  // --diagnostic-dir=<CRASH_REPORTS_DIR>` so a fatal V8 error (OOM, stack
+  // overflow, native-addon crash) or an operator-sent signal
+  // (SIGUSR2 POSIX / SIGBREAK Windows) leaves a JSON diagnostic report
+  // instead of a silent death. See getEngineCrashDiagnosticsEnv,
+  // pruneCrashDiagnosticsReports, and docs/diagnostics-crash-reports.md.
+  crashDiagnostics: {
+    enabled: true,
+    retainCount: 20, // report.*.json files kept in CRASH_REPORTS_DIR; oldest pruned during runCleanup (cleanupEvery ticks)
+  },
   stalledDispatchSweepEvery: 120,    // stalled-dispatch retry sweep (~20 min at default 10s tick) — only fires when all agents idle
   // W-mp5trwh60008386d: per-PR 404 must repeat across N consecutive successful base-repo probes
   // before flipping a PR to `abandoned`. A single 404 on `repos/{slug}/pulls/{n}` can be a transient
@@ -9091,6 +9174,9 @@ function createBackoffTracker({ baseMs = 30000, maxMs = 10 * 60 * 1000 } = {}) {
 module.exports = {
   MINIONS_DIR,
   ENGINE_DIR,
+  CRASH_REPORTS_DIR,
+  getEngineCrashDiagnosticsEnv,
+  pruneCrashDiagnosticsReports,
   resolveEngineCacheDir,
   openUrlInBrowser,
   CONTROL_PATH,

package/engine/supervisor.js

@@ -347,6 +347,18 @@ function _sqliteSpawnFlags() {
   return ['--experimental-sqlite'];
 }
 
+// W-mr2c4i8m0004da94: crash-diagnostics env additions for a supervisor-
+// initiated respawn. Best-effort config.json read — the supervisor spawns
+// engine.js before any config is loaded into memory, mirroring the same
+// read bin/minions.js does for its own engine spawns.
+function _engineCrashDiagnosticsEnv() {
+  const shared = _sharedOrNull();
+  if (!shared || typeof shared.getEngineCrashDiagnosticsEnv !== 'function') return {};
+  let cfg = null;
+  try { cfg = JSON.parse(fs.readFileSync(path.join(MINIONS_DIR, 'config.json'), 'utf8')); } catch { /* config may not exist */ }
+  try { return shared.getEngineCrashDiagnosticsEnv(cfg); } catch { return {}; }
+}
+
 function spawnEngine() {
   const out = openAppendFd('engine-stdio.log');
   const err = openAppendFd('engine-stdio.log');
@@ -355,6 +367,7 @@ function spawnEngine() {
     stdio: ['ignore', out, err],
     detached: true,
     windowsHide: true,
+    env: { ...process.env, ..._engineCrashDiagnosticsEnv() },
   });
   proc.unref();
   return proc.pid;

package/package.json

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