@yemi33/minions 0.1.2447 → 0.1.2449

package/engine/{managed-spawn.js → processes/managed-spawn.js}

@@ -1,8 +1,8 @@
 /**
- * engine/managed-spawn.js — Item 1 of plan P-7a3b1c92.
+ * engine/processes/managed-spawn.js — Item 1 of plan P-7a3b1c92.
  *
  * Schema, validator, sidecar reader, acceptance helper, and playbook hint for
- * the managed-spawn primitive. Mirrors engine/keep-process-sweep.js
+ * the managed-spawn primitive. Mirrors engine/processes/keep-process-sweep.js
  * beat-for-beat: an agent writes agents/<id>/managed-spawn.json describing
  * long-running services it wants the engine to spawn + healthcheck on its
  * behalf; this module validates the file, returns a structured acceptance
@@ -13,7 +13,7 @@
  * plan items (P-7a3b1c93+). This module is pure: no spawns, no network, no
  * mutation of shared state.
  *
- * Design template: engine/keep-process-sweep.js. Divergences are justified
+ * Design template: engine/processes/keep-process-sweep.js. Divergences are justified
  * inline; symmetry with keep-pids is the convention.
  */
 
@@ -22,8 +22,8 @@ const path = require('path');
 const http = require('http');
 const https = require('https');
 const { spawn, exec } = require('child_process');
-const shared = require('./shared');
-const queries = require('./queries');
+const shared = require('../core/shared');
+const queries = require('../core/queries');
 const processUtils = require('./process-utils');
 
 const { log, ENGINE_DEFAULTS } = shared;
@@ -801,7 +801,7 @@ function buildManagedSpawnHint(opts) {
     '}',
     '```',
     '',
-    'Known device-farm tooling to reach for instead of re-deriving a pattern from scratch: `adb` and `emulator` (both on the managed-spawn executable allowlist — device/emulator shell, install, logcat; `emulator -list-avds` discovers configured AVDs before you pick one for the spec), and `maestro` (declarative mobile UI-flow runner already wired in as a built-in QA runner adapter — see `engine/qa-runners.js` — for the DRAFT/EXECUTE phases, not for the managed-spawn `cmd`/healthcheck allowlist itself).',
+    'Known device-farm tooling to reach for instead of re-deriving a pattern from scratch: `adb` and `emulator` (both on the managed-spawn executable allowlist — device/emulator shell, install, logcat; `emulator -list-avds` discovers configured AVDs before you pick one for the spec), and `maestro` (declarative mobile UI-flow runner already wired in as a built-in QA runner adapter — see `engine/qa-runners/index.js` — for the DRAFT/EXECUTE phases, not for the managed-spawn `cmd`/healthcheck allowlist itself).',
     '',
     '### Verify before exit',
     '',
@@ -1174,11 +1174,32 @@ function reapOrTrackManagedRuntime(spec, runtime, ctx, options = {}) {
   // back to a liveness re-check + sweep-retry tracking when the kill itself
   // FAILED (or there was no pid to kill).
   let killed = false;
+  // A CONCLUSIVE identity mismatch — a real creation time that is later than
+  // the child we recorded — proves the PID is not ours (recycled, or an
+  // EPERM-guarded foreign/system process that isPidAlive reports as alive).
+  // There is nothing of ours to reap, so do not signal it, and do not pin the
+  // runtime into the sweep-retry loop forever (W-ms8d10y3003t0588).
+  let foreignPid = false;
   if (Number.isInteger(pid) && pid > 0) {
-    try { killed = shared.killImmediate({ pid }) !== false; }
-    catch (_e) { killed = false; }
+    const getIdentity = typeof options.getProcessIdentity === 'function'
+      ? options.getProcessIdentity
+      : processUtils.getProcessIdentity;
+    let expectedIdentity = null;
+    try { expectedIdentity = getIdentity(pid); } catch { /* fail closed below */ }
+    foreignPid = processUtils.isProcessIdentityConclusiveMismatch(
+      expectedIdentity,
+      _managedStartedAtMs(runtime),
+    );
+    if (!foreignPid) {
+      try {
+        killed = shared.terminateProcess('engine.managed-spawn.reap-failed', { pid }, {
+          expectedIdentity,
+        }) !== false;
+      }
+      catch (_e) { killed = false; }
+    }
   }
-  if (killed || !shared.isPidAlive(pid)) return { reaped: true, tracked: false };
+  if (foreignPid || killed || !shared.isPidAlive(pid)) return { reaped: true, tracked: false };
 
   const record = _toStateRecord(spec, runtime, ctx);
   record.healthy = false;
@@ -1227,17 +1248,47 @@ function removeManagedSpec(name, opts = {}) {
     return { removed: false, reason: 'generation-changed' };
   }
   const killPid = Number.isInteger(candidate.pid) && candidate.pid > 0 ? candidate.pid : null;
-  const verifyIdentity = opts.verifyIdentity === true;
+  const verifyIdentity = opts.verifyIdentity !== false;
   const getIdentity = typeof opts.getProcessIdentity === 'function'
     ? opts.getProcessIdentity
     : processUtils.getProcessIdentity;
+  // Tri-state probe (W-ms6dmv99005o26f4), consulted ONLY to interpret a null
+  // identity. `getIdentity` keeps priority so the injected/monkey-patched
+  // getProcessIdentity seams used by callers and tests are unaffected.
+  const inspectIdentity = typeof opts.inspectProcessIdentity === 'function'
+    ? opts.inspectProcessIdentity
+    : processUtils.inspectProcessIdentity;
   const wasAlive = killPid !== null && shared.isPidAlive(killPid);
   let identityBefore = null;
   if (verifyIdentity && wasAlive) {
     identityBefore = getIdentity(killPid);
-    if (!identityBefore) return { removed: false, reason: 'identity-unavailable' };
-    if (!processUtils.isProcessIdentityCompatible(identityBefore, _managedStartedAtMs(candidate))) {
-      return { removed: false, reason: 'identity-mismatch' };
+    if (!identityBefore) {
+      // A null identity is not one condition but two, and they demand opposite
+      // handling. isPidAlive() reports EPERM as alive (the kernel found the
+      // process and refused the signal), so a foreign/system process — or a
+      // recycled PID number no longer ours — now reaches this branch.
+      //   CONCLUSIVE absence from the process table → the PID is demonstrably
+      //     not our managed child; there is nothing of ours to kill, so drop
+      //     the stale record instead of pinning it forever.
+      //   INCONCLUSIVE (enumeration failed, no start time) → we learned
+      //     nothing; preserve the spec so a later sweep can retry.
+      let conclusive = false;
+      try { conclusive = inspectIdentity(killPid).conclusive === true; }
+      catch { conclusive = false; }
+      if (!conclusive) return { removed: false, reason: 'identity-unavailable' };
+    } else if (!processUtils.isProcessIdentityCompatible(identityBefore, _managedStartedAtMs(candidate))) {
+      // Same split as the null branch above. A CONCLUSIVE mismatch (a real
+      // creation time later than the child we recorded) is exactly as decisive
+      // as a conclusive absence: the PID is demonstrably not our managed child,
+      // so drop the stale record instead of pinning it forever behind
+      // `identity-mismatch` — which leaked the spec through
+      // removeManagedSpecsForProject and re-failed on every sweep retry
+      // (W-ms8d10y3003t0588). Clearing identityBefore routes it into the same
+      // never-signal path the conclusive-absence case uses.
+      if (!processUtils.isProcessIdentityConclusiveMismatch(identityBefore, _managedStartedAtMs(candidate))) {
+        return { removed: false, reason: 'identity-mismatch' };
+      }
+      identityBefore = null;
     }
   }
 
@@ -1268,15 +1319,21 @@ function removeManagedSpec(name, opts = {}) {
   // qemu-system-x86_64 child) whose descendants survive a single-PID kill and
   // leak indefinitely (opg-microsoft/minions#710).
   let killed = false;
-  if (killPid !== null && (!verifyIdentity || wasAlive)) {
-    if (verifyIdentity) {
-      const identityAfter = getIdentity(killPid);
-      if (!processUtils.isSameProcessIdentity(identityBefore, identityAfter)) {
-        _restoreManagedRecord(removedRecord);
-        return { removed: false, reason: 'identity-changed' };
-      }
+  // `identityBefore` is required: reaching here with a null identity means the
+  // PID was CONCLUSIVELY absent from the process table, or its live identity
+  // CONCLUSIVELY proved it is not our child (see above). Either way there is no
+  // verified target and we must not fire a kill at a foreign PID.
+  if (killPid !== null && verifyIdentity && wasAlive && identityBefore) {
+    const identityAfter = getIdentity(killPid);
+    if (!processUtils.isSameProcessIdentity(identityBefore, identityAfter)) {
+      _restoreManagedRecord(removedRecord);
+      return { removed: false, reason: 'identity-changed' };
+    }
+    try {
+      killed = shared.terminateProcess('engine.managed-spawn.remove', { pid: killPid }, {
+        expectedIdentity: identityAfter,
+      }) !== false;
     }
-    try { killed = shared.killImmediate({ pid: killPid }) !== false; }
     catch (e) {
       log('warn', 'managed-spawn removeManagedSpec: kill ' + killPid + ' failed: ' + e.message);
     }
@@ -1293,7 +1350,7 @@ function removeManagedSpec(name, opts = {}) {
 
 function listManagedSpecs(opts) {
   opts = opts || {};
-  const parsed = require('./small-state-store').readManagedProcesses();
+  const parsed = require('../persistence/small-state-store').readManagedProcesses();
   const specs = (parsed && Array.isArray(parsed.specs)) ? parsed.specs : [];
   if (opts.project) return specs.filter(s => s && s.owner_project === opts.project);
   return specs.slice();
@@ -1547,7 +1604,7 @@ function tailManagedLog(name, lines) {
 // ─── Item 6 (P-1f9c3a45) ─────────────────────────────────────────────────────
 //
 // Playbook auto-inject of the live-managed-processes block. Called by
-// engine/playbook.js renderPlaybook (project-scoped, computed once per render).
+// engine/agents/playbook.js renderPlaybook (project-scoped, computed once per render).
 // Filters listManagedSpecs() to specs where:
 //   - owner_project === opts.project
 //   - healthy === true
@@ -1899,7 +1956,7 @@ function restartManagedSpec(name, opts = {}) {
 //                                          Kills + drops every spec whose
 //                                          owner_project matches, unlinks the
 //                                          log + log.1. Returns {killed,
-//                                          unlinked}. engine/projects.js
+//                                          unlinked}. engine/planning/projects.js
 //                                          removeProject calls this — no
 //                                          managed-process awareness elsewhere.
 //
@@ -2096,28 +2153,22 @@ function removeManagedSpecsForProject(projectName) {
   if (typeof projectName !== 'string' || projectName.length === 0) {
     return { killed: 0, unlinked: 0, scanned: 0 };
   }
-  let toKill = [];
-  let logPaths = [];
-  shared.mutateManagedProcesses((data) => {
-    if (!data || typeof data !== 'object' || !Array.isArray(data.specs)) {
-      return _initialStateShape();
-    }
-    const keep = [];
-    for (const rec of data.specs) {
-      if (rec && rec.owner_project === projectName) {
-        if (Number.isInteger(rec.pid) && rec.pid > 0) toKill.push(rec.pid);
-        if (rec.log_path) logPaths.push(rec.log_path);
-        continue; // drop
-      }
-      keep.push(rec);
-    }
-    data.specs = keep;
-    return data;
-  }, { defaultValue: _initialStateShape() });
+  const records = listManagedSpecs({ project: projectName });
   let killed = 0;
-  if (toKill.length > 0) {
-    try { killed = shared.killByPidTreesImmediate(toKill); }
-    catch (e) { log('warn', 'managed-spawn removeForProject: kill batch failed for ' + projectName + ': ' + e.message); }
+  let removed = 0;
+  const logPaths = [];
+  for (const rec of records) {
+    const result = removeManagedSpec(rec.name, {
+      expected: rec,
+      verifyIdentity: true,
+    });
+    if (!result.removed) {
+      log('warn', 'managed-spawn removeForProject: preserved ' + rec.name + ' — ' + result.reason);
+      continue;
+    }
+    removed++;
+    if (result.killed) killed++;
+    if (rec.log_path) logPaths.push(rec.log_path);
   }
   let unlinked = 0;
   for (const p of logPaths) {
@@ -2126,7 +2177,7 @@ function removeManagedSpecsForProject(projectName) {
       catch (e) { if (e && e.code !== 'ENOENT') log('warn', 'managed-spawn removeForProject: unlink ' + candidate + ' failed: ' + e.message); }
     }
   }
-  return { killed: killed, unlinked: unlinked, scanned: toKill.length };
+  return { killed, unlinked, scanned: records.length, removed };
 }
 
 module.exports = {