@yemi33/minions 0.1.1953 → 0.1.1954

package/engine/cli.js

@@ -772,6 +772,22 @@ const commands = {
       }
     })();
 
+    // W-mp7gox8w000n8936 — Boot reconcile for kb-sweep state: clear stale
+    // `in-flight`/`starting` records left over from a crashed runner (or a
+    // legacy pre-pid runner). Without this, the record sits there clogging
+    // /api/knowledge/sweep/status until someone POSTs a new sweep. Idempotent.
+    (function startupReconcileKbSweep() {
+      try {
+        const { reconcileSweepStateOnBoot } = require('./kb-sweep');
+        const stats = reconcileSweepStateOnBoot();
+        if (stats.released > 0) {
+          console.log(`  KB-sweep boot reconcile: released stale ${stats.prevStatus} record (pid=${stats.prevPid}, reason=${stats.reason})`);
+        }
+      } catch (err) {
+        e.log('warn', `KB-sweep boot reconcile failed: ${err.message}`);
+      }
+    })();
+
     // Initial tick
     e.tick();
 

package/engine/kb-sweep.js

@@ -339,6 +339,91 @@ function readSweepLiveness(opts = {}) {
   };
 }
 
+/**
+ * One-shot boot-time reconciliation for `engine/kb-sweep-state.json`.
+ *
+ * Mirrors the worktree-pool / keep-process boot reconcilers in `engine/cli.js`:
+ * after an engine restart we may inherit a stale `in-flight`/`starting` record
+ * whose runner has long since died (or — for legacy state files — never
+ * recorded a pid). Without proactive cleanup the record sits there clogging
+ * `/api/knowledge/sweep/status` until someone POSTs a new sweep (which the
+ * dashboard's stale-guard would then auto-release).
+ *
+ * Behavior:
+ *   - Absent state file → no-op.
+ *   - Terminal status (completed/failed) → no-op.
+ *   - `starting` within 15s boot-grace → no-op (matches readSweepLiveness).
+ *   - `in-flight` / stale `starting` with a live pid → no-op (running sweep).
+ *   - Otherwise rewrite to `status: 'failed'` preserving the original pid for
+ *     forensics. The original record fields are kept; `reconciliationReason`
+ *     records why we released it.
+ *
+ * CAS guard: re-reads state immediately before the write and aborts if any of
+ * status/startedAt/pid/sweepToken changed since the snapshot — protects against
+ * a concurrent dashboard POST or runner that wrote a fresh record between our
+ * decision and our write.
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.now=Date.now()]                injectable clock (tests)
+ * @param {(pid:number)=>boolean} [opts.isPidAlive]    injectable (tests)
+ * @returns {{ scanned:number, released:number, reason?:string,
+ *             prevStatus?:string, prevPid?:number }}
+ */
+function reconcileSweepStateOnBoot(opts = {}) {
+  const now = Number(opts.now) || Date.now();
+  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 { scanned: 0, released: 0 };
+  if (state.status !== 'in-flight' && state.status !== 'starting') {
+    return { scanned: 1, released: 0, reason: `terminal-status-${state.status}` };
+  }
+  if (state.status === 'starting') {
+    const STARTING_GRACE_MS = 15000;
+    const age = state.startedAt ? now - Number(state.startedAt) : Infinity;
+    if (age <= STARTING_GRACE_MS) {
+      return { scanned: 1, released: 0, reason: 'within-boot-grace' };
+    }
+  }
+  const pid = Number(state.pid) || 0;
+  const alive = pid > 0 ? !!isPidAlive(pid) : false;
+  if (alive) {
+    return { scanned: 1, released: 0, reason: 'pid-still-alive', prevPid: pid };
+  }
+
+  const reason = pid > 0 ? 'pid-dead-on-startup-check' : 'no-pid-recorded-on-startup-check';
+
+  // CAS guard: re-read right before the write so we don't clobber a fresh
+  // `starting`/`in-flight` record that a concurrent dashboard POST or runner
+  // wrote between our decision and our write.
+  const current = safeJson(KB_SWEEP_STATE_PATH);
+  if (!current
+      || current.status !== state.status
+      || Number(current.startedAt || 0) !== Number(state.startedAt || 0)
+      || Number(current.pid || 0) !== pid
+      || (current.sweepToken || null) !== (state.sweepToken || null)) {
+    return { scanned: 1, released: 0, reason: 'state-changed-before-reconcile' };
+  }
+
+  const failedState = {
+    ...state,
+    status: 'failed',
+    completedAt: now,
+    completedAtIso: new Date(now).toISOString(),
+    error: `sweep abandoned: ${reason}`,
+    reconciliationReason: reason,
+  };
+  // Direct safeWrite (NOT _writeSweepState) so the original pid is preserved
+  // for forensics — _writeSweepState would overwrite it with this process's
+  // pid, destroying the diagnostic value of the record.
+  try { safeWrite(KB_SWEEP_STATE_PATH, JSON.stringify(failedState)); } catch { /* ignore */ }
+  return {
+    scanned: 1, released: 1, reason,
+    prevStatus: state.status, prevPid: pid,
+  };
+}
+
 /**
  * Run the full sweep. Returns a rich summary.
  *
@@ -480,6 +565,7 @@ module.exports = {
   runKbSweep,
   staleGuardMs,
   readSweepLiveness,
+  reconcileSweepStateOnBoot,
   KB_SWEEP_STATE_PATH,
   KB_SWEEP_LOG_PATH,
   KB_SWEEP_RUNNER_PATH,

package/package.json

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