test(e2e): no unit row drives the apt-prereq retry loop — the seam exists, the file budget does not (#442)

[VijitSingh97]

What is missing

tests/e2e/in-container.sh's apt-prereq retry loop (#442, PR #448) has no unit row. Its
_apt_failure_reason classifier is covered; the loop that calls it — bound, backoff, break-on-success,
and the abort text — is proven only by reading.

Why it was not landed with #442

Not because the harness cannot drive it. The non-author review on PR #448 established that it can, and
I had disclosed the opposite; that disclosure is retracted on the PR. Both instruments already exist:

• tests/run.sh:186 — make_stubs already writes a fake apt-get into the PATH-first stub dir.
• tests/run.sh:3386 — sleep() { :; } # drop the retry delay, the status prints a spurious '[ERROR] rigforge aborted' to stderr when the worker API is unreachable (exit code is still 0) #364 sampling driver, is the
  same shape of problem already solved.
• The loop needed to be a function rather than top-level code. PR fix(ci): retry the e2e apt prereqs, and stop the abort blaming the network (#442) #448 does that: it is
  _apt_prereqs(), above the E2E_LIB_ONLY guard, so a sourced harness can call it. That half is done
  and cost nothing — docs/dev/file-budget.tsv has no row for in-container.sh.

What stopped it is the file budget. tests/run.sh sits at its recorded ceiling of 9795
(docs/dev/file-budget.tsv:7). The smallest honest set of rows was drafted and measured at +36
lines: a failing-archive PATH stub (9), a child-bash driver (6), an invoke helper (5), three
invocations, six assertions and four comment lines. Paying for 36 lines means compressing ~36 lines of
rationale across roughly five unrelated comment blocks in a 9,795-line file — a wide edit whose own
risk of falsifying a claim is larger than the risk it removes, on harness code a reviewer has read line
by line. That is a deliberate deferral, not an oversight.

The recipe

Wrap it as one block driven by a separate bash process (the tests/run.sh:3386 pattern):

• a PATH stub apt-get that fails update for the first $APT_FAIL_FOR attempts and appends one line
  per attempt to a log, so the bound is read off a count rather than off the loop's own report;
• a driver that defines sleep() { :; }, sources in-container.sh with E2E_LIB_ONLY=1, calls
  _apt_prereqs, and prints OK|ABORT attempts=N;
• rows for: a first-try success is never retried (OK attempts=1); a mirror that clears on the next try
  is retried, not aborted (OK attempts=2); a dead archive spends every attempt then aborts
  (ABORT attempts=3); the retry notice names the attempt (attempt 1/3); the abort names the mirror
  mid-sync; and — guarded against a vacuous pass by the row above matching the same blob — that it never
  says no network / archive down again.

Prerequisite

Headroom in tests/run.sh, i.e. a real compression pass or a suite split. Ceilings only go down, so the
lines have to come from somewhere in that file first.

---

The prerequisite above is cheaper than it sounds (from the #448 re-review, reviewer-20260905T182040Z.md)

The "needs headroom in tests/run.sh" framing assumes the rows have to live in tests/run.sh. They
do not.

scripts/lint-file-budget.sh rule 1: a file under the 400-line target drops its budget entry
entirely. So lifting the existing five lines at tests/run.sh:9388-9392 into a small file under
tests/ and replacing them with a single source takes tests/run.sh down by four, and the new
file — the five lifted lines plus the ~19 the rows actually need — carries no budget row at all.

That turns this issue's prerequisite from "a compression pass through a 9,795-line file" into one
line of plumbing.

Two things to keep honest when doing it:

• The row set is ~19 lines, not the +36 this issue quotes. The reviewer drafted and ran it: 7
  passed against the real loop, 4 passed / 3 failed against a seeded mutation (bound 3→5, backoff
  5→7, both proved applied). My +36 was an honest measurement of a heredoc-style draft and a
  convenient number to quote as the price; printf one-liners carry the same content in half.
  My published itemisation also summed to 33, not 36 — corrected on PR fix(ci): retry the e2e apt prereqs, and stop the abort blaming the network (#442) #448.
• A new suite-composition pattern is a real change, not a refactor. It was deliberately kept out
  of PR fix(ci): retry the e2e apt prereqs, and stop the abort blaming the network (#442) #448 because introducing one in a CI fix during a live release gate is the widening that PR
  declined on purpose. Do it here, on its own, where it can be reviewed as what it is.

---

Worker brief (inventory 2026-09-13)

Acceptance criteria

• A unit row drives tests/e2e/in-container.sh's apt-prereq retry loop itself — not just its _apt_failure_reason classifier, which is already covered.
• Four behaviours are asserted, per the issue: the retry bound, the backoff, break-on-success, and the abort text.
• The row can fail: break the loop deliberately and confirm the test catches it.
• The file budget is updated if the new test file crosses it — the issue notes "the seam exists, the file budget does not", so expect scripts/lint-file-budget.sh to need a deliberate baseline edit. See scripts/lint-file-budget.sh is trusted not to rewrite its own baseline, but nothing asserts it #444, which is about that baseline being trusted without assertion.

What the issue already settled for you

The non-author review on PR #448 established the harness can drive this, and the author's opposite disclosure is retracted on that PR. Both instruments already exist:

• tests/run.sh:186 — make_stubs already writes a fake apt-get into the PATH-first stub dir.
• The seam referenced from tests/run.sh in the issue body.

So this is not a design question. Do not re-derive whether it is possible.

Scope

In: tests/e2e/in-container.sh's retry loop and its new unit row; docs/dev/file-budget.tsv if the budget moves.
Out: the apt retry behaviour itself (#442 / PR #448 landed it), and the file-budget gate's own self-assertion (#444).

The tier that proves it

rigforge tier 1 / the unit suite. No bench job.

Related

• CI: the e2e appliance leg has no apt retry, and its abort message blames the network for a mirror mid-sync #442 / PR fix(ci): retry the e2e apt prereqs, and stop the abort blaming the network (#442) #448 — the loop this covers.
• scripts/lint-file-budget.sh is trusted not to rewrite its own baseline, but nothing asserts it #444 — the file-budget baseline; separately pinned, and you will touch its baseline.

[pithead-developer]

Questions before work continues (answer here, then remove the question label):

Review of PR #498 did not pass after round 2 (RETURN).

Issue #449 requires a dependency-free row that directly proves the three-attempt bound, 5s/10s backoff, break-on-success, corrected abort text, mutation firing, and file-budget compliance. The diff meets those technical criteria, all nine current-head GitHub checks passed, and independent mutations fired. RETURN because PR head cd41b8f2… postdates successful quoted bench jobs 136/139, and the intervening merge contains executable tier-1 self-test changes—not a docs-only delta.

• [return] gh pr view 498 --repo p2pool-starter-stack/rigforge --json headRefOid,body; git diff --name-status HEAD^1..HEAD: Current head is cd41b8f2…, but the PR presents jobs 136/139 at 8e31a115… as final subject evidence. The intervening merge changes scripts/lint-file-budget-selftest.sh, which is exercised by the quoted lint tier, so the older jobs do not cover the head. Remove the unnecessary stale subject-job citations or replace them with evidence run at the current head.
• [note] bench-ci status 127; bench-ci status 137: Both expected mutation jobs correctly conclude failure with exit 2, but their run step is incorrectly reported as successful. This remains tracked in p2pool-starter-stack/bench-ci#23.
• [note] Graphify health diagnostic command: The auxiliary graph reported dangling, self-loop, and collapsed edges; no verdict-critical conclusion relies on it.

[VijitSingh97]

Drop the stale bench-job citations from the PR body; do not rerun tiers 1 to 3 on the bench. GitHub Actions runs them for every push now, and the nine green checks at the current head are that evidence: cite them (gh pr checks at the head SHA) in the Verification section and report done.

[pithead-developer]

Merged in #498.