usenet-drain-walk: a busy host is not a stuck drain

[leonardoazeredo]

What was wrong

A real 12-pass run of scripts/usenet-drain-walk.sh on 2026-09-22 logged 4 of its 12 passes as "no progress" — and every one of those four was a pass the I/O pressure gate refused before it started. Not one of them ran. Two more refusals and the walk would have stopped printing 4 passes in a row made no progress: a sentence about a drain that stopped moving, printed for passes that never happened, and the first line an operator reads.

The gate prints [pressure-gate] on four paths and refuses on one. The other three say this pass runs unprotected and then run the pass normally — so the walk's detection (a bare prefix match) classified a pass that ran as one that never started.

The change

• The refusal is its own counter. REFUSED (consecutive, reset by any admitted pass) no longer writes BARREN. A pass the gate refused says nothing about whether the drain is moving.
• It has its own bound and reason. --max-skipped (default 6 — six skip-cooldowns, half an hour of a host too busy to start a pass) stops the walk saying the I/O pressure gate refused N passes in a row (the host was too busy to start one), instead of borrowing the barren sentence.
• The summary counts them. passes run: 12 (4 refused by the pressure gate, 0 in a row with no progress at the end) — the line that would have made that run readable without cross-referencing the pass log by hand.
• The detection matches the refusal's own phrase, and a test drives the real usenet-blackhole.sh through both gate states (refused, and "runs unprotected"), because a stub hardcodes the phrase and cannot keep it honest.
• The final refusal no longer sleeps. It logged waiting 300s before the next attempt and slept it, although the bound guarantees no next attempt.
• Also fixes a shipped --help truncation found on the way: the range stopped three lines short of the header, so the operator's own --help was missing the Prerequisites line and the warning beneath it. A test now derives the last header line from the file, so it cannot fall behind again.

Verification

• The walk's own suite: 25 tests, all green. The mutation corpus reports killed 8 / 8, survived 0 — five new entries registering the guards this branch adds, each with a named test that goes red under it.
• On the NAS at this HEAD, with the gate forced closed by PSI_IO_LIMIT=0 (no TorBox call, no download): the new refusal lines, the new stop reason, passes run: 2 (2 refused by the pressure gate, 0 in a row with no progress at the end), exit 3, and 2 refusals with 1 wait — the final one going straight to the stop. --help prints the whole header; usenet-blackhole.timer is still inactive.
• Local full-suite caveat, stated rather than buried: ./tests/run-tests.sh reports executed=1112 failed=28 on this macOS host. Running the same six files on main fails the identical 28 test names — zero introduced, zero masked. They are host artifacts (ssh blocked by the sandbox, no docker compose CLI, no PyYAML, BSD sed, not on VLAN20). CI is the suite run to judge.

Notes

• CLAUDE.md's rule that every code change is NAS-tested before main is met: synced and verified at 0250a1b, and the NAS goes back to main when this lands.
• The plan (docs/superpowers/plans/2026-09-22-drain-walk-gate-refusals.md) travelled with the work, including three in-place corrections made when its own reviews disproved what it prescribed.
• One known gap, ledgered: the streak-reset guard (REFUSED=0) has no test that fails if it is removed, so its killability is unproven. The shipped behaviour is correct; the evidence is not there yet.