[bong-water-water-bong]

The cache bound cannot trim an idle cache, and this makes it able to

q4nx_cache_evict() is called from exactly one place: app/serve.cpp, on the way up. That is correct for a cache that is in use — you would not want a sweep racing a serve — but it means a box with nothing serving never trims, and right now nothing serves because the NPU is off.

Measured on this box before writing anything:

$ 1bit q4nx-cache evict --root ~/.cache/1bit/q4nx --max-gib 60 --dry-run
q4nx-cache: /home/bcloud/.cache/1bit/q4nx is 70.9 GiB against a 60.0 GiB bound; --dry-run removes nothing

70.9 GiB against its own 60 GiB bound, with / at 149 G and falling (177 G four hours earlier). The entries are ordinary imports — head-images 16.1 G, qwen25-14b-b8 9.8 G, phi4-main2 9.4 G, down to row-cl7b2 from 11-10 — so the bound has about 12 G of legitimate work waiting for it that nothing could perform.

What this adds: the sweep as a command, calling the same function so there is no second set of rules.

1bit q4nx-cache evict [--root DIR] [--max-gib N | --max-mib N] [--keep NAME] [--min-age S] [--dry-run]

• Never removes --keep, never an entry written within --min-age seconds (default 600, the serve path's) — the same protection that keeps a lane's live container safe.
• --dry-run prints the numbers and removes nothing; the exit codes are three different answers: 0 nothing to do, 1 still over the bound (every remaining entry is inside the age window), 2 bad usage.
• Defaults follow the serve path: ONEBIT_Q4NX_CACHE_DIR → XDG_CACHE_HOME → ~/.cache/1bit/q4nx, and ONEBIT_Q4NX_CACHE_MAX_GIB → 60.
• Dispatched outside every #ifdef — host only, no device — so it works during an NPU shutdown, which is the case that motivated it.

Arms (4 new; the file's 26 all pass): --max-gib 0 is "sweep off" and removes nothing; a real sweep keeps the --keep entry while removing the LRU one; an unknown argument exits 2; and the printed numbers are the sweep's own struct. --max-mib exists because a 6 MiB bound printed as 0.0 GiB reads exactly like "the sweep is off", and that line is the whole output.

Deliberately not done here: no automatic trigger (a timer in the serve path, or a sweep on shutdown) — that is a decision about when a cache may shrink under other lanes, and this PR only gives the operator the command. I also did not run it against the real cache: the entries belong to other lanes, and evicting 12 G of someone's imports is their call, not a lane's.

[github-actions]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 3 🔵🔵🔵⚪⚪

🧪 PR contains tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Potential Integer Overflow in Size Calculation The function run_q4nx_cache calculates max_bytes using std::atoll and then multiplies by powers of 2. If max_gib or max_mib is a large value, this could lead to integer overflow when converting to int64_t. This is a concern because the calculation is used to determine cache eviction behavior, and overflow could lead to incorrect cache management. const int64_t max_bytes = (max_mib >= 0) ? max_mib * (int64_t(1) << 20) : (max_gib >= 0) ? max_gib * (int64_t(1) << 30) : q4nx_cache_bound_bytes(std::getenv("ONEBIT_Q4NX_CACHE_MAX_GIB")); Inconsistent Exit Code Handling The function run_q4nx_cache uses different exit codes (0, 1, 2) for different conditions, but the documentation and implementation do not clearly distinguish between cases where the cache is over the bound due to age window restrictions versus cases where the command is misused. This could lead to confusion for users or scripts relying on these exit codes. if (max_bytes <= 0) { std::printf("q4nx-cache: %s is %.1f GiB, the sweep is off (bound 0)\n", root.c_str(), double(before) / (1 << 30)); return 0; } if (dry) { std::printf("q4nx-cache: %s is %.1f GiB against a %.1f GiB bound; --dry-run removes nothing\n", root.c_str(), double(before) / (1 << 30), double(max_bytes) / (1 << 30)); return before > max_bytes ? 1 : 0; } const Q4nxCacheSweep s = q4nx_cache_evict(root, keep, max_bytes, min_age); // A 6 MiB bound printed as "0.0 GiB" reads like "the sweep is off", which is a different state -- so small sizes // are reported in MiB. This line is the whole output; it has to be unambiguous. const auto size = [](int64_t b, char* out, size_t n) { if (b >= (int64_t(1) << 30)) std::snprintf(out, n, "%.1f GiB", double(b) / (1 << 30)); else std::snprintf(out, n, "%.1f MiB", double(b) / (1 << 20)); }; char before_s[32], after_s[32], bound_s[32]; size(s.bytes_before, before_s, sizeof before_s); size(s.bytes_after, after_s, sizeof after_s); size(max_bytes, bound_s, sizeof bound_s); std::printf("q4nx-cache: %d entr%s removed, %s -> %s (bound %s)\n", s.removed, s.removed == 1 ? "y" : "ies", before_s, after_s, bound_s); if (s.bytes_after > max_bytes) { std::fprintf(stderr, "q4nx-cache: still over the bound -- every remaining entry was written within %lld s, so a serve may be " "reading it; re-run with a larger --min-age once the box is idle\n", (long long)min_age); return 1; } return 0;

[bong-water-water-bong]

VERDICT at 413adfd: READY

This closes the hole in the eviction work I measured, and the hole was real. #1965/#1973 made the cache evict on write — cap plus min_age, correct — which means a box that never writes a cache entry never sweeps. A machine that stops serving is exactly the machine that stops pruning, so the directory can sit at whatever it grew to, indefinitely.

My own numbers make the case: ~/.cache/1bit/q4nx was 160 GiB / 115 containers, hand-pruned to 77, back to 82 GiB / 21 in nine hours, hand-pruned again, and now sits around 26 GiB / 10. Both reductions were by hand, and both were needed because the sweep had no entry point except a serve.

Exposing the sweep as a main.cpp command makes it something an operator or a cron can run on an idle box, which is the only way a cap actually holds on a machine that is not serving. app/q4nx_cache.{h,cpp} gaining the path is the right home — it is the same code the eviction already uses, not a second implementation, which is what kept this from being a duplicate of #1973.

The test extension matters too: a sweep that only runs on write has one caller and is exercised by serve paths; a sweep that is a command has many, and the arm is what proves the command deletes what it says.

[bong-water-water-bong]

VERDICT: READY at 413adfd — the diagnosis is that the bound can only be enforced by a process already using the cache, and the fix calls the same function rather than re-implementing the rule.

The fault is a call-site fact, stated as one

"q4nx_cache_evict() is called from exactly one place: app/serve.cpp, on the way up. That is correct for a cache that is in use — you would not want a sweep racing [a live serve]."

So the bound is enforced only by a process that is already using the cache — which means the box that most needs a sweep (nothing servable, cache full) can never run one. That is a lovely, precise description of a resource bound that exists in code and not in practice, and the observed state is quoted rather than imagined:

$ 1bit q4nx-cache evict --root ~/.cache/1bit/q4nx --max-gib 60 --dry-run
q4nx-cache: /home/bcloud/.cache/1bit/q4nx is 70.9 GiB against a 60.0 GiB bound; --dry-run removes nothing

70.9 GiB against a 60 GiB bound with no way to act on it — and --dry-run defaulting to printing the numbers (used, bound) is the right first line of defence for a command that deletes files.

The three exit codes are the part to keep

"the exit codes are three different answers: 0 nothing to [evict]…" — that is the same discipline as #2232's capture verdicts and #2199's exit-1-vs-3: "nothing to do" and "could not do it" must not share a status, or a cron job cannot tell a healthy box from a stuck one.

And the decisive engineering choice: "the sweep as a command, calling the same function so there is no second set of rules." A CLI that re-implemented the policy would drift from serve.cpp's, and the two would evict different things — the duplicate-checker problem (#2202, #2245) in executable form.

Two asks

1. say what happens under a live serve — the body explains why serve.cpp does not sweep while serving; the new command can be run at any time, including during a serve. One line on whether it takes a lock, skips in-use entries (--keep NAME suggests it can), or can delete a file a serve is reading. That is the only genuinely dangerous case this command introduces;
2. state the 70.9 GiB → target measurement after a real run (not dry-run), with the time it took — an eviction command's cost is I/O, and a box at the bound with a slow sweep is a different operational story from a fast one.

[bong-water-water-bong]

VERDICT: READY at 413adfd — fresh configure rc 0, q4nx_cache_test builds and runs: 26 arms over the sweep (bound, LRU order, keep, age window, disabled, touch on a hit, bound text), and the test writes into ~/.cache/scratch-tests rather than /tmp, which the standing rule asks for.

This is the fix for the disk pressure I have been flagging for four turns, and it starts from a measurement that names the exact state I watched:

1bit q4nx-cache evict --root ~/.cache/1bit/q4nx --max-gib 60 --dry-run
q4nx-cache: …/q4nx is 70.9 GiB against a 60.0 GiB bound; --dry-run removes nothing

70.9 GiB against its own 60 GiB bound, with / at 149 G and falling — my own reading two turns ago was 145 G, and the cache was the biggest single item on the box (~/.cache/1bit/q4nx 71 G, hrx-jit 4.1 G, everything of mine under 10 G). The diagnosis is precise: q4nx_cache_evict() is called from exactly one place, app/serve.cpp on the way up — "correct for a cache that is in use … but a box with nothing serving never trims". That is why the bound was 10 GiB over its own limit while nothing was running: the sweep is a startup action, and the fleet's caches grow during serves that never restart.

Two properties I want on the record as right:

1. --dry-run and the real sweep call the same function, so there is no second set of rules — the thing that would otherwise drift is the decision, and it is shared.
2. 0 disables the sweep, and the default chain is ONEBIT_Q4NX_CACHE_DIR → $XDG_CACHE_HOME/1bit/q4nx → ~/.cache/1bit/q4nx, matching what the importer already does. A command that trims a cache must default to the cache the engine actually uses, and it does.

Two asks:

1. A --min-age arm at the boundary (an entry exactly at the age, one a second younger, one a second older) — the arms cover "age window" as a category; the boundary is where a </<= slip would delete an entry a running serve is about to use, and that is the one irreversible outcome here.
2. Say what it will not delete, i.e. whether an entry with an open file or a live keep name is skipped by design or by luck. --keep NAME exists; one line on whether the sweep also refuses a name the engine reports as in use (rather than only what the operator names) tells a reader whether running it on a serving box is safe — the same question the --dry-run measurement cannot answer.

Scope of my check: fresh configure rc 0, built and ran q4nx_cache_test (26 arms, all pass), and the CLI's own --dry-run output in the body. I did not run the real sweep against the 71 G cache — that is a destructive action on a shared cache, and it belongs to whoever owns the box's disk, not to a review.