@yemi33/minions 0.1.2448 → 0.1.2449

package/engine/{distribution.js → operations/distribution.js}

@@ -1,6 +1,6 @@
-// engine/distribution.js — identity of the *installed* Minions distribution.
+// engine/operations/distribution.js — identity of the *installed* Minions distribution.
 //
-// Minions ships from one source tree as two npm packages (tools/prepare-package.js):
+// Minions ships from one source tree as two npm packages (scripts/prepare-package.js):
 //   • public   → `@yemi33/minions`               (npmjs, yemi33/minions)
 //   • internal → `@yemishin_microsoft/minions`   (GitHub Packages; overridable
 //                                                 at publish time via INTERNAL_PACKAGE_NAME)
@@ -34,9 +34,8 @@ const INTERNAL_WELCOME_MESSAGE = 'Welcome to the internal Minions!';
 const INSTALLATION_ID_KEY = 'installationId';
 const INTERNAL_WELCOME_ACK_KEY = 'internalWelcome';
 
-// The installed package root: engine/ lives one level under it in both the npm
-// tarball and the git checkout.
-const PACKAGE_ROOT = path.join(__dirname, '..');
+// The installed package root is two levels above this domain module.
+const PACKAGE_ROOT = path.join(__dirname, '..', '..');
 
 function _packageJsonPath(opts) {
   if (opts && opts.packageJsonPath) return opts.packageJsonPath;
@@ -88,7 +87,7 @@ function resolveDistribution(opts) {
 }
 
 function _smallState() {
-  return require('./small-state-store');
+  return require('../persistence/small-state-store');
 }
 
 function _newInstallationId() {

package/engine/{cleanup.js → orchestration/cleanup.js}

@@ -1,13 +1,13 @@
 /**
- * engine/cleanup.js — Periodic cleanup: temp files, worktrees, zombies, migrations.
+ * engine/orchestration/cleanup.js — Periodic cleanup: temp files, worktrees, zombies, migrations.
  * Extracted from engine.js for modularity. No logic changes.
  */
 
 const fs = require('fs');
 const path = require('path');
-const shared = require('./shared');
-const queries = require('./queries');
-const smallStateStore = require('./small-state-store');
+const shared = require('../core/shared');
+const queries = require('../core/queries');
+const smallStateStore = require('../persistence/small-state-store');
 
 const { exec, execAsync, execSilent, log, ts, ENGINE_DEFAULTS } = shared;
 const { safeJson, safeJsonArr, safeJsonNoRestore, safeWrite, safeReadDir, readWorkItems, readPullRequests, mutateCooldowns, mutateMetrics, mutateWorkItems, getProjects,
@@ -22,7 +22,7 @@ const PLANS_DIR = queries.PLANS_DIR;
 // Lazy require to break circular dependency with engine.js
 // Only needed for engine().activeProcesses — log/ts come from shared.js
 let _engine = null;
-function engine() { if (!_engine) _engine = require('../engine'); return _engine; }
+function engine() { if (!_engine) _engine = require('../../engine'); return _engine; }
 
 // Lazy require for dispatch module
 let _dispatch = null;
@@ -32,7 +32,7 @@ function dispatchModule() { if (!_dispatch) _dispatch = require('./dispatch'); r
 // protected; idle-entry TTL cleanup remains owned by worktree-pool.pruneStale.
 let _worktreePool = null;
 function worktreePool() {
-  if (!_worktreePool) _worktreePool = require('./worktree-pool');
+  if (!_worktreePool) _worktreePool = require('../worktrees/pool');
   return _worktreePool;
 }
 
@@ -179,7 +179,7 @@ function cleanupMergedPrLocalBranch(root, project, pr) {
  * Sweep leaked test-fixture meetings from a `meetings/` directory.
  *
  * Meeting unit/integration tests don't all honor MINIONS_TEST_DIR
- * (engine/meeting.js is in ISOLATED_MODULES, but tests that load it after the
+ * (engine/orchestration/meeting.js is in ISOLATED_MODULES, but tests that load it after the
  * env var is unset, or that fail before cleanup, leave `.json` + `.json.backup`
  * sidecars behind). The engine's tick loop then re-discovers these fixtures
  * every tick, fails playbook validation ("missing required template variables:
@@ -422,7 +422,7 @@ function pruneOrphanManagedLogs(opts = {}) {
   const now = Number.isFinite(Number(opts.now)) ? Number(opts.now) : Date.now();
   const specs = Array.isArray(opts.specs)
     ? opts.specs
-    : require('./managed-spawn').listManagedSpecs();
+    : require('../processes/managed-spawn').listManagedSpecs();
   const normalize = value => {
     const resolved = path.resolve(String(value || ''));
     return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
@@ -640,7 +640,7 @@ async function runCleanup(config, verbose = false) {
   cleaned.orphanWorktreeDirs = 0;
   cleaned.worktreeReconcileFailed = 0;
   try {
-    const reconcile = require('./worktree-gc').reconcileStaleWorktreeDirectories({
+    const reconcile = require('../worktrees/gc').reconcileStaleWorktreeDirectories({
       projects,
       dispatchSnap: getDispatch(),
       worktreeRootRel: config.engine?.worktreeRoot || ENGINE_DEFAULTS.worktreeRoot,
@@ -660,7 +660,7 @@ async function runCleanup(config, verbose = false) {
   const _reapedScratchRoots = new Set();     // reap each worktree root's .agent-temp once per cleanup
   let activeSharedBranchPlans = [];
   try {
-    activeSharedBranchPlans = require('./prd-store').listPrdRows()
+    activeSharedBranchPlans = require('../planning/prd-store').listPrdRows()
       .map(row => row.plan)
       .filter(plan => plan?.branch_strategy === 'shared-branch' && plan.feature_branch && plan.status !== 'completed');
   } catch { /* optional */ }
@@ -773,7 +773,7 @@ async function runCleanup(config, verbose = false) {
       // Sequential probing was the dominant cost in the cleanup phase
       // (5–15s tick stall every 10 ticks at 50+ worktrees), but unbounded
       // Promise.all would spawn 50+ concurrent git children — bad on Windows
-      // where each fork pays AV-scan overhead. Mirrors engine/ado.js:611.
+      // where each fork pays AV-scan overhead. Mirrors engine/ado/index.js:611.
       const BRANCH_PROBE_CONCURRENCY = 5;
       const branchMap = new Map();
       for (let i = 0; i < allDirs.length; i += BRANCH_PROBE_CONCURRENCY) {
@@ -789,7 +789,7 @@ async function runCleanup(config, verbose = false) {
       const _anchoredProcessCwds = [];
       let _anchorProbeFailed = false;
       try {
-        const _ms = require('./managed-spawn');
+        const _ms = require('../processes/managed-spawn');
         for (const rec of _ms.listManagedSpecs()) {
           if (rec && typeof rec.cwd === 'string' && rec.cwd.length > 0) {
             try { _anchoredProcessCwds.push(shared.realPathForComparison(rec.cwd)); }
@@ -801,7 +801,7 @@ async function runCleanup(config, verbose = false) {
         log('warn', `managed-spawn cwd anchor lookup failed: ${e.message}`);
       }
       try {
-        const _kp = require('./keep-process-sweep');
+        const _kp = require('../processes/keep-process-sweep');
         _anchoredProcessCwds.push(..._kp.getActiveKeepProcessCwds());
       } catch (e) {
         _anchorProbeFailed = true;
@@ -1022,6 +1022,10 @@ async function runCleanup(config, verbose = false) {
     }
   } catch (e) { log('warn', 'worktree-pool prune: ' + e.message); }
 
+  let processSnapshot = [];
+  try { processSnapshot = shared.listAllProcesses(); }
+  catch (e) { log('warn', 'cleanup process snapshot: ' + e.message); }
+
   // 4. Kill zombie agent processes not tracked by the engine
   // List all node processes, check if any are running spawn-agent.js for our minions
   try {
@@ -1043,11 +1047,12 @@ async function runCleanup(config, verbose = false) {
       let pid;
       try { pid = Number(fs.readFileSync(pidFilePath, 'utf8').trim()); } catch { return; }
       if (activePids.has(pid)) return;
-      if (Number.isInteger(pid) && pid > 0 && shared.isProcessCommandLineMatchingAgent(pid)) {
-        try {
-          shared.killImmediate({ pid });
-          cleaned.zombies++;
-        } catch { /* process may already be gone */ }
+      if (shared.terminateProcess('engine.cleanup.stale-agent-pid', { pid }, {
+        recordedAtMs: stat.mtimeMs,
+        processes: processSnapshot,
+        skewMs: 2000,
+      })) {
+        cleaned.zombies++;
       }
       if (layout === 'dispatch-dir') {
         try { shared.removeDispatchTmpDir(path.dirname(pidFilePath)); } catch {}
@@ -1056,24 +1061,22 @@ async function runCleanup(config, verbose = false) {
       }
       cleaned.stalePidFiles++;
     });
-    for (const [id, info] of activeProcesses.entries()) {
-      if (!activeIds.has(id)) {
-        shared.killImmediate(info.proc);
-        activeProcesses.delete(id);
-        cleaned.zombies++;
-      }
-    }
+    cleaned.zombies += require('./timeout').cancelTrackedProcessesWithoutDispatch(
+      activeProcesses,
+      dispatch.active,
+      { processes: processSnapshot },
+    );
   } catch (e) { log('warn', 'cleanup zombie processes: ' + e.message); }
 
-  // 4b. Sweep stray MCP descendants. Spawn-agent.js reaps its descendants on
+  // 4b. Detect stray MCP descendants. Spawn-agent.js reaps its descendants on
   // close, but a hard kill (engine restart, OS crash) can skip that path and
   // leave orphan node.exe processes running MCP servers (Azure, Playwright,
-  // Loop, etc.) reparented away from the Minions tree. This sweep walks
-  // descendants from every anchor we know (engine, dashboard, active spawn-
-  // agents) and kills any node MCP processes outside that set.
+  // Loop, etc.) reparented away from the Minions tree. We cannot prove that an
+  // unanchored global process belongs to this runtime, so report it without
+  // killing it; leaking is safer than terminating another checkout's process.
   cleaned.strayMcps = 0;
   try {
-    const allProcs = shared.listAllProcesses();
+    const allProcs = processSnapshot;
     if (allProcs.length) {
       const anchorPids = [process.pid];
       for (const info of activeProcesses.values()) {
@@ -1093,8 +1096,8 @@ async function runCleanup(config, verbose = false) {
       // any agents/<id>/keep-pids.json file are anchors, so the reachability
       // walk treats them (and their MCP grandchildren) as legitimate.
       try {
-        const keepProcessSweep = require('./keep-process-sweep');
-        for (const pid of keepProcessSweep.getActiveAnchorPids()) anchorPids.push(pid);
+        const keepProcessSweep = require('../processes/keep-process-sweep');
+        for (const pid of keepProcessSweep.getActiveAnchorPids({ processes: allProcs })) anchorPids.push(pid);
       } catch (e) { log('warn', `cleanup: keep-process anchor lookup failed: ${e.message}`); }
       const reach = shared.listProcessReachable(anchorPids, allProcs);
       // MCP server commandlines. Matches scoped (@modelcontextprotocol/*,
@@ -1112,8 +1115,7 @@ async function runCleanup(config, verbose = false) {
         strayPids.push(p.pid);
       }
       if (strayPids.length) {
-        cleaned.strayMcps = shared.killByPidsImmediate(strayPids);
-        log('info', `Cleanup: ${cleaned.strayMcps}/${strayPids.length} stray MCP descendants reaped`);
+        log('warn', `Cleanup: detected ${strayPids.length} unanchored MCP process(es); leaving them running because ownership is unproven`);
       }
     }
   } catch (e) { log('warn', 'cleanup stray MCPs: ' + e.message); }
@@ -1342,7 +1344,7 @@ async function runCleanup(config, verbose = false) {
   // changes clobbered by this pass's stale in-memory copy (lost-update race —
   // writePrd's _upsertPrd does a full-column data=? replace, not a merge).
   try {
-    const prdStore = require('./prd-store');
+    const prdStore = require('../planning/prd-store');
     const prdFiles = prdStore.listPrdRows().filter(row => !row.archived).map(row => row.filename);
     for (const pf of prdFiles) {
       // Cheap out-of-transaction peek to skip PRDs that clearly need no work;
@@ -1381,7 +1383,7 @@ async function runCleanup(config, verbose = false) {
       queries.getWorkItems(config, { enrich: false }).map(wi => wi?.id).filter(Boolean)
     );
 
-    const prdStore = require('./prd-store');
+    const prdStore = require('../planning/prd-store');
     const orphanPrdEntries = prdStore.listPrdRows().filter(row => !row.archived).map(row => row.filename);
     for (const pf of orphanPrdEntries) {
       const peek = prdStore.readPrd(pf);
@@ -1598,7 +1600,7 @@ async function runCleanup(config, verbose = false) {
   cleaned.expiredReviewCandidates = 0;
   cleaned.prunedLifecycleEvents = 0;
   try {
-    const memoryStore = require('./memory-store');
+    const memoryStore = require('../memory/memory-store');
     cleaned.expiredReviewCandidates = memoryStore.expireStaleReviewLearningCandidates();
     cleaned.prunedLifecycleEvents = memoryStore.pruneMemoryLifecycleEvents();
     if (cleaned.expiredReviewCandidates > 0 || cleaned.prunedLifecycleEvents > 0) {
@@ -1608,20 +1610,45 @@ async function runCleanup(config, verbose = false) {
 
   // 20. Recovery refs outlive the 24-hour quarantine-directory window so an
   // operator can still recover preserved commits/WIP after directory cleanup.
-  // Bound that independent recovery window at 10 days.
+  // W-ms87rbe601a66d13 — bound that window at the SAME retention the protected
+  // quarantine-DIRECTORY sweep uses (`engine.worktreeProtectedQuarantineRetentionMs`,
+  // default `shared.QUARANTINE_REF_RETENTION_MS`) rather than the built-in
+  // constant, so lowering the setting moves both sides together and `0` keeps
+  // refs indefinitely exactly like the directories.
   cleaned.quarantineRefs = 0;
   try {
-    const { pruneExpiredQuarantineRefs } = require('./quarantine-refs');
-    const result = await pruneExpiredQuarantineRefs(projects);
+    const { pruneExpiredQuarantineRefs } = require('../worktrees/quarantine-refs');
+    const retentionMs = shared.resolveQuarantineRetentionMs(config);
+    const retentionDays = retentionMs / (24 * 60 * 60 * 1000);
+    const result = await pruneExpiredQuarantineRefs(projects, { retentionMs });
     cleaned.quarantineRefs = result.removed;
-    if (result.removed > 0) {
-      log('info', `cleanup: pruned ${result.removed} quarantine recovery ref(s) older than 10 days`);
+    cleaned.quarantineRefsMalformed = result.malformed;
+    cleaned.quarantineRefFailures = result.failed;
+    if (result.removed > 0 || result.failed > 0) {
+      log('info', `cleanup: pruned ${result.removed}/${result.scanned} quarantine recovery ref(s) older than ${retentionDays} days (retained ${result.retained}, failed ${result.failed})`);
+    }
+    if (result.malformed > 0) {
+      const sample = result.malformedRefs.slice(0, 5).map(entry => entry.ref).join(', ');
+      log('warn', `quarantine-ref retention: preserved ${result.malformed} ref(s) with an unparseable timestamp: ${sample}`);
     }
     for (const failure of result.errors) {
-      log('warn', `quarantine-ref retention (${failure.project || 'unknown project'}): ${failure.error}`);
+      log('warn', `quarantine-ref retention (${failure.project || 'unknown project'}${failure.ref ? ` ${failure.ref}` : ''}): ${failure.error}`);
     }
   } catch (e) { log('warn', `quarantine-ref retention: ${e.message}`); }
 
+  // 21. Superseded failed-scheduled work-item retention (W-msckn1lp002xdf6b).
+  // Machine-generated scheduled-run failures (hourly review/fetch sweeps, etc.)
+  // otherwise accumulate indefinitely. This daily sweep keeps the newest failure
+  // per schedule for diagnosis and prunes older superseded failures past the 24h
+  // window; human-authored / non-scheduled failures are never touched. Its own
+  // cadence gate makes it a near no-op on most cleanup ticks.
+  cleaned.failedScheduledPruned = 0;
+  try {
+    const { pruneSupersededFailedScheduledItems } = require('./failed-scheduled-cleanup');
+    const result = pruneSupersededFailedScheduledItems(config);
+    cleaned.failedScheduledPruned = (result && result.pruned) || 0;
+  } catch (e) { log('warn', `failed-scheduled retention: ${e.message}`); }
+
   return cleaned;
 }
 
@@ -1644,7 +1671,7 @@ function scrubStaleMetrics() {
 
 /**
  * Periodic per-tick worktree sweep. Aggregates the two pruners in
- * `engine/worktree-gc.js` so a long-lived engine catches orphans the
+ * `engine/worktrees/gc.js` so a long-lived engine catches orphans the
  * boot-only reconcile would miss:
  *
  *   - `pruneOrphanWorktrees`: walks `<localPath>/<worktreeRoot>` and reaps
@@ -1664,7 +1691,7 @@ function scrubStaleMetrics() {
  * resolves with the same object after its final counters are refreshed.
  */
 function runPeriodicWorktreeSweep(config) {
-  const worktreeGc = require('./worktree-gc');
+  const worktreeGc = require('../worktrees/gc');
   const allProjects = getProjects(config);
   // PL-live-checkout-reliability-hardening — EXCLUDE live-checkout projects from
   // registry-derived destructive pruners. Filesystem reconciliation below still

package/engine/{cooldown.js → orchestration/cooldown.js}

@@ -1,11 +1,11 @@
 /**
- * engine/cooldown.js — Dispatch cooldowns, deduplication, and context coalescing.
+ * engine/orchestration/cooldown.js — Dispatch cooldowns, deduplication, and context coalescing.
  * Extracted from engine.js.
  */
 
-const shared = require('./shared');
-const queries = require('./queries');
-const smallStateStore = require('./small-state-store');
+const shared = require('../core/shared');
+const queries = require('../core/queries');
+const smallStateStore = require('../persistence/small-state-store');
 
 const { mutateCooldowns, log, ENGINE_DEFAULTS } = shared;
 
@@ -274,7 +274,7 @@ function isAlreadyDispatched(key) {
  */
 function isBranchActive(branch) {
   if (!branch) return null;
-  const { sanitizeBranch } = require('./shared');
+  const { sanitizeBranch } = require('../core/shared');
   const normalized = sanitizeBranch(branch);
   const dispatch = queries.getDispatch();
   return (dispatch.active || []).find(d => {

package/engine/{dispatch-events.js → orchestration/dispatch-events.js}

@@ -1,5 +1,5 @@
 /**
- * engine/dispatch-events.js — Single source of truth for dispatch terminal events.
+ * engine/orchestration/dispatch-events.js — Single source of truth for dispatch terminal events.
  *
  * W-mpob4nyk0006580e: The live view banner ("✓ Task complete" / "✗ Task ended
  * with …") must mirror `dispatch.result` exactly. Previously the banner was
@@ -29,7 +29,7 @@
 const fs = require('fs');
 const path = require('path');
 const { EventEmitter } = require('events');
-const shared = require('./shared');
+const shared = require('../core/shared');
 
 const MAX_RING_ENTRIES = 50;          // bound file size + memory; dev tool
 const REPLAY_TTL_MS = 5 * 60 * 1000;  // 5 min — long enough for tab refresh