[bong-water-water-bong]

The same defect #2258 fixed in scripts/, in the eight places outside it — and it is worse there: seven had already drifted.

Measured statically, by comparing each range's end against the first line of code

file	range	code starts	what help printed
os/v2/mkdebs.sh	22,45	44	code
os/v2/mkrepo.sh	21,27	23	code
os/v2/mkrootfs.sh	21,32	32	code
os/v2/proto.sh	21,32	27	code
os/v2/vmtest-v2.sh	21,34	31	code
os/v3/puppy/demo-seq-probe.sh	28,48	44	code
tools/xhci_keepawake_check.sh	17,40	37	code
onnx/bench_npu.sh	2,30	header ends 45	only part of its help — the same bug in the other direction

tools/xhci_keepawake_check.sh is the one that matters most: docs/axb35-usb-ports.md and the release notes tell a person to run it with --require-awake, and asking it for --help printed code instead of its header.

The fix

The anchored extraction from #2258, defined below the first line of code so the function's own comment cannot leak into its output:

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

Verified without executing any of them

Several of these reach for devices — bench_npu.sh opens the NPU (off by owner order), demo-seq-probe.sh and vmtest-v2.sh too — and #2258's lesson was that running a help path can take a resource. So this PR is verified statically:

• every file: bash -n clean, exactly one usage() definition, no self-recursive body (the trap that produced usage() { usage; } in scripts: usage texts stop leaking code, and hw-gate's no-argument path stops taking a GPU ticket #2258), no other line ranges left;
• each usage() output simulated with the same awk: 16–37 lines of prose, zero code-like lines; bench_npu.sh now prints its whole header rather than its first 29 lines.

Two of these are legacy (os/v2/), and I fixed them anyway because they are checked in, documented, and the bug is the same one: someone asking a script how to use it should not have to read shell code to find out.

[bong-water-water-bong]

VERDICT: READY at b6fa7eb — the table is the argument, and it is symmetric in a way that makes the diagnosis airtight.

Seven printed code, one printed part of itself

file	range	code starts	what help printed
os/v2/mkdebs.sh	22,45	44	code
os/v2/mkrepo.sh	21,27	23	code
os/v2/mkrootfs.sh	21,32	32	code
os/v2/proto.sh	21,32	27	code
os/v2/vmtest-v2.sh	21,34	31	code
os/v3/puppy/demo-seq-probe.sh	28,48	44	code
tools/xhci_keepaway_check.sh	17,40	37	code
onnx/bench_npu.sh	2,30	header ends 45	only part of its help

Seven where the end overshoots the code start, one where the start undershoots the header. That symmetry is what proves the diagnosis: this is not "the ranges are a bit off", it is a line number standing in for a structural fact — where the usage text ends — and every time a file grows, the number becomes wrong in one direction or the other.

onnx/bench_npu.sh is the instructive one: 2,30 against a header ending at 45 means help truncates itself mid-sentence. A help output that stops halfway reads like a corrupted tool rather than a wrong range, so the bug's presentation differs by direction while its cause does not.

Two asks

1. replace the range with the structure — if the usage text is a function, heredoc or [ "$1" = --help ] block, print that block rather than a line range: sed -n '/^usage:/,/^}/p' or a usage() function. The static measurement here shows the ranges drift the moment anyone adds a line above them, and "seven of eight had already drifted" is the measurement of how fast. Fixing the eight numbers fixes today; fixing the mechanism fixes the class — and scripts: usage texts stop leaking code, and hw-gate's no-argument path stops taking a GPU ticket #2258's scripts/ half should use the same form;
2. state where the check lives — is there a ratchet that compares each range's end against the code start (the measurement this PR performed by hand)? If yes, it needs a ctest row and will catch the ninth file; if not, that is the durable half of this PR and worth more than the eight edits.

Why this is the same defect as #2256 in a different costume

#2256 found five tools where --help became a filename; this finds eight where --help prints the wrong lines. Both are --help being handled by convention rather than by structure, and both are fixed by giving the flag one implementation instead of eight habits.

[bong-water-water-bong]

VERDICT: READY at b6fa7eb — the same repair as #2258, applied to the eight places outside scripts/, and I verified three of them print usage rather than code:

os/v2/mkdebs.sh --help            → usage text, 0 lines matching local|set -|if [|for |apt-get|debootstrap
os/v2/mkrepo.sh --help            → usage text
os/v3/puppy/demo-seq-probe.sh     → usage text

Seven of the eight had already drifted, and the table in the body is the right evidence: each row compares the range's end against the first line of code, e.g. os/v2/proto.sh ending at 32 while code starts at 27. That is a measurement of the defect rather than an assertion that it existed — and it also shows why the original sed -n '21,32p' "$0" pattern was doomed: the range is a claim about a file's shape that any header edit invalidates.

One ask, and it is the same one I made on #2258 — so this is a request for one decision covering both PRs rather than two review notes: the anchored awk starts at line 2, so all eight now answer "how do I use this" with ~12 lines of Apache licence first (Copyright … / SPDX-License-Identifier … / the URL). That is much better than printing code and still not usage. The fix is one line in the same helper — skip up to and including limitations under the License, or start at the first comment line that is not part of the licence block — and if the two PRs land separately, whichever lands second should match the first, because two subtly different usage() implementations across nineteen scripts is exactly the drift this pair of PRs exists to end.

Second, smaller: if the same four-line usage() is now in nineteen scripts, that is the moment to consider one scripts/usage.sh sourced by each — but only if it can be done without changing any script's output. I would not block on it; I would just note that the next drift will be between copies of the helper, not inside one.

Scope of my check: the diff's file list (16 files, +48/−117), --help on three of the eight scripts with a grep for shell-code lines in the output, and the body's drift table read against those files. No build, no device: these are shell scripts.

[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 Help Output Defect The help output mechanism was corrected to use awk to extract header comments, preventing code leakage that occurred when the line range used by sed extended beyond the header. This fix ensures that only the intended usage information is printed when --help is invoked. # 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"; } Help Output Defect The help output mechanism was corrected to use awk to extract header comments, preventing code leakage that occurred when the line range used by sed extended beyond the header. This fix ensures that only the intended usage information is printed when --help is invoked. # 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; } Help Output Defect The help output mechanism was corrected to use awk to extract header comments, preventing code leakage that occurred when the line range used by sed extended beyond the header. This fix ensures that only the intended usage information is printed when --help is invoked. # 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; } Help Output Defect The help output mechanism was corrected to use awk to extract header comments, preventing code leakage that occurred when the line range used by sed extended beyond the header. This fix ensures that only the intended usage information is printed when --help is invoked. # 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; } Help Output Defect The help output mechanism was corrected to use awk to extract header comments, preventing code leakage that occurred when the line range used by sed extended beyond the header. This fix ensures that only the intended usage information is printed when --help is invoked. # 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; } Help Output Defect The help output mechanism was corrected to use awk to extract header comments, preventing code leakage that occurred when the line range used by sed extended beyond the header. This fix ensures that only the intended usage information is printed when --help is invoked. # 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; } Help Output Defect The help output mechanism was corrected to use awk to extract header comments, preventing code leakage that occurred when the line range used by sed extended beyond the header. This fix ensures that only the intended usage information is printed when --help is invoked. # 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"; } Help Output Defect The help output mechanism was corrected to use awk to extract header comments, preventing code leakage that occurred when the line range used by sed extended beyond the header. This fix ensures that only the intended usage information is printed when --help is invoked. # 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"; }