ruvnet-brain 3.4.9-dev → 3.4.16-dev

package/README.md

@@ -4,7 +4,7 @@
 
 # 🧠 RuvNet Brain
 
-### 🧠 RuvNet Brain — [![RuvNet Brain version 3.4.9-dev — updated 2026-07-18 02:41 EDT](https://img.shields.io/badge/version_3.4.9--dev-updated_2026--07--18_02:41_EDT-1E90FF?style=for-the-badge&labelColor=0757BA)](https://github.com/stuinfla/ruvnet-brain/blob/main/plugin/.claude-plugin/plugin.json)
+### 🧠 RuvNet Brain — [![RuvNet Brain version 3.4.16-dev — updated 2026-07-18 11:07 EDT](https://img.shields.io/badge/version_3.4.16--dev-updated_2026--07--18_11:07_EDT-1E90FF?style=for-the-badge&labelColor=0757BA)](https://github.com/stuinfla/ruvnet-brain/blob/main/plugin/.claude-plugin/plugin.json)
 
 **A portable, source-grounded brain over Reuven Cohen's (rUv's) RuvNet stack — delivered as a Claude Code plugin that makes Claude _use_ the stack instead of fighting it.**
 
@@ -271,7 +271,7 @@ Plus: the **“take the wheel” behavioral pipeline** (below), a **4-level beha
 
 ## How it works
 
-The expensive work happens **once, at build time**: every covered repo is deep-walked (whole files, full function bodies, plus a symbol index), embedded into **two** vector variants (MiniLM-384 for edge/portability, bge-768 for depth) stored on-disk in **RVF / HNSW**, and distilled into a concepts + capability layer of per-repo primers and cards. That's **132,135 source chunks**. At **query time**, `search_ruvnet` searches every repo's store at once, pools the hits, and runs them through **one cross-encoder rerank** on a common scale — so the truly relevant file wins regardless of which repo it lives in — then returns whole source files, each labeled by repo and path.
+The expensive work happens **once, at build time**: every covered repo is deep-walked (whole files, full function bodies, plus a symbol index), embedded into **two** vector variants (MiniLM-384 for edge/portability, bge-768 for depth) stored on-disk in **RVF / HNSW**, and distilled into a concepts + capability layer of per-repo primers and cards. That's **132,216 source chunks**. At **query time**, `search_ruvnet` searches every repo's store at once, pools the hits, and runs them through **one cross-encoder rerank** on a common scale — so the truly relevant file wins regardless of which repo it lives in — then returns whole source files, each labeled by repo and path.
 
 ![RuvNet Brain architecture pipeline](assets/diagrams/architecture-pipeline.svg)
 
@@ -381,7 +381,7 @@ node forge-ask-all.mjs --dir . --q "How does RuVector implement HNSW vector sear
 
 This project versions in the open (see the live badge up top for the exact plugin version; the downloadable knowledge bundle is a separate track) — we don't claim “done,” “complete,” or “zero hallucinations.” Where it stands:
 
-- ✅ **The grounding brain is real and proven** — 57 repos, 132,135 chunks, dual embeddings, cross-encoder rerank, plugin (MCP tool + enforcement hook + skill), all re-runnable.
+- ✅ **The grounding brain is real and proven** — 57 repos, 132,216 chunks, dual embeddings, cross-encoder rerank, plugin (MCP tool + enforcement hook + skill), all re-runnable.
 - ✅ **Code-level depth** — the code-rich repos are indexed to full function bodies; “how is it implemented?” returns the implementation. Verified in the shipped bundle (clean-room 3/3).
 - ✅ **Routing holds** — named 47/48, described 26/28, scenario 7/8; behavioral L1–L4 all pass; private stores fenced out of the public bundle (zero-leak verified).
 - ⚠️ **Two routing residuals** (above) — surfaced, not hidden.

package/bin/install.mjs

@@ -740,6 +740,25 @@ async function doctor() {
   env.ruvector
     ? ok('RuVector present — vector CLI / MCP available')
     : warn('RuVector not found — answers still work. To add: claude mcp add ruvector --scope user -- npx -y ruvector mcp start');
+  // Network probe (issue #27, Jan Lafko): in a network-restricted sandbox the cold-cache embedder
+  // pull used to hang FOREVER. Diagnose the condition here, explicitly and in 3 seconds flat: if the
+  // model host is unreachable AND no local model cache exists, the first query needs the network and
+  // will fail loud (bounded by RUVNET_BRAIN_FETCH_TIMEOUT_MS) — tell the user BEFORE they hit it.
+  const modelCacheDir = process.env.KB_MODEL_CACHE || path.join(cacheDir, 'models-cache');
+  const haveLocalModel = fs.existsSync(path.join(modelCacheDir, 'Xenova', 'all-MiniLM-L6-v2'))
+    || fs.existsSync(path.join(modelCacheDir, 'Xenova/all-MiniLM-L6-v2'));
+  try {
+    await fetch('https://huggingface.co', { method: 'HEAD', signal: AbortSignal.timeout(3000) });
+    ok('model host reachable (huggingface.co) — cold-cache model download would work');
+  } catch {
+    if (haveLocalModel) {
+      ok(`model host UNREACHABLE, but the embedder is already cached locally (${modelCacheDir}) — queries work offline`);
+    } else {
+      warn('network-restricted environment detected: huggingface.co unreachable (3s probe) AND no local model cache.');
+      warn(`  The first query needs the embedder model once. Fix: on a networked machine run one query, then copy`);
+      warn(`  its model cache to this machine and set KB_MODEL_CACHE to that path. (Queries fail loud, not hang.)`);
+    }
+  }
   const v = verifyInstall(cacheDir);
   const smoke = await smokeQuery(cacheDir);
   const allGreen = v.repos > 0 && v.reader && v.mcp;
@@ -908,14 +927,25 @@ function runUpdate() {
   const kbDir = resolvedKbDir();
   info(`brain dir: ${c.bold(kbDir)}`);
   let updateStatus = 1;
-  if (fs.existsSync(path.join(kbDir, 'forge-update.mjs'))) {
-    info(c.dim("running the bundle's own self-updater (backs up first, re-verifies, never half-applies)…\n"));
-    // Relative filename + matching cwd — same launch convention as smokeQuery(); stdio:'inherit'
-    // streams the updater's narration live and unedited.
-    const r = spawnSync(process.execPath, ['forge-update.mjs', '--apply'], { cwd: kbDir, stdio: 'inherit' });
-    updateStatus = r.error ? 1 : (r.status === null ? 1 : r.status);
-  }
-  // FALLBACK (2026-07-17). The bundle's self-updater is missing OR failed — e.g. an OLDER bundle whose
+  // NO updater at all = no brain installed here (or a pre-self-updater bundle). That is a USER
+  // message, not a fallback trigger: fail LOUD with the re-run-installer help and exit — never
+  // surprise the user with a full fresh install as a side effect of `--update` on an empty dir.
+  // (Restored 2026-07-18: the 2026-07-17 fallback below accidentally swallowed this branch too,
+  // turning `--update` on an empty dir into a silent 512MB re-install — it hung CI's 60s smoke
+  // test on both platforms, mutated a dir the contract promises untouched, and on a machine with
+  // private KB stores a surprise fresh PUBLIC install is exactly the store-stripping hazard the
+  // project docs warn about. The fallback's own comment scopes it to an updater that EXISTS but
+  // is broken — this branch enforces that scope.)
+  if (!fs.existsSync(path.join(kbDir, 'forge-update.mjs'))) {
+    missingUpdaterHelp(kbDir);
+    process.exit(1);
+  }
+  info(c.dim("running the bundle's own self-updater (backs up first, re-verifies, never half-applies)…\n"));
+  // Relative filename + matching cwd — same launch convention as smokeQuery(); stdio:'inherit'
+  // streams the updater's narration live and unedited.
+  const r = spawnSync(process.execPath, ['forge-update.mjs', '--apply'], { cwd: kbDir, stdio: 'inherit' });
+  updateStatus = r.error ? 1 : (r.status === null ? 1 : r.status);
+  // FALLBACK (2026-07-17), scoped 2026-07-18 to exists-but-FAILED only. An OLDER bundle whose
   // canonicalManifestUrl points at the dead main/kb/.last-built.json path and 404s (the exact break a
   // real user, Jan Lafko, hit). NEVER leave the user stranded at a 404: re-run THIS installer as a
   // fresh install, which pulls the latest Release DIRECTLY (releases/latest) and never touches the

package/config/scheduled-jobs.json

@@ -91,7 +91,7 @@
     },
     {
       "label": "com.ruvnet.issue-fix",
-      "what": "Every 10 min: auto-fixes newly opened GitHub issues (stuinfla/ruvnet-brain) \u2014 bounded headless `claude -p` per issue in a disposable git worktree, pushes an issue-fix/<N> branch + comment or posts an honest triage comment, never touches main, never closes an issue",
+      "what": "Every 30 min (was 10 \u2014 a real run takes ~13 min, so the 10-min schedule SIGTERMed its own overlapping runs, fixed 2026-07-18): auto-fixes newly opened GitHub issues (stuinfla/ruvnet-brain) \u2014 bounded headless `claude -p` per issue in a disposable git worktree, pushes an issue-fix/<N> branch + comment or posts an honest triage comment, never touches main, never closes an issue",
       "schedule": "every 10 min",
       "maxAgeHours": 1,
       "required": true
@@ -100,7 +100,13 @@
       "label": "com.ruvnet.routing-flywheel",
       "schedule": "nightly 04:45",
       "maxAgeHours": 26,
-      "what": "nightly bounded live flywheel over routing policy (candidate+receipt only, never live routing)"
+      "what": "nightly data-readiness DRY-RUN of the routing flywheel (the plist runs --dry-run: reads receipts + prints readiness, runs NO loop and writes NO receipt — honest label per F13 2026-07-18; switch the plist to --synthetic to run a real $0 loop)"
+    },
+    {
+      "label": "com.ruvnet.npx-witness",
+      "schedule": "WatchPaths on ~/.npm/_npx (event-driven, no cadence)",
+      "maxAgeHours": 2160,
+      "what": "records every npx-cache mutation to the witness log (pure observer). Event-driven: weeks of silence are NORMAL when nothing touches _npx — maxAgeHours is a 90-day tripwire against the job being unloaded, not a freshness SLA. Registered per F2 2026-07-18: it was loaded+wrapped but absent here, i.e. unwatched by the registry's own definition."
     }
   ],
   "_retired": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "3.4.9-dev",
+  "version": "3.4.16-dev",
   "description": "One-command installer for RuvNet Brain — a portable, source-grounded brain over rUv's RuvNet building blocks, delivered as a Claude Code plugin so Claude uses the stack instead of fighting it.",
   "type": "module",
   "bin": {

package/scripts/job-heartbeat.sh

@@ -32,6 +32,14 @@ ts() { date -u +%Y-%m-%dT%H:%M:%SZ; }
 STARTED="$(ts)"
 START_EPOCH="$(date +%s)"
 
+# F3 (2026-07-18): remember the receipt as it was BEFORE this fire. A skip-fire (exit 75, the
+# reserved "another instance is already running" code) must not destroy the live run's evidence —
+# its finish() RESTORES this snapshot instead of overwriting the receipt with a meaningless "ok/0s".
+# Without this, a skip stamped state:"ok" over a real run's "running", and if that real run was then
+# SIGKILLed, the watchdog's started-and-never-finished detection had nothing left to see.
+PREV_HB=""
+[ -f "$HB" ] && PREV_HB="$(cat "$HB" 2>/dev/null)"
+
 # Start receipt. If the job vanishes without ever writing an end receipt, THIS is the evidence that
 # it started and never finished — a state the watchdog reports as FAILING, not as silence.
 cat > "$HB" <<EOF
@@ -39,6 +47,12 @@ cat > "$HB" <<EOF
 EOF
 
 notify() { # notify <title> <body> <priority>
+  # NTFY_TOPIC set-but-EMPTY is an explicit opt-out (2026-07-18): unit tests wrap this script around
+  # deliberately-failing fixture commands (t-fail, t.bad, exit 7), and the topic-file fallback below
+  # meant every test run PAGED Stuart's real phone — 16+ fixture pages in one morning, indistinguishable
+  # from real job failures. Tests set NTFY_TOPIC="" and stay silent; production (unset) still falls
+  # through to the topic file.
+  if [ "${NTFY_TOPIC+set}" = "set" ] && [ -z "$NTFY_TOPIC" ]; then return 0; fi
   topic="${NTFY_TOPIC:-}"
   [ -z "$topic" ] && [ -f "$HOME/.cache/ruvnet-brain/ntfy-topic" ] && topic="$(cat "$HOME/.cache/ruvnet-brain/ntfy-topic")"
   [ -z "$topic" ] && return 0
@@ -49,6 +63,15 @@ finish() {
   code=${FORCED_CODE:-$?}
   ended="$(ts)"
   dur=$(( $(date +%s) - START_EPOCH ))
+  # Exit 75 = SKIP (lock held by a live run). Restore the pre-fire receipt so the live run's evidence
+  # survives; report 0 to launchd (a skip is not a failure). If no receipt ever existed, record an
+  # honest "skipped" — which the watchdog treats as NOT proof of a real run.
+  if [ "$code" -eq 75 ]; then
+    if [ -n "$PREV_HB" ]; then printf '%s' "$PREV_HB" > "$HB"; else
+      printf '{"label":"%s","started_at":"%s","ended_at":"%s","state":"skipped","duration_sec":%s}' "$LABEL" "$STARTED" "$ended" "$dur" > "$HB"
+    fi
+    exit 0
+  fi
   if [ "$code" -eq 0 ]; then state="ok"; else state="failed"; fi
   cat > "$HB" <<EOF
 {"label":"$LABEL","started_at":"$STARTED","ended_at":"$ended","state":"$state","exit_code":$code,"duration_sec":$dur}

package/scripts/nightly-watchdog.mjs

@@ -87,6 +87,12 @@ export function judge(job, hb, loaded, now) {
   if (ageHours > job.maxAgeHours) {
     return { state: STALE, ageHours, detail: `last ran ${ageHours.toFixed(1)}h ago — its schedule allows ${job.maxAgeHours}h. It stopped.` };
   }
+  // A "skipped" receipt (lock-skip fired but no real run has EVER recorded a result — job-heartbeat
+  // restores the real receipt when one exists, so this only survives when there was none) proves the
+  // schedule fires, not that the work runs. Never count it as OK. (F3, 2026-07-18)
+  if (hb.state === 'skipped') {
+    return { state: NEVER_RAN, ageHours, detail: 'only a lock-skip receipt exists — no real run has ever recorded a result' };
+  }
   if (hb.state === 'failed' || (typeof hb.exit_code === 'number' && hb.exit_code !== 0)) {
     return { state: FAILING, ageHours, detail: `last run FAILED with exit ${hb.exit_code} (${ageHours.toFixed(1)}h ago)` };
   }
@@ -165,11 +171,24 @@ async function main() {
   const bad = results.filter((r) => r.state !== OK);
 
   const prev = loadState();
+  // DERIVED, not asserted (F1, 2026-07-18): a transition is only recorded as handled when its page
+  // was actually DELIVERED (push() returned true). The old code saved every new state unconditionally
+  // — so a FAILING job whose urgent page failed (ntfy down for a minute) was marked "alerted" and,
+  // because alerts are transition-only, would NEVER page again. Now an undelivered transition keeps
+  // its PREVIOUS state in the snapshot, so the same transition re-fires (and re-pages) on the next
+  // run until a page genuinely lands. The ledger can no longer claim a page that didn't happen.
+  const undelivered = new Set();
   for (const c of transitions(results, prev)) {
-    if (c.state === OK) await push(`✅ ${c.label} is healthy again`, c.detail, 'default');
-    else await push(`🔴 ${c.state}: ${c.label}`, `${c.what}\n\n${c.detail}\n\nschedule: ${c.schedule}`, 'urgent');
+    const delivered = c.state === OK
+      ? await push(`✅ ${c.label} is healthy again`, c.detail, 'default')
+      : await push(`🔴 ${c.state}: ${c.label}`, `${c.what}\n\n${c.detail}\n\nschedule: ${c.schedule}`, 'urgent');
+    if (!delivered) undelivered.add(c.label);
   }
-  saveState(Object.fromEntries(results.map((r) => [r.label, r.state])));
+  saveState(Object.fromEntries(results.map((r) => [r.label, undelivered.has(r.label) ? (prev[r.label] ?? OK) : r.state])));
+  // Sol amendment to F1: an undelivered page also FAILS this run (exitCode, not exit — the report
+  // below still prints). The watchdog's own heartbeat then records the degradation, so "the pager is
+  // broken" is itself a paged, visible condition instead of a silent one.
+  if (undelivered.size > 0) process.exitCode = 1;
 
   if (json) console.log(JSON.stringify({ results, checkedAt: new Date().toISOString() }, null, 2));
   else if (!quiet || bad.length) {