q4nx cache: an invoker for the sweep, because nothing sweeps a box that never serves (#2263)

cmake/tests-q4nx-cache-timer.cmake

@@ -0,0 +1,20 @@
+# Copyright 2026 bong-water-water-bong
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# engine#2263: scripts/install-q4nx-cache-timer.sh generates a systemd --user sweep for a box that never serves. Its
+# --self-test checks the generated units, the refusals (--max-gib 0 means OFF, an empty --interval never fires) and the
+# capability probe that stops a timer being installed against a binary older than engine#2251 -- all with stubs, so no
+# systemd, no cache and no binary are touched.
+add_test(NAME q4nx_cache_timer_self COMMAND ${CMAKE_SOURCE_DIR}/scripts/install-q4nx-cache-timer.sh --self-test)

docs/npu.md

@@ -311,6 +311,16 @@ every day outlives a one-off imported yesterday. The value is read as a whole nu
 number too large to be a byte count is the largest bound that is one (it does not wrap to a small
 one), and a value that is not a number gets the default rather than an unbounded cache.
 
+**A box that never serves never sweeps (engine#2263).** Both triggers — the write-time sweep and the manual
+`1bit q4nx-cache evict` — need the binary to run, so a review, CI or build box that holds the cache and never starts a
+serve keeps every entry it ever wrote. Measured on this box: **59 GiB in 12 h** with the command merged and nothing
+invoking it, which put free space 3 GiB under the 175 GiB build gate; one manual 24 h age cut took it to 24 GiB and it
+regrew. `scripts/install-q4nx-cache-timer.sh` installs the invoker as a `systemd --user` timer — hourly,
+`--max-gib 40 --min-age 86400`, opt-in, nothing outside `~/.config/systemd/user` — and refuses to install against a
+binary that predates the command (`1bit q4nx-cache` printing *unknown command*), because a timer naming a command the
+binary lacks fails hourly and silently. `--dry-run` prints the units and verifies them without changing anything;
+`--uninstall` removes them and leaves the cache alone.
+
 **The packed lm-head is cached beside it (engine#1716).** A model whose head runs as int8 tiles
 packs those tiles on the host — gather `kpad × T` weights per tile, quantise each column to int8
 with its own scale — and until this cache that happened on every serve. The image is a function

onnx/bench_npu.sh

@@ -45,6 +45,10 @@
 #   PORT               serve port                                              (default 52625)
 set -uo pipefail
 
+# usage(): the header comment as prose, anchored on the comment block rather than a line range -- several of these ranges
+# had drifted past the end of their header and printed code to whoever asked for help (the same defect engine PR #2258 fixed in scripts/).
+usage() { awk 'NR>1 && /^#/ {sub(/^# ?/,""); print; next} NR>1 {exit}' "$0"; }
+
 BIN="${ONEBIT_BIN:-$HOME/src/engine-laya-npu/build-npu/1bit}"
 MODEL="${ONEBIT_MODEL:-$HOME/.config/flm/models/Qwen3-0.6B-NPU2}"
 KERNELS="${ONEBIT_DX_KERNELS:-}"
@@ -60,7 +64,7 @@ while [ $# -gt 0 ]; do
         --kernels) KERNELS="$2"; shift 2 ;;
         --port) PORT="$2"; shift 2 ;;
         --lens|--gen|-w|--warmup|-r|--repeat|--mode|--endpoint) BENCH_ARGS+=("$1" "$2"); shift 2 ;;
-        -h|--help) sed -n '2,30p' "$0"; exit 0 ;;
+        -h|--help) usage; exit 0 ;;
         *) echo "bench_npu.sh: unknown option $1" >&2; exit 2 ;;
     esac
 done

os/v2/mkdebs.sh

@@ -42,7 +42,11 @@
 # prefix (bin/lemond, bin/lemonade, bin/resources). <version> is the release tag, with or without the
 # leading v: v2026.43 becomes 2026.43-1.
 set -euo pipefail
-[ $# -ge 4 ] || { sed -n '22,45p' "$0"; exit 2; }
+
+# usage(): the header comment as prose, anchored on the comment block rather than a line range -- several of these ranges
+# had drifted past the end of their header and printed code to whoever asked for help (the same defect engine PR #2258 fixed in scripts/).
+usage() { awk 'NR>1 && /^#/ {sub(/^# ?/,""); print; next} NR>1 {exit}' "$0"; }
+[ $# -ge 4 ] || { usage; exit 2; }
 stage_in=$1 lemon=$2 version=${3#v} out=$4 keyring=${5:-} kstage=${KERNEL_STAGE:-} kver=
 here=$(cd "$(dirname "$0")" && pwd)
 src=$(cd "$here/../.." && pwd)

os/v2/mkrepo.sh

@@ -21,7 +21,11 @@
 # Release file is produced unsigned and the script says so - useful for a local run, never for
 # publishing. The result is a directory of static files: publish it to 1bit.gg/apt as it is.
 set -euo pipefail
-[ $# -ge 2 ] || { sed -n '21,27p' "$0"; exit 2; }
+
+# usage(): the header comment as prose, anchored on the comment block rather than a line range -- several of these ranges
+# had drifted past the end of their header and printed code to whoever asked for help (the same defect engine PR #2258 fixed in scripts/).
+usage() { awk 'NR>1 && /^#/ {sub(/^# ?/,""); print; next} NR>1 {exit}' "$0"; }
+[ $# -ge 2 ] || { usage; exit 2; }
 debs=$1 repo=$2 gnupg=${3:-} keyid=${4:-}
 [ -d "$debs" ] || { echo "mkrepo: no $debs"; exit 2; }
 dist=$repo/dists/stable

os/v2/mkrootfs.sh

@@ -30,7 +30,11 @@
 # The repository goes in at /srv/1bit-apt and apt reads it as file://, so the signed-by chain is the
 # same one https would use: an unsigned or wrongly signed Release file fails the build here.
 set -euo pipefail
-[ $# -ge 2 ] || { sed -n '21,32p' "$0"; exit 2; }
+
+# usage(): the header comment as prose, anchored on the comment block rather than a line range -- several of these ranges
+# had drifted past the end of their header and printed code to whoever asked for help (the same defect engine PR #2258 fixed in scripts/).
+usage() { awk 'NR>1 && /^#/ {sub(/^# ?/,""); print; next} NR>1 {exit}' "$0"; }
+[ $# -ge 2 ] || { usage; exit 2; }
 repo=$(cd "$1" && pwd) rootfs=$2 sshkey=${3:-}
 here=$(cd "$(dirname "$0")" && pwd)
 . "$here/pin.txt"

os/v2/proto.sh

@@ -25,7 +25,11 @@
 # directory to seed the data partition with (so the VM needs no network for Lemonade's backends), and
 # [model.gguf] a small model for the chat row.
 set -euo pipefail
-[ $# -ge 3 ] || { sed -n '21,32p' "$0"; exit 2; }
+
+# usage(): the header comment as prose, anchored on the comment block rather than a line range -- several of these ranges
+# had drifted past the end of their header and printed code to whoever asked for help (the same defect engine PR #2258 fixed in scripts/).
+usage() { awk 'NR>1 && /^#/ {sub(/^# ?/,""); print; next} NR>1 {exit}' "$0"; }
+[ $# -ge 3 ] || { usage; exit 2; }
 w=$1 stage=$2 lemon=$3 backends=${4:-} model=${5:-$HOME/models/Qwen3-0.6B-Q4_K_M.gguf}
 here=$(cd "$(dirname "$0")" && pwd)
 version=v2026.43

os/v2/vmtest-v2.sh

@@ -29,7 +29,11 @@
 #
 # Prints VMTEST-V2 PASS or FAIL.
 set -uo pipefail
-[ $# -ge 2 ] || { sed -n '21,34p' "$0"; exit 2; }
+
+# usage(): the header comment as prose, anchored on the comment block rather than a line range -- several of these ranges
+# had drifted past the end of their header and printed code to whoever asked for help (the same defect engine PR #2258 fixed in scripts/).
+usage() { awk 'NR>1 && /^#/ {sub(/^# ?/,""); print; next} NR>1 {exit}' "$0"; }
+[ $# -ge 2 ] || { usage; exit 2; }
 rootfs=$(cd "$1" && pwd) seed=$(cd "$2" && pwd) key=${3:-}
 # an mmdebstrap rootfs is root-owned with root-only files: populating a filesystem image from it and
 # handing it to qemu needs root, so the whole test runs as root rather than half of it

os/v3/puppy/demo-seq-probe.sh

@@ -43,6 +43,10 @@
 # 1 when any did not, 2 on usage/setup error.
 set -uo pipefail
 
+# usage(): the header comment as prose, anchored on the comment block rather than a line range -- several of these ranges
+# had drifted past the end of their header and printed code to whoever asked for help (the same defect engine PR #2258 fixed in scripts/).
+usage() { awk 'NR>1 && /^#/ {sub(/^# ?/,""); print; next} NR>1 {exit}' "$0"; }
+
 rounds=10
 url=${LEMONADE:-http://1bit-os.local:13305/api/v1}
 npu=${NPU_MODEL:-Qwen3-0.6B-NPU-1bit}
@@ -56,7 +60,7 @@ while [ $# -gt 0 ]; do
     --big) big=${2:?}; shift 2 ;;
     --dmesg) dmesg_file=${2:?}; shift 2 ;;
     --state) state=${2:?}; shift 2 ;;
-    -h | --help) sed -n '28,48p' "$0"; exit 0 ;;
+    -h | --help) usage; exit 0 ;;
     *[!0-9]*) echo "demo-seq-probe: unknown argument: $1" >&2; exit 2 ;;
     *) rounds=$1; shift ;;
     esac