@yemi33/minions 0.1.2447 → 0.1.2449

package/engine/{qa-runners.js → qa-runners/index.js}

@@ -1,8 +1,8 @@
 /**
- * engine/qa-runners.js — P-b8e1d4a6
+ * engine/qa-runners/index.js — P-b8e1d4a6
  *
  * Pluggable test-runner registry for QA Sessions. Mirrors the
- * engine/watches.js target-type registry pattern (registerTargetType /
+ * engine/watches/index.js target-type registry pattern (registerTargetType /
  * getTargetType / listTargetTypes / plugin folder discovery).
  *
  * A runner adapter teaches QA Sessions how to translate a natural-language
@@ -52,10 +52,10 @@
  *   or an array of those objects for multi-runner plugins. Bad plugin files
  *   log WARN with the file path and do NOT block sibling plugins or built-in
  *   runners from registering. A missing qa-runners.d/ directory is a silent
- *   no-op (matches watches.d/ behaviour).
+ *   no-op (matches watch-plugins/ behaviour).
  *
  * Security: plugins are user-trusted JS (same trust level as `playbooks/`
- * and `watches.d/`); no sandboxing. Hot-reload is not supported at module
+ * and `watch-plugins/`); no sandboxing. Hot-reload is not supported at module
  * level — restart the engine to pick up new plugin files, or POST
  * /api/qa/runners/reload (implemented in P-d2f5a8c9) which re-invokes
  * loadRunnerPlugins().
@@ -65,7 +65,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const shared = require('./shared');
+const shared = require('../core/shared');
 const { log } = shared;
 
 const _KEBAB_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
@@ -227,7 +227,7 @@ function detectRunner(target, project, explicitRunner) {
 }
 
 // ── Plugin folder discovery (qa-runners.d/) ─────────────────────────────────
-// Mirrors engine/watches.js:_loadPluginTargetTypes (W-mp7hg58e000b5212).
+// Mirrors engine/watches/index.js:_loadPluginTargetTypes.
 // Auto-loaded at module load time below. Tests bust the require cache via
 // test/_helpers.js ISOLATED_MODULES so MINIONS_TEST_DIR/qa-runners.d/ takes
 // effect on every createTestMinionsDir() boundary.
@@ -282,7 +282,7 @@ function _clearRunners() {
 // disk plugins. Built-ins are required relative to this file (not
 // MINIONS_DIR) so test isolation can't strand them on a stale module path.
 function _registerBuiltins() {
-  const BUILTIN_FILES = ['./qa-runners/maestro', './qa-runners/playwright'];
+  const BUILTIN_FILES = ['./maestro', './playwright'];
   for (const rel of BUILTIN_FILES) {
     try {
       const resolved = require.resolve(rel);

package/engine/qa-runners/maestro.js

@@ -2,15 +2,15 @@
  * engine/qa-runners/maestro.js — P-c4a9e7f3
  *
  * Maestro built-in runner adapter for QA Sessions. Registered at boot by
- * engine/qa-runners.js (_registerBuiltins). Priority 80 — higher than the
+ * engine/qa-runners/index.js (_registerBuiltins). Priority 80 — higher than the
  * Playwright safe default so a project with `.maestro/` wins on tie.
  *
  * Detection: project.localPath (or target.worktree for kind='current') has
  * a `.maestro/` directory. Explicit `runner: 'maestro'` is honoured directly
- * by qa-runners.js#detectRunner before detect() runs, so it does not need
+ * by qa-runners/index.js#detectRunner before detect() runs, so it does not need
  * a branch here.
  *
- * Hooks: see engine/qa-runners.js header for the contract. We return
+ * Hooks: see engine/qa-runners/index.js for the contract. We return
  * markdown strings from generateBrief / executeBrief — those flow into the
  * qa-session-draft.md / qa-session-execute.md playbooks as {{runner_brief}}
  * and {{runner_execute_brief}} (wired in P-f9a2e1b4).

package/engine/qa-runners/playwright.js

@@ -2,7 +2,7 @@
  * engine/qa-runners/playwright.js — P-c4a9e7f3
  *
  * Playwright built-in runner adapter for QA Sessions. Registered at boot by
- * engine/qa-runners.js (_registerBuiltins). Priority 50 — the safe default
+ * engine/qa-runners/index.js (_registerBuiltins). Priority 50 — the safe default
  * for any HTTP target. Maestro (priority 80) wins on detect tie when the
  * project has `.maestro/`.
  *
@@ -12,7 +12,7 @@
  * priority gate above lets Maestro win when present; explicit
  * `runner: '...'` overrides win before detect() runs at all.
  *
- * Hooks: see engine/qa-runners.js header for the contract.
+ * Hooks: see engine/qa-runners/index.js for the contract.
  */
 
 const fs = require('fs');

package/engine/{restart-health.js → recovery/restart-health.js}

@@ -3,7 +3,7 @@ const path = require('path');
 const http = require('http');
 const https = require('https');
 const { execSync } = require('child_process');
-const shared = require('./shared');
+const shared = require('../core/shared');
 
 // W-mqpx0tpi — single source of truth for the cold-start health budget. The
 // old fixed 15s was too short for a post-`npm install` dashboard boot on a
@@ -15,6 +15,7 @@ const shared = require('./shared');
 // the literal is only a fallback if shared somehow failed to load.
 const DEFAULT_RESTART_HEALTH_TIMEOUT_MS =
   (shared.ENGINE_DEFAULTS && shared.ENGINE_DEFAULTS.restartHealthTimeoutMs) || 60000;
+const RESTART_HEALTH_FRESH_HEARTBEAT_MS = 30000;
 const DEFAULT_RESTART_HEALTH_INTERVAL_MS = 100;
 const DEFAULT_DIAGNOSTIC_LOG_MAX_BYTES = 8192;
 // Consecutive dead-PID reads tolerated before fail-fast. A small guard avoids
@@ -192,8 +193,13 @@ async function checkRestartHealth(options = {}) {
   const control = readControl(minionsHome);
   const pid = normalizePid(control && control.pid);
   const expectedEngine = normalizePid(expectedEnginePid);
-  const engineAlive = pid ? isAlive(pid) : false;
   const engineOwned = expectedEngine == null || pid === expectedEngine;
+  const heartbeat = Number(control?.heartbeat);
+  const heartbeatFresh = Number.isFinite(heartbeat)
+    && heartbeat > 0
+    && Date.now() - heartbeat <= RESTART_HEALTH_FRESH_HEARTBEAT_MS;
+  const engineProbeAlive = pid ? isAlive(pid) : false;
+  const engineAlive = engineProbeAlive || (engineOwned && heartbeatFresh);
   const engineOk = control && control.state === 'running' && engineAlive && engineOwned;
 
   // Two strategies for the dashboard check:
@@ -214,7 +220,7 @@ async function checkRestartHealth(options = {}) {
   if (dashboardPid != null && !dashboardUrl) {
     dashboardKind = 'process';
     const dpid = normalizePid(dashboardPid);
-    const dashAlive = dpid ? isAlive(dpid) : false;
+    const dashProbeAlive = dpid ? isAlive(dpid) : false;
     // Ownership gate (opt-in via requireBeaconOwner). "PID alive + port
     // listening" is NOT sufficient: a stale pre-restart dashboard still holding
     // the port satisfies the listening probe, so the verifier used to report
@@ -240,6 +246,7 @@ async function checkRestartHealth(options = {}) {
     // netstat — the dashboard writes dashboard-port.json in its listen() callback,
     // so beacon.pid === dpid IS the port-bind signal.
     const portOpen = (options.requireBeaconOwner && beaconOwned) ? true : portCheck(dashboardPort);
+    const dashAlive = dashProbeAlive || !!(options.requireBeaconOwner && beaconOwned && portOpen);
     dashboardOk = !!(dashAlive && portOpen && beaconOwned);
     dashboardDetail = `pid=${dpid || 'none'} alive=${dashAlive ? 'yes' : 'no'} port=${dashboardPort} listening=${portOpen ? 'yes' : 'no'}`
       + (options.requireBeaconOwner ? ` beaconPid=${beaconPid || 'none'} owned=${beaconOwned ? 'yes' : 'no'}` : '');
@@ -323,7 +330,14 @@ async function checkRestartHealth(options = {}) {
 
   return {
     ok: engineOk && dashboardOk && supervisorOk && topologyOk,
-    engine: { state: control && control.state, pid, alive: engineAlive, owned: engineOwned },
+    engine: {
+      state: control && control.state,
+      pid,
+      alive: engineAlive,
+      probeAlive: engineProbeAlive,
+      heartbeatFresh,
+      owned: engineOwned,
+    },
     dashboard: dashboardSnapshot,
     supervisor: supervisorSnapshot,
     topology: topologySnapshot,
@@ -331,6 +345,35 @@ async function checkRestartHealth(options = {}) {
   };
 }
 
+async function confirmRestartHealthBeforeCleanup(options = {}) {
+  const ownership = await checkRestartHealth({
+    ...options,
+    // Exclusive process enumeration is a useful restart invariant, but it is
+    // not strong enough to justify killing an otherwise healthy owned stack.
+    // Re-prove the expected PIDs, beacon, heartbeat, and supervisor immediately
+    // before destructive cleanup.
+    requireExactTopology: false,
+    listProcessPids: undefined,
+    topologyScripts: undefined,
+  });
+  if (!ownership.ok) return ownership;
+
+  const http = await checkRestartHealth({
+    ...options,
+    dashboardPid: null,
+    requireBeaconOwner: false,
+    requireExactTopology: false,
+    listProcessPids: undefined,
+    topologyScripts: undefined,
+  });
+  return {
+    ...ownership,
+    ok: http.ok,
+    dashboardHttp: http.dashboard,
+    errors: http.ok ? [] : http.errors,
+  };
+}
+
 async function waitForRestartHealth(options = {}) {
   const timeoutMs = options.timeoutMs ?? DEFAULT_RESTART_HEALTH_TIMEOUT_MS;
   const intervalMs = options.intervalMs ?? DEFAULT_RESTART_HEALTH_INTERVAL_MS;
@@ -431,6 +474,7 @@ module.exports = {
   DEFAULT_RESTART_HEALTH_TIMEOUT_MS,
   DEFAULT_RESTART_HEALTH_INTERVAL_MS,
   checkRestartHealth,
+  confirmRestartHealthBeforeCleanup,
   waitForRestartHealth,
   formatRestartHealthError,
   _private: {