@yemi33/minions 0.1.1930 → 0.1.1931

package/dashboard.js

@@ -4631,14 +4631,17 @@ const server = http.createServer(async (req, res) => {
     if (swept) result.lastSwept = swept.timestamp;
     // Surface in-flight sweep state so the UI can render a 'now sweeping (Xm)'
     // badge alongside the previous-completion 'swept N days ago' indicator.
-    // Memory wins when present, disk fallback survives dashboard restarts.
-    const sweepState = safeJson(path.join(ENGINE_DIR, 'kb-sweep-state.json'));
-    const memInFlight = !!global._kbSweepInFlight;
-    const diskInFlight = !!(sweepState && sweepState.status === 'in-flight');
-    if (memInFlight || diskInFlight) {
-      result.sweepInFlight = true;
-      result.sweepStartedAt = global._kbSweepStartedAt || (sweepState && sweepState.startedAt) || null;
-    }
+    // Source of truth: kb-sweep-state.json + PID liveness — the in-process
+    // sweep moved to a detached runner so in-memory globals are no longer
+    // authoritative (they die with the dashboard).
+    try {
+      const { readSweepLiveness } = require('./engine/kb-sweep');
+      const liveness = readSweepLiveness({ entryCount: entries.length });
+      if (liveness.inFlight && liveness.alive) {
+        result.sweepInFlight = true;
+        result.sweepStartedAt = liveness.startedAt || null;
+      }
+    } catch { /* best-effort UI indicator */ }
     return jsonReply(res, 200, result);
   }
 
@@ -4657,73 +4660,135 @@ const server = http.createServer(async (req, res) => {
   }
 
   async function handleKnowledgeSweep(req, res) {
-    // Auto-release stale guard — dynamic floor based on KB size (30 min min, +1s per entry)
-    const { staleGuardMs } = require('./engine/kb-sweep');
+    // Source of truth = kb-sweep-state.json + PID liveness. The sweep now runs
+    // as a detached child (engine/kb-sweep-runner.js) so it survives
+    // `minions restart`; the in-memory `global._kbSweep*` flags from the old
+    // in-process implementation are gone.
+    const {
+      readSweepLiveness, staleGuardMs, KB_SWEEP_STATE_PATH, KB_SWEEP_LOG_PATH, KB_SWEEP_RUNNER_PATH,
+    } = require('./engine/kb-sweep');
     const entryCount = (queries.getKnowledgeBaseEntries() || []).length;
     const guardMs = staleGuardMs(entryCount);
-    if (global._kbSweepInFlight && global._kbSweepStartedAt && Date.now() - global._kbSweepStartedAt > guardMs) {
-      console.log(`[kb-sweep] Auto-releasing stale guard (>${Math.round(guardMs / 60000)}min for ${entryCount} entries)`);
-      global._kbSweepInFlight = false;
-    }
-    // Disk-state fallback: if a previous dashboard process died mid-sweep, the
-    // state file says 'in-flight' forever. Treat it as stale past the guard so
-    // a new sweep can start.
-    const sweepStateFile = path.join(ENGINE_DIR, 'kb-sweep-state.json');
-    const diskState = safeJson(sweepStateFile);
-    const diskInFlight = !!(diskState && diskState.status === 'in-flight');
-    const diskStartedAt = diskState && diskState.startedAt ? Number(diskState.startedAt) : 0;
-    const diskStale = diskInFlight && diskStartedAt && Date.now() - diskStartedAt > guardMs;
-    if (diskStale) {
-      console.log(`[kb-sweep] Auto-releasing stale disk-state guard (>${Math.round(guardMs / 60000)}min)`);
-      try { shared.safeUnlink(sweepStateFile); } catch { /* ignore */ }
-    }
-    if (global._kbSweepInFlight || (diskInFlight && !diskStale)) {
+
+    // Synchronous pre-claim BEFORE awaiting the body so a concurrent POST
+    // arriving in the same tick sees in-flight state and can't double-spawn.
+    const sweepToken = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const liveness = readSweepLiveness({ entryCount });
+    if (liveness.inFlight && liveness.stale) {
+      const reason = !liveness.alive
+        ? `runner pid=${liveness.pid} is no longer alive`
+        : `>${Math.round(guardMs / 60000)}min for ${entryCount} entries`;
+      console.log(`[kb-sweep] Auto-releasing stale guard (${reason})`);
+      try { shared.safeUnlink(KB_SWEEP_STATE_PATH); } catch { /* ignore */ }
+    } else if (liveness.inFlight) {
       return jsonReply(res, 200, {
         ok: true, alreadyRunning: true,
-        startedAt: global._kbSweepStartedAt || diskStartedAt || null,
+        startedAt: liveness.startedAt || null,
       });
     }
-    const sweepToken = Date.now() + Math.random();
-    global._kbSweepToken = sweepToken;
-    global._kbSweepInFlight = true;
-    global._kbSweepStartedAt = Date.now();
+
+    // Claim the slot synchronously by writing a "starting" state. The runner
+    // will overwrite this with status:'in-flight' + its real pid once it boots.
+    // readSweepLiveness grants a 15s boot-grace to "starting" records with no pid.
+    const startedAt = Date.now();
+    try {
+      safeWrite(KB_SWEEP_STATE_PATH, JSON.stringify({
+        status: 'starting', startedAt, startedAtIso: new Date().toISOString(),
+        sweepToken, pid: null,
+      }));
+    } catch (e) {
+      console.error(`[kb-sweep] failed to write starting state: ${e.message}`);
+    }
+
     const body = await readBody(req).catch(() => ({}));
-    _runKbSweepBackground(body, sweepToken);
-    return jsonReply(res, 202, { ok: true, started: true });
-  }
 
-  async function _runKbSweepBackground(body, sweepToken) {
+    // Persist body to a temp file so spawn doesn't have to serialize large
+    // pinnedKeys arrays via argv. Skip when body is empty.
+    let bodyFile = null;
+    if (body && (Array.isArray(body.pinnedKeys) || body.dryRun != null)) {
+      bodyFile = path.join(ENGINE_DIR, `tmp-kb-sweep-body-${sweepToken}.json`);
+      try { safeWrite(bodyFile, JSON.stringify(body)); }
+      catch (e) {
+        console.error(`[kb-sweep] failed to write body-file ${bodyFile}: ${e.message}`);
+        bodyFile = null;
+      }
+    }
+
+    const { spawn: cpSpawn } = require('child_process');
+    // Open log fd in append mode so spawn can pipe stdio there. Child inherits
+    // the fd; parent closes its copy after spawn returns successfully.
+    let logFdNum = null;
+    let stdio = ['ignore', 'ignore', 'ignore'];
     try {
-      const { runKbSweep } = require('./engine/kb-sweep');
-      const result = await runKbSweep({ pinnedKeys: body.pinnedKeys, engineConfig: CONFIG.engine });
-      global._kbSweepLastResult = result;
-      global._kbSweepLastCompletedAt = Date.now();
+      logFdNum = fs.openSync(KB_SWEEP_LOG_PATH, 'a');
+      stdio = ['ignore', logFdNum, logFdNum];
+    } catch (e) {
+      console.error(`[kb-sweep] failed to open log ${KB_SWEEP_LOG_PATH}: ${e.message}`);
+    }
+
+    const spawnArgs = ['--sweep-token', sweepToken];
+    if (bodyFile) spawnArgs.push('--body-file', bodyFile);
+
+    let proc;
+    try {
+      proc = cpSpawn(process.execPath, [KB_SWEEP_RUNNER_PATH, ...spawnArgs], {
+        cwd: MINIONS_DIR, stdio, detached: true, windowsHide: true,
+        env: { ...process.env },
+      });
     } catch (e) {
-      console.error('[kb-sweep] background error:', e.message);
-      global._kbSweepLastResult = { ok: false, error: e.message };
-      global._kbSweepLastCompletedAt = Date.now();
-    } finally { if (global._kbSweepToken === sweepToken) global._kbSweepInFlight = false; }
+      if (logFdNum != null) try { fs.closeSync(logFdNum); } catch { /* ignore */ }
+      if (bodyFile) try { fs.unlinkSync(bodyFile); } catch { /* ignore */ }
+      // Release the "starting" claim on synchronous spawn failure so the user
+      // can retry immediately.
+      try { shared.safeUnlink(KB_SWEEP_STATE_PATH); } catch { /* ignore */ }
+      return jsonReply(res, 500, { error: `spawn failed: ${e.message}` });
+    }
+    if (logFdNum != null) try { fs.closeSync(logFdNum); } catch { /* ignore */ }
+
+    // Conditional CAS: only update the state file from "starting" → "in-flight"
+    // if our sweepToken still owns it. If the (fast) runner already wrote
+    // "completed"/"failed" or its own "in-flight", leave that newer state alone.
+    try {
+      const current = safeJson(KB_SWEEP_STATE_PATH);
+      if (current && current.status === 'starting' && current.sweepToken === sweepToken) {
+        safeWrite(KB_SWEEP_STATE_PATH, JSON.stringify({
+          status: 'in-flight', startedAt, startedAtIso: new Date().toISOString(),
+          sweepToken, pid: proc.pid,
+        }));
+      }
+    } catch { /* best-effort */ }
+
+    proc.unref();
+    return jsonReply(res, 202, { ok: true, started: true, sweepToken });
   }
 
 
   function handleKnowledgeSweepStatus(req, res) {
-    // Disk-state fallback: when the dashboard restarts mid-sweep the in-memory
-    // globals get reset, but engine/kb-sweep-state.json survives. Memory still
-    // wins when present (faster, no disk read on every poll).
+    // Source of truth = kb-sweep-state.json + PID liveness. Globals are gone —
+    // the runner is detached, so its lifecycle is independent of this process.
+    const { readSweepLiveness } = require('./engine/kb-sweep');
+    const entries = queries.getKnowledgeBaseEntries() || [];
+    const liveness = readSweepLiveness({ entryCount: entries.length });
     const diskState = safeJson(path.join(ENGINE_DIR, 'kb-sweep-state.json'));
-    const memInFlight = !!global._kbSweepInFlight;
-    const diskInFlight = !!(diskState && diskState.status === 'in-flight');
-    const inFlight = memInFlight || diskInFlight;
-    const startedAt = global._kbSweepStartedAt || (diskState && diskState.startedAt) || null;
-    let lastResult = global._kbSweepLastResult || null;
-    let lastCompletedAt = global._kbSweepLastCompletedAt || null;
-    if (!lastResult && diskState && (diskState.status === 'completed' || diskState.status === 'failed')) {
-      if (diskState.status === 'failed') {
-        lastResult = { ok: false, error: diskState.error || 'sweep failed' };
-      } else {
-        lastResult = diskState.lastResult || { ok: true, summary: diskState.summary };
-      }
-      if (!lastCompletedAt && diskState.completedAt) lastCompletedAt = diskState.completedAt;
+    let inFlight = false;
+    let startedAt = null;
+    let lastResult = null;
+    let lastCompletedAt = null;
+    if (liveness.inFlight && liveness.alive) {
+      inFlight = true;
+      startedAt = liveness.startedAt || null;
+    } else if (liveness.inFlight && !liveness.alive) {
+      // Runner crashed pre-completion (or "starting" claim expired without a
+      // runner ever booting). Surface a synthetic error so the UI doesn't
+      // silently lose the previous attempt.
+      lastResult = { ok: false, error: 'sweep process exited before reporting completion' };
+      lastCompletedAt = liveness.startedAt || null;
+    } else if (diskState && diskState.status === 'completed') {
+      lastResult = diskState.lastResult || { ok: true, summary: diskState.summary };
+      lastCompletedAt = diskState.completedAt || null;
+    } else if (diskState && diskState.status === 'failed') {
+      lastResult = { ok: false, error: diskState.error || 'sweep failed' };
+      lastCompletedAt = diskState.completedAt || null;
     }
     return jsonReply(res, 200, { inFlight, startedAt, lastResult, lastCompletedAt });
   }

package/engine/copilot-models.json

@@ -1,5 +1,5 @@
 {
   "runtime": "copilot",
   "models": null,
-  "cachedAt": "2026-05-14T02:53:42.873Z"
+  "cachedAt": "2026-05-14T03:32:45.485Z"
 }

package/engine/kb-sweep-runner.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+/**
+ * engine/kb-sweep-runner.js — Detached entrypoint for the KB sweep.
+ *
+ * Spawned by dashboard.js `handleKnowledgeSweep` with `{ detached: true,
+ * stdio: ['ignore', logFd, logFd] }` so the sweep survives dashboard /
+ * engine restarts. The sweep regularly runs 1h+ and was previously killed
+ * mid-stream every `minions restart`.
+ *
+ * Args:
+ *   --sweep-token <token>   Opaque token from the dashboard (string/number).
+ *   --body-file <path>      Optional path to a JSON file with request body
+ *                           fields (pinnedKeys, dryRun). Deleted on exit.
+ *   --dry-run               Equivalent to `body.dryRun = true`.
+ *
+ * State protocol: runKbSweep itself writes `engine/kb-sweep-state.json`
+ * (in-flight → completed/failed) and includes `pid: process.pid` (this
+ * runner's pid) so the dashboard can liveness-check via `process.kill(pid, 0)`.
+ * Exits 0 on success, 1 on error. stdout/stderr land in engine/kb-sweep.log.
+ */
+
+const fs = require('fs');
+
+function getArg(argv, name) {
+  const idx = argv.indexOf(name);
+  if (idx >= 0 && idx + 1 < argv.length) return argv[idx + 1];
+  return null;
+}
+function hasFlag(argv, name) {
+  return argv.indexOf(name) >= 0;
+}
+
+const argv = process.argv.slice(2);
+const sweepToken = getArg(argv, '--sweep-token') || String(Date.now());
+const bodyFile = getArg(argv, '--body-file');
+const cliDryRun = hasFlag(argv, '--dry-run');
+
+let body = {};
+if (bodyFile) {
+  try {
+    const raw = fs.readFileSync(bodyFile, 'utf8');
+    body = JSON.parse(raw || '{}');
+  } catch (e) {
+    console.error(`[kb-sweep-runner] failed to read body-file ${bodyFile}: ${e.message}`);
+  }
+}
+const dryRun = cliDryRun || body.dryRun === true;
+
+// Lazy-require AFTER args are parsed so a malformed body-file doesn't drag in
+// the whole sweep stack before we've reported the failure.
+const queries = require('./queries');
+const { runKbSweep } = require('./kb-sweep');
+
+function cleanupBodyFile() {
+  if (!bodyFile) return;
+  try { fs.unlinkSync(bodyFile); } catch { /* ignore */ }
+}
+
+(async () => {
+  const startedIso = new Date().toISOString();
+  console.log(`[kb-sweep-runner] ${startedIso} starting pid=${process.pid} token=${sweepToken} dryRun=${dryRun}`);
+  try {
+    const engineConfig = (queries.getConfig() || {}).engine || {};
+    const result = await runKbSweep({
+      pinnedKeys: body.pinnedKeys,
+      engineConfig,
+      sweepToken,
+      dryRun,
+    });
+    const summary = result && result.summary ? result.summary : 'ok';
+    console.log(`[kb-sweep-runner] ${new Date().toISOString()} done: ${summary}`);
+    cleanupBodyFile();
+    process.exit(0);
+  } catch (e) {
+    const msg = e && e.message ? e.message : String(e);
+    console.error(`[kb-sweep-runner] ${new Date().toISOString()} error: ${msg}`);
+    if (e && e.stack) console.error(e.stack);
+    cleanupBodyFile();
+    process.exit(1);
+  }
+})();

package/engine/kb-sweep.js

@@ -14,12 +14,14 @@ const path = require('path');
 const crypto = require('crypto');
 const shared = require('./shared');
 const queries = require('./queries');
-const { safeRead, safeWrite, safeUnlink, log, ts } = shared;
+const { safeRead, safeWrite, safeJson, safeUnlink, log, ts } = shared;
 const { MINIONS_DIR, ENGINE_DIR } = queries;
 
 const KB_DIR = path.join(MINIONS_DIR, 'knowledge');
 const SWEPT_DIR = path.join(KB_DIR, '_swept');
 const KB_SWEEP_STATE_PATH = path.join(ENGINE_DIR, 'kb-sweep-state.json');
+const KB_SWEEP_LOG_PATH = path.join(ENGINE_DIR, 'kb-sweep.log');
+const KB_SWEEP_RUNNER_PATH = path.join(__dirname, 'kb-sweep-runner.js');
 const SWEPT_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
 const COMPRESS_THRESHOLD_BYTES = 5000;
 const LLM_BATCH_SIZE = 30;
@@ -279,7 +281,62 @@ function _applyLlmPlan(plan, manifest, opts = {}) {
 }
 
 function _writeSweepState(state) {
-  try { safeWrite(KB_SWEEP_STATE_PATH, JSON.stringify(state)); } catch { /* ignore */ }
+  // Always include the current process pid + the caller-supplied sweepToken so
+  // the dashboard's liveness check (process.kill(pid, 0)) and the stale-guard
+  // can distinguish "still running" from "runner crashed". When this module is
+  // imported by the detached runner, process.pid is the runner's pid — which
+  // is exactly what we want.
+  const augmented = { pid: process.pid, ...state };
+  try { safeWrite(KB_SWEEP_STATE_PATH, JSON.stringify(augmented)); } catch { /* ignore */ }
+}
+
+/**
+ * Read kb-sweep-state.json and classify whether a sweep is alive + stale.
+ *
+ * Used by the dashboard's start endpoint, status endpoint, and stale-guard so
+ * they share a single source of truth (disk state + PID liveness) instead of
+ * relying on in-memory globals that die with the dashboard process.
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.entryCount=0] - KB entry count for staleGuardMs()
+ * @param {number} [opts.now=Date.now()] - injectable clock for tests
+ * @param {(pid:number)=>boolean} [opts.isPidAlive] - injectable for tests
+ * @returns {{ inFlight: boolean, alive?: boolean, stale?: boolean, pid?: number,
+ *            startedAt?: number, sweepToken?: string|number|null, guardMs?: number,
+ *            status?: string }}
+ */
+function readSweepLiveness(opts = {}) {
+  const now = Number(opts.now) || Date.now();
+  const entryCount = Number(opts.entryCount) || 0;
+  const isPidAlive = typeof opts.isPidAlive === 'function'
+    ? opts.isPidAlive
+    : (pid) => { try { process.kill(pid, 0); return true; } catch { return false; } };
+  const state = safeJson(KB_SWEEP_STATE_PATH);
+  if (!state) return { inFlight: false };
+  // "starting" is written by the dashboard pre-spawn (no PID yet) to close the
+  // race window between two concurrent POSTs. "in-flight" is written by the
+  // runner once it boots and has its own pid.
+  if (state.status !== 'starting' && state.status !== 'in-flight') {
+    return { inFlight: false, status: state.status };
+  }
+  const pid = Number(state.pid) || 0;
+  const startedAt = Number(state.startedAt) || 0;
+  const guardMs = staleGuardMs(entryCount);
+  const age = startedAt ? now - startedAt : 0;
+  let alive;
+  if (state.status === 'starting') {
+    // No PID yet — grant a short boot-grace so spawn can complete and the
+    // runner can overwrite with status:'in-flight' + its pid.
+    const STARTING_GRACE_MS = 15000;
+    alive = age <= STARTING_GRACE_MS;
+  } else {
+    alive = pid > 0 ? !!isPidAlive(pid) : false;
+  }
+  const stale = !alive || (startedAt > 0 && age > guardMs);
+  return {
+    inFlight: true, alive, stale, pid, startedAt, guardMs,
+    sweepToken: state.sweepToken || null, status: state.status,
+  };
 }
 
 /**
@@ -298,23 +355,26 @@ function _writeSweepState(state) {
 async function runKbSweep(opts = {}) {
   const dryRun = !!opts.dryRun;
   const startedAt = Date.now();
-  if (!dryRun) _writeSweepState({ status: 'in-flight', startedAt, startedAtIso: ts() });
+  const sweepToken = opts.sweepToken != null ? opts.sweepToken : null;
+  // Always write state — even for dryRun — so a runner spawned with dryRun
+  // still reports terminal status and the dashboard pre-write doesn't leak
+  // a stale "in-flight"/"starting" record. The inner _runKbSweepImpl still
+  // honors dryRun for actual file mutations.
+  _writeSweepState({ status: 'in-flight', startedAt, startedAtIso: ts(), sweepToken, dryRun });
   try {
     const result = await _runKbSweepImpl(opts);
-    if (!dryRun) {
-      _writeSweepState({
-        status: 'completed', startedAt, completedAt: Date.now(), completedAtIso: ts(),
-        durationMs: result.durationMs, summary: result.summary, lastResult: result,
-      });
-    }
+    _writeSweepState({
+      status: 'completed', startedAt, completedAt: Date.now(), completedAtIso: ts(),
+      durationMs: result.durationMs, summary: result.summary, lastResult: result,
+      sweepToken, dryRun,
+    });
     return result;
   } catch (e) {
-    if (!dryRun) {
-      _writeSweepState({
-        status: 'failed', startedAt, completedAt: Date.now(), completedAtIso: ts(),
-        error: e && e.message ? e.message : String(e),
-      });
-    }
+    _writeSweepState({
+      status: 'failed', startedAt, completedAt: Date.now(), completedAtIso: ts(),
+      error: e && e.message ? e.message : String(e),
+      sweepToken, dryRun,
+    });
     throw e;
   }
 }
@@ -419,7 +479,10 @@ function staleGuardMs(entryCount) {
 module.exports = {
   runKbSweep,
   staleGuardMs,
+  readSweepLiveness,
   KB_SWEEP_STATE_PATH,
+  KB_SWEEP_LOG_PATH,
+  KB_SWEEP_RUNNER_PATH,
   // Exported for tests
   _hashEntry,
   _parseFrontmatter,

package/package.json

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