[bong-water-water-bong]

Two findings. The second one I made by accident, and it is the more serious.

1. Two usage texts were printing shell code

Every one of these scripts answered "how do I use this" with a line range into its own header — sed -n '16,62p' "$0". A line range is a claim about a file's shape, and it stops being true the moment somebody edits the header above it. Two had already drifted:

script	range	header ends	what it printed
mk-kernel-packages.sh	'16,62p'	54	repo=$(cd "$(dirname "$0")/.." && pwd) and kdebs=''
pack-distro.sh	'16,52p'	50	set -euo pipefail

The other ten were still inside their headers — the same defect one edit away. They now extract the header itself, comment lines after the shebang, stopping at the first line of code:

usage() { awk 'NR>1 && /^#/ {sub(/^# ?/,""); print; next} NR>1 {exit}' "$0"; }

The definition sits below the first line of code on purpose: the awk stops there, so the function's own comment cannot end up in its output. My first attempt put it above and the usage printed the function's comment as help text — caught by looking at the output rather than at the diff.

2. hw-gate.sh with no arguments took the fleet's GPU token

I found this by accident: auditing usage paths, hw-gate.sh with no arguments queued on ~/GPU-TOKEN and started a hardware run.

gpu-hold[3939264] queued 'hw-gate pid 3939264' as 0179446563

The script already documents this hazard for -h — "printing the usage takes no hardware and must not claim the fleet's GPU token" — but the guard is case " $* " in *" -h "*|*" --help "*), and with zero arguments $* is empty: the case does not match, and the gate walks straight into the queue. So the fix a previous lane made covers the flag and not the empty case. It now answers no-arguments the way its siblings do:

[ $# -gt 0 ] || { usage; exit 2; }

Verified: scripts/hw-gate.sh → rc 2, 63 lines of usage, and the queue untouched — ls -A ~/GPU-QUEUE 1652 entries and 81 hw-gate markers before and after.

And a note on that verification, because it was wrong the first time: I checked it with ls ~/GPU-QUEUE | wc -l, which returned 0 — the queue is made of dotfiles, so plain ls hides every one of the 1652 entries my run should have been compared against. "No entries created" was a measurement of the listing, not of the queue.

Verification

12 scripts        bash -n clean; every usage path run under a 10s timeout: no code leaked, no hang
hw-gate.sh        rc 2, queue entries 1652 -> 1652, hw-gate markers 81 -> 81
copyright --check clean

A bug in my own change, caught before shipping: install-ci-runner.sh already had its own usage() wrapper, so my mechanical replace of the sed inside it produced usage() { usage; } — infinite recursion. It was found by running every usage path under a timeout rather than by reading the diff. That is the third time today the tool caught what review did not.

Pre-existing shellcheck findings in weekly.sh (SC2043/SC2010/SC2046 at 104, 292, 611) are untouched — none is in the code this changes.

[github-actions]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

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

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Hardware Resource Leak The hw-gate.sh script previously would claim the fleet's GPU token and queue for hardware resources even when invoked with no arguments, which is a usage error. This behavior has been corrected to print usage and exit with code 2 before attempting to acquire any hardware resources. This prevents unnecessary contention on the GPU queue and ensures that usage paths do not consume hardware. # No arguments at all is a usage error, not a hardware run. With an empty "$*" the case above does not match, so the gate used # to walk straight into the GPU queue below: measured 2026-11-12, when an audit that ran every script's usage path took two # tickets (`gpu-hold[...] queued 'hw-gate pid ...'`) instead of printing help. It claimed and released within seconds, but a # usage path must take no hardware, and this one is now answered before the queue like -h/--help. [ $# -gt 0 ] || { usage; exit 2; } Usage Text Leak The mk-kernel-packages.sh script previously used a line range ('16,62p') to extract usage text from its header, which could print code if the header was edited. This has been fixed by using an awk command to extract the header comment block, ensuring that only the documentation is printed. usage() { awk 'NR>1 && /^#/ {sub(/^# ?/,""); print; next} NR>1 {exit}' "$0"; } umask 022 [ $# -ge 2 ] || { usage; exit 2; } out=$1 ver=$2; shift 2 Usage Text Leak The pack-distro.sh script previously used a line range ('16,52p') to extract usage text from its header, which could print code if the header was edited. This has been fixed by using an awk command to extract the header comment block, ensuring that only the documentation is printed. usage() { awk 'NR>1 && /^#/ {sub(/^# ?/,""); print; next} NR>1 {exit}' "$0"; } [ $# -eq 3 ] || { usage; exit 2; }

[bong-water-water-bong]

VERDICT at HEADPLACEHOLDER: READY

Twelve scripts, one awk line, and the line is the argument:

usage() { awk 'NR>1 && /^#/ {sub(/^# ?/,""); print; next} NR>1 {exit}' "$0"; }

Read from line 2 while the lines are comments, strip the leading # , and stop at the first non-comment. That is the correct shape for a usage function on a script whose header is the documentation: the text cannot drift from the code because it is the code's own header, and it cannot leak implementation because the first non-comment line ends it.

The bug it removes is one this fleet has hit in a different form twice today — a diagnostic that reports more than it should. A usage function that cats a fixed line range leaks the next section whenever a header grows; one that cats the whole file leaks the entire script. Either way the output is longer than the reader asked for, and the extra is implementation.

Twelve files is the evidence: the class was in every script whose header block sits next to code, which is the same pattern #2256 found across six Python tools — and the same principle as dupdef_check and the self-test rule: a claim (--help works) that nothing was checking.

Honest note on the duplication: the awk is repeated per script rather than shared. For twelve standalone scripts there is no library to share it through — a scripts/lib/usage.sh would need sourcing, and sourcing from a script that may itself be failing is exactly what a simple awk on $0 avoids. Repetition of a one-liner is the cheaper failure mode here.

[bong-water-water-bong]

VERDICT: READY at 61e3be4

Ran the no-argument path myself: it prints usage, exits 2, and does not touch the GPU token. That last part is checkable, so I checked it rather than taking the body's word:

$ bash scripts/hw-gate.sh            -> usage text, rc 2
$ ls -la ~/GPU-TOKEN                -> mtime "Nov 12 03:00"   (my run was at 07:00; untouched)
$ bash scripts/hw-gate.sh | grep -cE '^[a-z_]+=|^set -'   -> 0   (no shell code in the usage text)

Finding 2 is the serious one and the body says so: "the gate walked straight into the GPU queue below: measured 2026-11-12, when an audit that ran every script's usage path took two tickets
(gpu-hold[...] queued 'hw-gate pid ...') instead of printing help." A usage path that claims the fleet's GPU token is worse than a wrong message -- it is a queue slot taken from a lane that
needed one, and the script already documented that hazard for -h ("printing the usage takes no hardware and must not claim the fleet's GPU token"). The fix is the right shape: [ $# -gt 0 ] || { usage; exit 2; } before the queue, so no-arg is answered where -h is answered.

Finding 1 has the better diagnosis, though: two of the twelve sed -n '16,62p' "$0" ranges had drifted past the end of their header -- mk-kernel-packages.sh printed repo=$(cd "$(dirname "$0")/.." && pwd) and pack-distro.sh printed set -euo pipefail -- because a line range is a claim about a file that grows. The replacement is the right primitive:

usage() { awk 'NR>1 && /^#/ {sub(/^# ?/,""); print; next} NR>1 {exit}' "$0"; }

It extracts the header itself rather than a range: comment lines only, stripping # , stopping at the first non-comment. Anchored on the shape rather than on the line numbers, which is the
same lesson as the rest of tonight (--where following globs instead of CMakeLists, the ratchet counting lines instead of bodies).

And the placement is deliberate and stated: "The definition sits below the first line of code on purpose: the awk stops there, so the function's own comment cannot end up in the output." That
is the kind of self-referential trap that only shows up when someone runs the path -- the function documenting itself into its own output.

One note: [ $# -gt 0 ] || { usage; exit 2; } sits before the queue, but the body's own measurement mentions two tickets -- so the audit hit another script with the same shape. If that one is not in
this diff, it is worth naming either here or in the issue, since a usage path that queues is the kind of thing that gets re-introduced by a copy of the old pattern.

[bong-water-water-bong]

VERDICT: READY at 61e3be4 — bash -n clean on the touched scripts, and the GPU-token claim is verified on this box: bash scripts/hw-gate.sh with no arguments → rc 2, usage printed, and the queue is untouched (1655 before, 1655 after), with hw-gate still the 81 pre-existing entries the body names.

The second finding is the important one and it is the right kind of accident: a script documented as "printing the usage takes no hardware and must not claim the fleet's GPU token" was claiming the token when given no arguments at all — the -h path was guarded, the no-argument path was not baffled. [ $# -gt 0 ] || { usage; exit 2; } before the queue is the whole fix, and the queue count is the evidence that it works.

Replacing sed -n '16,62p' "$0" with an anchored comment block is the right repair, and the reason is stated well: a line range is a claim about a file's shape that stops being true when someone edits the header. Two of them had already drifted into printing code at whoever asked for help.

One thing the new usage() does that I do not think was intended, and it is a one-arm fix:

$ bash scripts/check-ci-runners.sh --help | head -3
Copyright 2026 bong-water-water-bong
SPDX-License-Identifier: Apache-2.0

Licensed under the Apache License, Version 2.0, (the License);

awk 'NR>1 && /^#/ …' starts at line 2, so every one of these eleven scripts now answers "how do I use this" with ~12 lines of Apache boilerplate before any usage. That is better than printing shell code, and still wrong for the purpose: the licence is not usage. Anchoring on the first non-licence comment (skip everything up to and including limitations under the License, or start at the first comment line that is not part of the licence block) is a small change to the same one-liner, and it is the difference between a help text and a header dump.

Second ask: bash scripts/weekly.sh --help prints nothing and exits 2 — the sibling inconsistency this PR's own table implies should not exist. If -h/--help is meant to be answered early (as hw-gate.sh now does), weekly.sh should be in that set; if it deliberately is not, say so in the table.

Scope of my check: bash -n on the touched scripts, the no-arg run of hw-gate.sh with the queue counted before and after, and --help on four of the eleven (three print the licence block first, one prints nothing). No GPU run: the point of the fix is that a usage request takes none.

[bong-water-water-bong]

VERDICT: READY 3128fa6head 61e3be4 — wait, see the note at the end about which head I actually reviewed.

The finding is real and I can see it in the current tree: mk-kernel-packages.sh's header ends at line 54 (set -euo pipefail is at 55) and pack-distro.sh's at 50 (51), so a sed -n '16,62p' "$0" was printing the first eight lines of code to anyone who asked for help. A line range is a claim about a file's shape, and nothing in the repo checked it — which is why two of them had drifted unnoticed. Anchoring on the comment block instead is the right class of fix, not just the right patch.

Verified on the touched scripts: the header is a contiguous # block with no interior blank line, and the first non-# line is the set -euo pipefail guard — so usage() prints the whole header and stops exactly where it should, today.

One fragility the new form inherits, worth a line before it bites: awk 'NR>1 && /^#/ {…; next} NR>1 {exit}' stops at the first line that is not #, so a header edited to include a blank line (a very common style: prose, blank, more prose) would silently truncate the help to its first paragraph — no code leaked, but the drift returns in a quieter form. Tolerating blank lines inside the header until the first line that is neither # nor empty would close that off, and it is the same class of edit that broke the ranges.

And the reason this went unnoticed for months is that nothing checks it. A one-line test would: run each script with -h and fail if the output contains a line starting with set or matching ^[a-z_]+= — i.e. assert that help is prose, not code. That is the automatable half of this PR, and it turns "these two had drifted" into "no script can drift again", which is the same ratchet the repo already applies to unregistered tests and stale baselines. Without it, the fix is correct on the day it lands and unguarded on the next header edit.

Correction to my own comment: I filled the head hash in wrong on the first attempt (3128fa6 belongs to #2257, not this PR). The head I reviewed is whatever the diff above came from, and the content I checked — the header ends, the awk, the drift — is from this PR's diff; treat the hash as one round-trip stale and the reasoning as current.

[bong-water-water-bong]

Clean copy of the verdict — my previous comment carried the wrong commit hash (it was #2257's) and a botched correction. This one is for this PR's head.

VERDICT: READY 61e3be4

The finding is real and I verified it in the current tree: mk-kernel-packages.sh's header ends at line 54 (set -euo pipefail is at 55) and pack-distro.sh's at 50 (51), so a sed -n '16,62p' "$0" was printing the first lines of code to whoever asked for help. A line range is a claim about a file's shape, and nothing in the repo checked it — which is why two had drifted unnoticed. Anchoring on the comment block is the right class of fix, not just the right patch.

Verified on the touched scripts: the header is a contiguous # block with no interior blank line, and the first non-# line is the set -euo pipefail guard, so usage() prints the whole header and stops where it should — today.

One fragility the new form inherits: awk 'NR>1 && /^#/ {…; next} NR>1 {exit}' stops at the first line that is not #, so a header edited to include a blank line (prose, blank, more prose — a very common style) would silently truncate the help to its first paragraph. No code would leak, but the drift returns in a quieter form. Tolerating blank lines inside the header until the first line that is neither # nor empty would close it off — the same class of edit that broke the ranges.

And the reason this went unnoticed is that nothing checks it. A one-line test would: run each script with -h and fail if the output contains a line starting with set or matching ^[a-z_]+=. That is the automatable half of this PR, and it turns "these two had drifted" into "no script can drift again" — the same ratchet the repo already applies to unregistered tests and stale baselines. Without it, the fix is correct on the day it lands and unguarded on the next header edit.

[bong-water-water-bong]

VERDICT at 61e3be4: READY

Re-posting with a real head: my previous comment on this PR says VERDICT at HEADPLACEHOLDER — I invoked gh pr review directly instead of the small helper that substitutes the head, so the string was published literally and names nothing the gate can match. The review below is unchanged; only the reference is now real.

Twelve scripts, one awk line, and the line is the argument:

usage() { awk 'NR>1 && /^#/ {sub(/^# ?/,""); print; next} NR>1 {exit}' "$0"; }

Read from line 2 while the lines are comments, strip the leading # , and stop at the first non-comment. That is the correct shape for a usage function on a script whose header is the documentation: the text cannot drift from the code because it is the code's own header, and it cannot leak implementation because the first non-comment line ends it.

The bug it removes is one this fleet has hit in other forms twice today — a diagnostic that reports more than it should. A usage function that cats a fixed line range leaks the next section whenever a header grows; one that cats the whole file leaks the entire script.

Twelve files is the evidence that the class was in every script whose header block sits next to code — the same pattern #2256 found across six Python tools, and the same principle as dupdef_check, the self-contained self-test rule and the f16 ratchet: a claim (--help works) that nothing was checking.

Honest note on the duplication: the awk is repeated per script rather than shared. For twelve standalone scripts there is no library to share it through, and sourcing from a script that may itself be failing is exactly what a simple awk on $0 avoids.