Advertised "rebuilds itself nightly / never goes stale" isn't delivered to end users — nightly LaunchAgent is author-only, and releases/latest is 5 days stale

[sparkling]

Filing as appreciative downstream-consumer feedback — the grounding-hook idea is great and the brain is genuinely useful. This is a gap between the pitch deck's "nightly / never stale" promise and the shipped behavior, plus a concrete staleness symptom on a normal install.

What's advertised

The deck (https://deck-six-liart.vercel.app/) has a dedicated currency section (quoted verbatim):

• "Always current · rebuilds itself nightly"
• "Every night a LaunchAgent checks rUv's repos, rebuilds only what changed, re-verifies, and re-stamps — automatically."
• "rUv is prolific. So the Brain never goes stale." / "A static one would rot in weeks."
• "Bundle status · CURRENT · last rebuild · last night · 3:15 AM"
• "Honest: nightly, changed-repos-only (safe scope); brand-new repos are added under supervision."
• "Your instruction manual updates while you sleep."

The installer reinforces it — bin/install.mjs prints: "…auto-updating nightly)? Just tell Claude once it's on — the brain is smart enough to reconfigure itself."

(For contrast, the README and the main site are more measured — README: "Only moves when the underlying knowledge base is rebuilt"; site: "When he ships more, the Brain updates." The deck is the surface making the hard nightly/never-stale guarantee.)

What actually ships

1. The nightly LaunchAgent is author-only, by design. deploy/com.ruvnet.brain-nightly.plist:

• header comment: "NOT auto-installed (system schedulers require explicit owner approval)."
• ProgramArguments: cd /Users/stuartkerr/Code/ruvnet-brain && node scripts/self-update.mjs --apply --publish …

The absolute home path + --publish make this the maintainer's personal rebuild-and-publish job — a downstream user can't run it (wrong path; it would publish to your release). scripts/self-update.mjs says the same: "Designed to be invoked by deploy/com.ruvnet.brain-nightly.plist (LaunchAgent — NOT auto-installed)."

2. No end-user mechanism enables a per-user nightly. bin/install.mjs never installs a LaunchAgent — the "auto-updating nightly" line just defers to "Just tell Claude." package.json scripts is {} and the only bin is the installer. So a user who accepts the offered "auto-updating nightly" gets nothing scheduled.

3. Even the upstream publish isn't nightly. releases/latest = v0.5.0-dev, published 2026-07-01; prior v0.4.0-dev, 2026-06-29. As of 2026-07-06 that's 5 days with no new release, despite active main commits in between (e.g. the 2026-07-05 "brain-stamp … closes the freshness loop", and the plugin badge advancing to 1.9.1-dev while the KB bundle is still v0.5.0-dev). So the deck's live-looking "CURRENT · last rebuild · last night · 3:15 AM" status doesn't match the actual release cadence.

Concrete staleness symptom

Fresh macOS install; nothing in launchctl list (expected — the plist isn't auto-installed). The KB content (*.passages.jsonl, primers, *.meta.json) is frozen at 2026-07-01 03:31, matching the v0.5.0-dev bundle publish time. So the brain answers from a July-1 snapshot and misses recent rUv work — e.g. it never surfaces ruvnet/metaharness ADR-202 (agenticow ⇄ agentic-jujutsu COW dual-state bridge, dated 2026-06-28) or anything after; that repo is now at 218 ADRs, HEAD 2026-07-06. In practice, every "does X exist upstream?" answer had to be re-checked against live GitHub because the KB lagged.

Suggested directions (either / both)

• Deliver it: ship a user-facing enable step (e.g. ruvnet-brain --enable-nightly) that templates the plist to the user's install path, points at a non-publishing local self-update (or just pulls the latest Release bundle), and launchctl loads it — with an easy disable. Then "updates while you sleep" becomes true for end users too.
• Or align the claim: soften the deck to match the README/site (e.g. "refreshes when a new bundle is published"), make the "CURRENT / last rebuild" indicator a real live read, and/or fix the upstream nightly so releases/latest actually advances daily.

Environment

• macOS; plugin at ~/.claude/plugins/cache/ruvnet-brain/ruvnet-brain/0.5.0-dev
• KB bundle v0.5.0-dev (2026-07-01); KB content mtime 2026-07-01 03:31
• No com.ruvnet.brain-nightly in launchctl list

Thanks again — the enforced-grounding approach is a genuinely good idea. This is just about making the deck's "nightly / never stale" surface true for people who aren't running it from /Users/stuartkerr/….

[sparkling]

Update: a working local stop-gap, and a code-grounded fix so it delivers as promised.

While standing up a local refresh on top of this, I traced the exact break points in the build/update path (all on main, verified against v0.8.0-era source and the running plugin). Two parts: (1) a stop-gap any user can run today to get the promised "stays current" behavior — shared as a hold-until-fixed, not a proposed solution; and (2) the upstream fix, per file/line, so the "rebuilds itself nightly · never goes stale" promise is actually delivered.

---

Part 1 — Local stop-gap (works today; verified end-to-end on macOS)

This is what a user currently has to figure out by hand to get what the deck promises. Posting so others aren't stranded on a July‑1 snapshot while the real fix lands.

# 1. clone the brain repo — the KB build tooling isn't in the installed plugin cache
git clone --depth 1 https://github.com/stuinfla/ruvnet-brain ~/.cache/ruvnet-brain/repo
cd ~/.cache/ruvnet-brain/repo

# 2. install the KB BUILD deps — the missing, undocumented step (see Part 2, cause #2)
( cd kb && npm i )          # installs @ruvector/rvf + @xenova/transformers into kb/node_modules

# 3. refresh a repo to live HEAD (re-clones ruvnet/<name>, re-embeds MiniLM-384 + bge-768, symbols)
node scripts/ingest-repo.mjs --name agent-harness-generator

# 4. THE /kb BRIDGE — builds land in <clone>/kb, but the MCP server reads ~/.cache/ruvnet-brain/kb.
#    sync the artifacts across so the RUNNING brain actually sees them:
cp -f kb/agent-harness-generator.* ~/.cache/ruvnet-brain/kb/

Verified on this machine: after step 4, a query for ADR-202 agenticow jujutsu returns
docs/adrs/ADR-202-agenticow-jujutsu-dual-state-bridge.md (dated 2026‑06‑28) as the top hit — a
document the shipped v0.5.0-dev bundle misses entirely (34 chunks reference it in the fresh
store; zero in the shipped one). For a drift-aware nightly, wrap steps 3–4 in a
git ls-remote-vs-stored-SHA loop behind a per-user LaunchAgent templated to the user's own path
with --publish dropped.

To be clear: this is a stop-gap, not the fix. It requires a manual clone, an undocumented
cd kb && npm i, and a manual cache-sync that no user should have to reverse-engineer.

---

Part 2 — Upstream fix (code-grounded), so "rebuilds itself nightly · never goes stale" is real

Five concrete gaps between the promise and the code, each with a fix:

Cause 1 — the only nightly LaunchAgent is author-only.
deploy/com.ruvnet.brain-nightly.plist hardcodes /Users/stuartkerr/Code/ruvnet-brain + --publish
and is marked "NOT auto-installed." No end user can use it.
→ Fix: ship ruvnet-brain --enable-nightly that templates the plist to the user's paths, drops
--publish, and launchctl loads it (plus --disable-nightly). Make the "Just tell Claude … auto-updating
nightly" line (bin/install.mjs ~L833) actually invoke it instead of being a no-op suggestion.

Cause 2 — the KB build deps are never installed for users.
kb/package.json declares @ruvector/rvf + @xenova/transformers, but bin/install.mjs only fetches
the prebuilt bundle — it never runs cd kb && npm i. So ingest-repo.mjs / self-update.mjs die
immediately with Cannot resolve '@ruvector/rvf' for anyone who tries the "reconfigure yourself" path.
(This is exactly what the stop-gap's step 2 works around.)
→ Fix: the enable step (or a --with-build-tools) runs npm i in kb/ as part of setup.

Cause 3 — build output ≠ server read path.
ingest-repo.mjs / self-update.mjs write to <repo>/kb (hardcoded ROOT/kb), but
mcp/server.mjs:20 reads RUVNET_BRAIN_KB || ~/.cache/ruvnet-brain/kb. A successful local build is
therefore invisible to the running brain (the stop-gap's step 4 bridges this by hand).
→ Fix: have the local-refresh path build straight into (or rsync into) ~/.cache/ruvnet-brain/kb,
or set RUVNET_BRAIN_KB to the build dir in the enable step.

Cause 4 — self-update.mjs couples "refresh my local KB" with "publish a release."
The one script does rebuild → stamp → build-bundle → (gated) publish. An end user wants only the first
half; the publish half is author-only (needs repo write). There's no clean no-auth "just refresh
locally" entry point.
→ Fix: split a no-auth refresh-local (rebuild changed → land in the cache) from the author-only
--publish. The per-user LaunchAgent calls the former.

Cause 5 — the published bundle isn't actually nightly, and the "CURRENT" badge is static text.
releases/latest = v0.5.0-dev @ 2026-07-01, 5 days stale despite active main commits — so even
the reinstall path only ever fetches stale content. Meanwhile the deck's "Bundle status · CURRENT ·
last rebuild · last night · 3:15 AM" is fixed text, not a live read.
→ Fix: run rebuild+publish as a GitHub Actions cron (host-independent — an author's-Mac plist
can't be a reliable nightly), so releases/latest advances daily; and make the deck's status line a
live read of releases/latest.published_at so it can't claim "last night" when the bundle is 5 days old.

---

Net: Cause 5 alone (CI cron publish + a live status line) makes the reinstall path honestly
"current." Causes 1–4 make the local nightly the deck describes ("updates while you sleep")
actually installable by end users. Ideally both.

Happy to PR the --enable-nightly installer step + the per-user plist template + the kb/ dep-install
if that's useful.

[sparkling]

Correction — my ADR-202 example was wrong. Thanks to the reviewer on another install who caught it.

A reviewer flagged that my headline proof ("the shipped bundle misses ADR-202 entirely") doesn't
reproduce — and they're right. I re-checked it properly against the timeline:

• ADR-202-agenticow-jujutsu-dual-state-bridge.md was added 2026-06-28 18:18 (commit 5adcb08).
• The v0.5.0-dev bundle was built from commit a7d4b8 @ 2026-06-28 21:14 — three hours later.
• The file exists at that build commit (7460 bytes), and forge-build embeds .md, so the bundle
  contains ADR-202.

My claim was wrong. I mistook a search_ruvnet ranking miss (ADR-202 didn't crack top-6 for the
queries I ran, so I found it faster via live GitHub) for absent content. Those aren't the same thing,
and I stated it far too dramatically. Apologies.

What the bundle actually misses (the real, still-valid freshness gap): everything committed after the
2026-06-28 build — 63 commits on main as of today, including a genuinely-absent ADR run: ADR-228
(GEPA distilled-executor genome, #64), ADR-230 (agenticow branch-memory in the GEPA candidate loop,
#65), ADR-231–233, and ADR-234 / 235 / 236 — the flywheel "honest-null" series, all dated
2026-07-06. Ironically the correct "missing agenticow ADR" is ADR-230, not 202 — I conflated the two
agenticow docs (the 06-28 dual-state bridge, which is present, vs the ~07-02 GEPA branch-memory pilot,
which isn't).

What still stands — unchanged, and reproduced on the other install:

• No per-user nightly is scheduled (launchctl empty); KB content frozen at 2026-07-01; "updates
  while you sleep" not delivered on a normal install.
• Part 2's five code causes (author-only plist; installer never wires a per-user nightly; kb/ build
  deps never npm i'd; build-writes-to-<clone>/kb vs server-reads-~/.cache/…/kb; releases/latest
  5 days stale) — all still verified from source.

So the freshness gap is real but ~8 days, not "misses late-June": a user isn't blind to the
dual-state-bridge work, they're blind to the July 2–6 flywheel / honest-null series. The bug (no
working nightly + a "never goes stale" claim that isn't delivered) is unaffected — only my example was
mis-chosen. Correcting in the open, for the record.

One triage note for the other install: the metaharness repo is in the bundle — indexed as
agent-harness-generator.* (its former name), not metaharness.* — so it's not a missing repo, it's a
stale repo. The accurate targeted fix is refreshing that one store to live HEAD (which surfaces
ADR-230/234/235/236), not adding a new repo.

[sparkling]

A real fix for the root cause, not just the stop-gap: incremental updates, using an API this repo already ships with.

Following up on the stop-gap in my earlier comment — I dug into why a refresh is so expensive, since "rebuilds itself nightly" is a much smaller promise to keep if a rebuild is cheap. Found the answer directly in this repo's own dependency.

The root cause of the cost

kb/forge-build.mjs and kb/forge-big.mjs always do a full wipe-and-rebuild, regardless of how much actually changed:

fs.rmSync(OUT_RVF, { force: true });
const db = await RvfDatabase.create(OUT_RVF, { dimensions: 384, metric: 'cosine' });

Every refresh re-walks the entire tree, re-chunks everything, and re-embeds every chunk through two models (MiniLM-384 + bge-768) — even chunks whose text hasn't changed since the last build. That's why a refresh costs minutes even for a repo where only a handful of files actually moved.

@ruvector/rvf (a dependency this repo already has) doesn't have this limitation

node_modules/@ruvector/rvf/dist/database.d.ts shows RvfDatabase already supports incremental writes — open() an existing store (not just create()), ingestBatch() to add/update vectors, delete(ids) / deleteByFilter() to prune, compact() to reclaim space. None of forge-build.mjs/forge-big.mjs call any of these. The storage engine can do incremental updates; the build script just never asked it to.

The fix (implemented, tested locally against real repos — not just designed)

Added a --incremental mode to forge-build.mjs (and a matching incremental mode to forge-big.mjs) that reconciles instead of rebuilding:

1. The walk + chunk step is unconditional (cheap — seconds, not minutes) and produces the exact same in-memory chunk list as today.
2. Each chunk is keyed by (path, chunkIndex) — the same key meta.json already stores (entries[id].path + entries[id].chunk), so no ID-scheme change, fully backward-compatible with every existing store.
3. Compare against the old meta.json + passages.jsonl:
   • key exists, text identical → unchanged, skip embedding entirely, reuse the same id
   • key exists, text differs → changed, reuse the same id, needs re-embedding
   • key doesn't exist → new, assign a fresh id
   • old key has no current counterpart (file deleted/shrank) → stale, gets delete()d
4. RvfDatabase.open() the existing store, delete() the stale ids, embed only the changed/new chunks, ingestBatch() those, compact().
5. forge-build.mjs writes a small plan file ({toEmbedIds, toDeleteIds}) so forge-big.mjs's incremental mode doesn't have to re-derive the same diff — it just applies the identical reconciliation to .big.rvf using bge, reading the now-updated text from passages.jsonl.
6. Falls back automatically to the existing full-rebuild path when no prior baseline exists (first-ever ingest of a repo) — the incremental path is purely additive, the default behavior is untouched.

Measured results (real repos, not synthetic)

Repo	Old chunks	Current chunks	Deleted	Changed/new	Time (incremental)	Time (full, observed earlier)
sparc	215	211	4	0	2.9s	~5-8 min
ruview	7415	4149	3413	230	39.7s	~20 min
ruvector	28297	18491	12450	3345	8m 18s (base 108s + bge 385s + symbols/sync)	~45-50 min (extrapolated: ~11min base @ 29/s for all 18491 + ~38min bge @ 8/s for all 18491)

Every case verified for correctness before and after: identical query results for unchanged content, and full reconciliation across .rvf vector count / passages.jsonl line count / meta.json entry count / the .big.* mirrors (all match exactly, e.g. 211/211/211/211 for sparc).

Why this matters for the original issue

This is what actually makes "rebuilds itself nightly" cheap enough to be true for an end user, not just for the maintainer's own beefier build box. Combined with the earlier stop-gap (per-user LaunchAgent, kb/ dep install), a nightly refresh of a repo with modest day-to-day drift now costs seconds to low-minutes instead of minutes-to-tens-of-minutes per repo — the difference between "plausible to run nightly on a laptop" and "a real ongoing cost most users will eventually turn off."

Happy to open a PR with these two files (forge-build.mjs, forge-big.mjs, plus the one-line ingest-repo.mjs wiring for an --incremental --baseline-dir flag) if useful — implemented and validated against your real registry repos, not a toy example.

[sparkling]

Correction to my last comment, and a separate real bug found in the process: self-update.mjs's own FULL_HINTS map is incomplete.

Retracting the emphasis of my previous comment

I built a custom chunk-level incremental diff-and-patch engine (added to forge-build.mjs/forge-big.mjs) because full rebuilds seemed slow. On reflection this was solving a problem that didn't need a new mechanism: self-update.mjs already does the right thing — drift-checks each repo via git ls-remote vs manifest.json, and only full-rebuilds repos that actually changed. The real, minimal bug in this issue was always just "nothing schedules this script," which my original LaunchAgent stop-gap already addressed correctly. Building a second, parallel update mechanism was unnecessary scope creep on my part, and it introduced a real regression: my custom path calls forge-build.mjs without ever passing --full, silently downgrading full-body source indexing to thin doc-comment-only snippets for every repo it touched. self-update.mjs doesn't have that specific bug — it already threads --full through correctly for the repos it knows about.

Recommendation: ignore my incremental-diff engine as a fix for this issue. The fix that actually matters is just: schedule self-update.mjs --apply (no --publish) via a per-user LaunchAgent, as originally proposed. I'm not suggesting the diff-and-patch code be adopted upstream.

The real, separate bug: FULL_HINTS in scripts/self-update.mjs is incomplete

const FULL_HINTS = { ruflo: 'v3/@claude-flow,v3/mcp,ruflo/src' };

This is the only entry. But checking the actually-shipped v0.5.0-dev bundle's kb/*.passages.jsonl directly, several other registry repos clearly have substantial full-body source indexing (a Source <path> (full body): prefix, only emitted by forge-build.mjs when a file's path matches a --full prefix):

Repo	Full-body entries in the shipped bundle
qudag	531
daa	266
agentdb	178
rulake	93

None of these repos appear in FULL_HINTS. That strongly suggests the original bulk registry build (whatever produced the v0.5.0-dev bundle) was run with per-repo --full arguments that were never captured back into self-update.mjs's own map. The practical consequence: the first time self-update.mjs ever drift-rebuilds one of these repos (or presumably others in the registry with the same undocumented pattern), it will rebuild without --full, silently stripping that repo's full-body source depth down to doc-comment-only snippets — the same regression I introduced by hand, except this would happen automatically, the first time any of these repos actually drifts, via the tool's own intended update path.

Suggested fix: audit which repos in the shipped bundle currently have full-body entries (a one-time grep -c '(full body)' <name>.passages.jsonl per store, same check I used to find this), and backfill FULL_HINTS with the correct prefix per repo before wiring up any automated nightly. Happy to share the exact prefixes I can infer if useful, though the authoritative source would be whatever build command originally produced the bundle.

[sparkling]

Opened a focused PR for the FULL_HINTS gap found while working this issue: #5 — adds the four missing entries (agentdb, rulake, daa, qudag), with the full evidence/derivation in the PR description.

[sparkling]

Update: PR #5's scope grew significantly after a full audit — it wasn't 4 repos missing from FULL_HINTS, it was 14 (only ruflo was ever recorded). ruvector alone had 1302 full-body entries with no hint. Confirmed the regression happens in practice, not just in theory: rebuilding agent-harness-generator via self-update.mjs --apply took it from 201 full-body entries to 0 in this session — now fixed and re-verified. PR #5 updated with the full table and an observation (not yet acted on) that a tier-based default might be a better long-term fix than an ever-growing list.

[sparkling]

Root cause of the FULL_HINTS gap, found via commit archaeology (not a deliberate design choice).

Wanted to check whether omitting these repos from FULL_HINTS was intentional before assuming it was a bug. It wasn't — found the exact history:

61ad43b9 (2026-06-30, "Deep-brain depth fixes") explicitly recorded fixing depth for 5 of these repos:

"Brain depth (ships via the Release bundle; .rvf stores are gitignored): re-indexed qudag(531), daa(266), safla(0→136), ruv-fann(779), agentic-flow(984) with corrected per-repo --full prefixes after a depth audit found the one-size prefix list under-indexed every code-rich repo."

So someone did do a real depth audit and apply correct --full prefixes — but note ".rvf stores are gitignored." That fix was applied by running forge-build.mjs manually with the right flags to patch the shipped bundle directly. The exact prefix strings used were never written back into FULL_HINTS, which is tracked in git. The bundle got fixed; the automation that would keep it fixed didn't inherit the change.

Why nobody caught this until now: c244f4e8 (2026-07-05, yesterday) — "Freshness-loop bug: unknown-SHA repos never rebuilt" — self-update.mjs's own drift-check treated a builtFromSha: "unknown" stamp as "up to date," so ruflo/agentic-flow (and structurally, presumably others) were never actually rebuilt by the automated path. That guard was only fixed yesterday. So the FULL_HINTS gap existed silently because the code path that would expose it — an automated rebuild actually running — was itself broken until 24 hours before I found this. I'm likely the first person to trigger a real post-fix automated rebuild of one of these repos, which is exactly why it surfaced now rather than a week ago.

No ADR documents any of this either way — this is pure git-log reconstruction, not a documented decision I'm contradicting.

Net effect: this doesn't change PR #5's fix, but it does explain why it's needed now specifically — the freshness-loop fix from yesterday means self-update.mjs will start actually rebuilding previously-stuck repos, and without the FULL_HINTS fix, each one would silently regress from full-body depth back to snippets the first time that happens (exactly what I caught happening live to agent-harness-generator).

[sparkling]

Update: PR #5 now covers more than the original FULL_HINTS gap.

While verifying the freshness loop, found that 10 repos with content already in the shipped bundle (agentdb, agentic-flow, daa, qudag, fact, ruv-fann, dspy.ts, rulake, ruv-dev, rupixel) had no manifest.json stamp, so self-update.mjs classified them as "new" and silently skipped them from the nightly freshness loop forever, regardless of whether they actually drifted. Verified each has had zero commits since before the shipped snapshot (no content was missing), then cloned + stamped them with their real SHA.

Also found self-update.mjs hardcodes https://github.com/ruvnet/${name} in two places, meaning it structurally cannot track any repo outside the ruvnet org. Added an optional owner/repo field (backward compatible) and used it to onboard 4 new repos: agenticow, CVE-bench (both ruvnet), and cognitum-cogs/cognitum-support (cognitum-one org — the first cross-org entries).

Full details in the updated PR #5 description.

[sparkling]

One more small find while verifying the PR #5 fixes: ruvnet/agent-harness-generator was renamed upstream to ruvnet/metaharness (confirmed via HTTP 301 redirect + the repo's own package.json still internally referencing the old name/URL — same commit history, same content, not a fork or separate project).

git/gh follow the redirect transparently, so nothing is currently broken, but it's fragile to depend on a GitHub redirect indefinitely. Added an explicit repo: "metaharness" field to the registry entry (using the owner/repo override from PR #5) so future clone/fetch operations target the current canonical name directly. No re-indexing needed — same repo, already covered under the existing agent-harness-generator kb-store name. Pushed to the same PR #5 branch.