forge-update permanently stuck once kb.bak-*/kb.install-preserved-* accumulate; no reclaim/prune command exists

[pacphi]

Summary

npx ruvnet-brain --update refuses to run once ~/.cache/ruvnet-brain/ accumulates old
kb.bak-* / kb.install-preserved-* snapshots that forge-update's own safety check can't
clear ("unresolved rollback state exists; refusing to create another full-KB copy."). There's
no CLI path to resolve this — --doctor, --what-changed, and --uninstall don't touch it,
and there's no prune/reclaim/gc subcommand. The only way out today is deleting directories by
hand and manually verifying you're not losing data.

Repro

After enough --update cycles (installs on 2026-09-08, 09 (x3), 10, 19), my cache held 12
legacy snapshot dirs (~21GB total) alongside the live kb/ (~1.2GB). Attempting --update to
4.3.29 fails at the source-enumeration phase:

unresolved rollback state exists; refusing to create another full-KB copy.
  kb.bak-2026-07-13T10-47-54-235Z: inventory is incomplete; refusing destructive reclaim
    (legacy inventory contains unclassified non-RVF files)
  ...(4 more kb.bak-* dirs, same reason)...
  kb.install-preserved-69VtSI: it holds 183 store(s) the new copy does NOT have:
    concepts.big.rvf, ruv-gists.big.rvf, __MACOSX/._agentdb.big.rvf…
  kb.install-preserved-6oa0th: it holds 2 store(s) the new copy does NOT have:
    concepts.big.rvf, ruv-gists.big.rvf
  ...(4 more kb.install-preserved-* dirs, same 2 stores)...
  kb.install-preserved-vvWguB: PRESERVED_UNCLASSIFIED: complete byte redundancy is not proven;
    different bytes: kb.install-preserved-vvWguB/.console-runtime/bin/install.mjs
  Restore or reconcile that copy first, then re-run.

legacyBackupRetention in the refresh-run receipt confirms this isn't a fluke: it's a real
(non-dry-run) evaluation that kept everything, "freed": 0.

What I found investigating by hand

• 6 of the kb.install-preserved-* dirs (6oa0th, AezwrD, O9aAIg, bwOYOX, ksPDYz, vvWguB) are
  byte-identical to each other for every file they hold beyond what's already in the live
  kb/ (verified via sha256: concepts.*, ruv-gists.*, cognitum-ruos-primer.md,
  cognitum-ruos.symbols.json — same hash in every copy that has each file). Each also carries
  its own node_modules/ (an old installer's dependency tree, not knowledge data).
  vvWguB's flagged install.mjs byte diff is just a different installer script version
  (5634 vs ~5170-5259 lines) — not KB content.
• kb.install-preserved-69VtSI is a different story: ~300 non-junk top-level files (plus 758
  __MACOSX/._* zip-extraction artifacts) that don't exist in the current kb/ under the same
  names — mostly a legacy dual-variant layout (<repo>.rvf + <repo>.big.rvf per repo) from
  before the KB apparently consolidated to a single .big.rvf-only naming scheme. I could not
  fully rule out real content loss here without deeper tooling, so I left it alone.
• The 5 kb.bak-* dirs are pre-RVF-format legacy backups; I could not verify their inventory
  either way and left them alone too.

So roughly a third of the accumulation (7GB of the 21GB on my machine) was provably-safe,
byte-verified duplication I could clean up manually — the rest needs the tool's own format
knowledge to judge safely, which a user shelling out and grepping error text doesn't have.

Ask

A --reclaim (or similar) subcommand that:

1. Runs the same store-diff logic already computed during --update (it's already computing
   legacyBackupRetention per snapshot — this data exists, it's just not exposed standalone).
2. Reports, per snapshot dir, which are byte-identical duplicates of another kept snapshot vs.
   genuinely divergent, using the sha256 comparison the updater already has the infrastructure
   for.
3. Offers to archive the small set of genuinely non-redundant files (like concepts.* /
   ruv-gists.* here) to one canonical location and delete the rest, or at minimum prints
   the exact rm -rf command for entries it CAN prove are pure duplicates — the same evidence
   I had to reconstruct by hand.

Even a read-only --doctor-style report ("N snapshots use X GB; Y GB of that is provably
duplicate; Z GB needs manual review because ") would turn this from "silently stuck
forever" into something a user can act on without spelunking refresh-runs/*.json.

Environment

• ruvnet-brain bin install.mjs version: 4.3.29 (installed plugin: 4.3.28)
• darwin, Node via mise
• RUVNET_BRAIN_KB unset (default ~/.cache/ruvnet-brain/kb)

[pacphi]

Update: tested a workaround — it resolves the version block, but not the bloat

Since filing this, I tried npx ruvnet-brain --uninstall followed by a fresh npx ruvnet-brain
reinstall, to see if it would route around the stuck reclaim check. Results, in case they're
useful to anyone else hitting this:

It works for getting unstuck on version. --uninstall turns out to be narrower than I
expected — it only removes ~/.cache/ruvnet-brain/kb itself (plus telemetry/statusline/
model-router files); it does not touch kb.bak-* / kb.install-preserved-*, and doesn't
touch the Claude Code plugin or MCP registration either (those need claude plugin uninstall /
claude mcp remove separately, per the tool's own printed instructions). With kb/ gone, the
next npx ruvnet-brain install took the fresh-install path (obtainBundle()), not the
incremental-update path (forge-update.mjs --apply) — and only the latter runs the reclaim/
rollback check that was stuck. So the "unresolved rollback state" block is specific to
updating an existing kb/ in place; deleting it first sidesteps that code path entirely.
Landed cleanly on 4.3.29, search_ruvnet came back live on the fresh corpus with no Claude Code
restart needed (matches the "body-only releases go live on the next hook/MCP call" contract).

It does nothing for the actual disk bloat. Before: 21GB (12 legacy snapshot dirs). After
manually reclaiming the 6 I could prove were byte-identical duplicates (see original report):
14GB. After the full uninstall → reinstall cycle: still 14GB, same 5 kb.bak-2026-07-* +
1 kb.install-preserved-* dirs, completely untouched throughout. A fresh install also created a
new (thankfully empty, 0 bytes) kb.install-preserved-<random> dir of its own — presumably the
same "preserve the outgoing copy" logic firing even though there was nothing left to preserve.

So the net effect of the workaround is: trade "stuck on an old version" for "still carrying
~10-12GB of unreclaimable legacy snapshots forever" — not a fix, just a different flavor of the
same underlying problem.

Re-raising the ask

A --reclaim (or --gc/--prune) subcommand would still close the actual gap: expose the
store-diff logic forge-update's legacyBackupRetention already computes internally (real,
not dry-run — it already decided freed: 0 and kept everything last time), so a user can see
which snapshots are provably safe to remove (byte-identical to another kept copy, or to what's
already in the live kb/) vs. genuinely uncertain (legacy pre-RVF inventory it can't parse), and
act on the provable ones without hand-hashing directories themselves.

Environment: ruvnet-brain 4.3.29 (post-workaround), darwin, Node via mise.

[stuinfla]

🤖 Automated acknowledgment — received and opened. The maintainer has been paged and this is being worked. The next update here will be a fix, findings, or the maintainer in person.

[pacphi]

Checked against 4.3.34: system info, code pointers, and a possible shape for the fix

Thanks for the quick acknowledgment. This fills in what my report was missing, checked against the newest release (4.3.34, published 2026-09-27).

System info

• macOS 27.0 (26A428), arm64
• Node v26.4.0, npm 11.17.0 (Node via mise)
• ruvnet-brain KB: brainVersion 4.3.29 (~/.cache/ruvnet-brain/kb/SOURCE.json); latest on npm: 4.3.34
• Claude Code 2.1.283; RUVNET_BRAIN_KB unset
• Current cache: 14 GB, with 5 kb.bak-2026-07-1* dirs and 1 kb.install-preserved-69VtSI left after my manual cleanup of the provable duplicates

Still present in 4.3.34

I read the 4.3.34 package source (npm pack ruvnet-brain@4.3.34) and kb/forge-update.mjs at tag v4.3.34, which is identical to main. I did not run it.

• kb/forge-update.mjs:1076: reclaimBackups() is already an exported, self-contained classifier. It gives each snapshot a reason: inventory is incomplete; refusing destructive reclaim (:1165), PRESERVED_UNCLASSIFIED: complete byte redundancy is not proven (:1201), removed, or over budget.
• kb/forge-update.mjs:1463-1477: it runs only inside --apply, and any blockingRetained entry makes the whole update die("unresolved rollback state exists ...").
• bin/install.mjs:122-144: the CLI flags are --doctor, --update, --uninstall, --what-changed and others. None of them runs reclaimBackups() on its own or reports its result.
• bin/install.mjs:705: a fresh install creates ${cacheDir}.install-preserved-<id>, which is why the uninstall-and-reinstall workaround adds a new preserved dir instead of reducing the count.

Steps to reproduce (observed condition, not a synthetic repro)

Because the Brain is verified here by reading source only, this is the observed state plus the code path, not a disposable run:

ls -d ~/.cache/ruvnet-brain/kb.bak-* ~/.cache/ruvnet-brain/kb.install-preserved-*   # legacy snapshots present
npx ruvnet-brain --update                                                            # -> "unresolved rollback state exists; refusing ..."
ls -t ~/.cache/ruvnet-brain/refresh-runs/*.json | head -1 | xargs jq '.legacyBackupRetention'   # kept[], removed: [], freed: 0

A deterministic repro should be possible, though: put a kb.bak-<ts> directory containing one unclassified non-RVF file next to a disposable RUVNET_BRAIN_KB, then run --update. I have not run that, to avoid touching a live install.

Possible fix approaches (suggestions)

1. --reclaim --dry-run / --reclaim: a thin CLI wrapper around the existing reclaimBackups({ kbDir }). It would print each snapshot's classification and reason, plus the provably redundant bytes. Without --dry-run, it would remove only what the function already proves redundant.
2. Hash-level dedup across snapshots: a pass that marks files byte-identical to another kept snapshot or to the live kb/ as redundant, even when the whole-directory inventory is incomplete. That is what freed 7 GB here by hand.
3. Archive and release: for the rare genuinely unique stores (here concepts.* and ruv-gists.*), copy them once into a single kb.archive/ and then release the snapshot, so one unique file no longer pins a multi-GB directory.
4. --doctor line: "N snapshots, X GB; Y GB provably redundant; Z GB needs review because ".
   This would also fit the --doctor --json you planned in the agentic-kit sync briefing (docs/AGENTIC-KIT-SYNC-BRIEFING.md §5.4): a reclaim block there would let ak sync show the exact safe next step instead of only flagging the stuck update.

Impact

• Brain users: anyone who has updated through the pre-RVF era can end up permanently unable to --update, carrying 10–20 GB of snapshots they can't safely remove. The only way out today is to hand-hash directories, or to uninstall and reinstall, which fixes the version but not the disk use.
• Downstream: agentic-kit's ak sync flags the stuck update and the cache size. It can't offer a safe fix because the evidence for what is removable exists only inside forge-update.