test(testing): retry_etxtbsy helper to kill linux CI stub-exec flake (hew-0rky)

[droidnoob]

Closes hew-0rky — kills the install_executable_stub ETXTBSY flake on Linux CI.

Background

The 2026-05-29 PR #58 CI run failed install_overwrites_an_existing_stub with ExecutableFileBusy on ubuntu-latest / stable only (the other 3 test matrices passed). This is the documented GOTCHA:linux-etxtbsy-stub race: the kernel's i_writecount can briefly report a freshly-written stub as exec-busy even after fs::rename + parent-dir fsync, because the writer fd's close hasn't fully propagated through the inode's busy-counter.

GOTCHA:flaky-pre-commit notes this should be "retry once, investigate twice." It hit twice this week. Investigated.

Fix

Add a retry_etxtbsy helper in hew-core/src/testing.rs and wrap the 4 in-module stub-exec tests with it. Up to 5 attempts with 10ms sleeps between retries; non-ETXTBSY io errors propagate unchanged.

pub fn retry_etxtbsy<T>(
    attempts: u32,
    mut f: impl FnMut() -> io::Result<T>,
) -> io::Result<T> {
    for attempt in 0..attempts {
        match f() {
            Ok(v) => return Ok(v),
            Err(e) if e.raw_os_error() == Some(libc::ETXTBSY) && attempt + 1 < attempts => {
                std::thread::sleep(std::time::Duration::from_millis(10));
            }
            Err(e) => return Err(e),
        }
    }
    unreachable!()
}

Why test-call-site retry, not helper-internal exec-verify

Two options were considered (documented in hew-0rky's task body):

• Option A: install_executable_stub exec-verifies the file with /bin/true before returning. ~50ms amortized across every stub install in the suite (~5s total in our suite). Also gives false confidence — the verify exec doesn't match the test's actual exec.
• Option B (this PR): retry_etxtbsy helper that test callers wrap around their own Command::new(stub).output(). Zero amortized cost when ETXTBSY doesn't fire; explicit at the call site so the reader sees the retry pattern.

Option B selected per the task body's recommendation.

Tests

• retry_etxtbsy_succeeds_on_first_call_when_no_busy
• retry_etxtbsy_eventually_succeeds_when_busy_clears (fake returns ETXTBSY twice then Ok)
• retry_etxtbsy_propagates_other_io_errors (PermissionDenied not retried)
• retry_etxtbsy_gives_up_after_attempts_with_last_etxtbsy

Memory update

GOTCHA:linux-etxtbsy-stub reads "rare race; retry if happens once, investigate if twice." After this lands, the note will be updated to point at the retry_etxtbsy helper as the canonical mitigation. (Update happens at PR merge, not in this branch — keeps the helper change atomic from the doc change.)

Out of scope

• Switching install_executable_stub to posix_spawn with explicit busy-handling flags. Heavier and the retry approach is empirically sufficient.
• Auditing every test in every workspace crate for similar exec-after-install patterns. This PR covers hew-core::testing; if RealGit::at(...) tests or install.rs integration tests also trip, follow-up.

🤖 Generated with Claude Code