ci: a cached link timeout is reported as an error, defeating --accept-timeouts

[wallstop]

Problem

The Probe external link liveness step in ci.yml passes --accept-timeouts=true, and the job's own step summary states the intent plainly:

Bot-detection, throttling, transient responses, and timeouts are accepted by this gate; do not add per-domain excludes for those cases.

That intent does not hold for a URL that appears more than once. When lychee times out on a URL and then reuses that result for a later occurrence of the same URL, the reused entry is reported as a generic error rather than a timeout, so --accept-timeouts=true does not cover it and the job exits 2.

Evidence

Run 30610933921, job Lint docs links, on PR #320. The PR changed only scripts/__tests__/test-editor-provisioning-heartbeat.ps1 and a progress/ markdown file; neither links to openupm.com.

Final summary line:

1714 Total (in 3m 43s 247ms)  581 Unique  153 OK  1 Error  1554 Excluded  6 Timeouts  15 Redirects

Six timeouts were accepted. The single error that failed the gate was the same host, and specifically a cached result:

[docs/getting-started/install.md]:
[TIMEOUT] https://openupm.com/packages/com.wallstop-studios.dxmessaging/ (at 20:47) | Request timed out
[TIMEOUT] https://openupm.com/packages/com.wallstop-studios.dxmessaging/ (at 33:51) | Request timed out

[README.md]:
[ERROR] https://openupm.com/packages/com.wallstop-studios.dxmessaging/ (at 15:1) | Error (cached)

The identical URL is a TIMEOUT at its first two occurrences and an ERROR at its third. Same host, same cause, same run; the classification differs only by cache hit, and only the cached one is fatal.

The earlier offline pass in the same job reported 0 Errors, so nothing internal was wrong.

Impact

Any PR can be turned red by a slow external host, regardless of what it changed, and the failure is a required check (Lint docs links feeds CI Success). The current remedy is a manual re-run, which is exactly the flake-tolerating loop the repository's testing policy rejects. It also trains reviewers to re-run a red required check without reading it, which is worse than the flake.

Constraints on any fix

• Do not add a per-domain exclude for openupm.com. .lychee.toml says so explicitly, and it would hide a genuinely dead link later.
• accept takes status codes, so it cannot express this case.
• The scheduled advisory scan deliberately shares .lychee.toml without accept_timeouts, so any change must keep the advisory scan reporting timeouts while the blocking gate keeps ignoring them.

Candidate approaches

1. Retry the external probe step once before failing, in the step's own shell. A second attempt repopulates the cache from a fresh request, so a transient host outage stops being fatal without weakening what the gate detects. Costs one extra pass on an already-failing run only.
2. Raise timeout and max_retries in .lychee.toml (currently 20 s and 2). This reduces how often a host times out at all, but does not fix the misclassification, so a slow-enough host still produces a fatal cached error.
3. Check whether lychee v0.24.2 preserves timeout status through its cache in a newer release, and bump the pinned version if so. This is the only option that fixes the cause rather than the symptom.

Option 3 first; option 1 if upstream still reclassifies.

Reproduction

Not deterministic on demand, since it needs the external host to be slow. It requires only that a URL time out once and appear at least twice across the checked docs, which https://openupm.com/packages/com.wallstop-studios.dxmessaging/ does (README.md plus docs/getting-started/install.md).

[wallstop]

Second occurrence, different host, different cause -- and it hit master

Run 30613636402 on master (69af9d14) failed Lint docs links about 50 minutes after the run in the description:

[ERROR] https://www.shellcheck.net/ (at 105:5) | Connection failed. Check network connectivity and firewall settings
1714 Total (in 12s 32ms)  581 Unique  159 OK  1 Error  1554 Excluded  16 Redirects

That is a connection failure rather than a cached timeout, so --accept-timeouts=true would not have covered it even if the classification were correct. The offline pass again reported 0 Errors, and the merged commit added editor test files -- no link, doc page, or .lychee.toml change.

So the problem is broader than this issue's title. The gate asks third-party websites whether they are up and fails the build on the first bad answer, which makes any transient internet condition a red required check on an unrelated commit.

#325 addresses that broader failure mode by running the external probe twice, 30 seconds apart, and failing only if both attempts fail.

This issue stays open, because #325 does not fix what it describes. A cached timeout is still reclassified as a generic error, and --accept-timeouts=true is still defeated for any URL that appears more than once. The retry makes that survivable, not correct. The candidate fix in the description -- checking whether a lychee release after v0.24.2 preserves timeout status through its cache, and bumping the pin if so -- is still the one that addresses the cause.

[wallstop]

PR #325 (merged 7eac8f53) implemented candidate approach 1: the external probe now runs twice, 30 seconds apart, and fails only if both attempts fail.

That makes the reported symptom non-fatal, but it does not remove the cause. lychee still classifies a reused cache entry for a timed-out URL as a generic error rather than a timeout, so --accept-timeouts=true still does not cover it -- the retry just gives the cache a second chance to be populated from a fresh request.

Leaving this open to track the classification behavior itself. Whether that is worth pursuing upstream or is now adequately mitigated is a judgement call; if the retry has held for a while with no recurrence, closing as mitigated is reasonable.

[wallstop]

Reproduction attempt against the pinned version: the misclassification does not reproduce

Option 3 ("check whether a newer lychee preserves timeout status through its cache, and bump if so") is the option this issue asks for first. Two findings, both checkable.

1. There is no newer version to bump to

lychee-v0.24.2 (2026-05-01) is the latest stable release. The only newer tag is the rolling nightly, which is not a pin candidate. So option 3 is unavailable today regardless of whether upstream fixed anything.

$ gh api repos/lycheeverse/lychee/releases --jq '.[0:4][] | .tag_name'
nightly
lychee-v0.24.2
lychee-lib-v0.24.2
lychee-v0.24.1

2. A duplicated timing-out URL keeps TIMEOUT on every occurrence in v0.24.2

Ran the actual pinned binary against a URL repeated across three files, for both kinds of timeout:

Connection timeout (unroutable 10.255.255.1) and response timeout (a local socket that completes the handshake and never replies) both give:

🔍 3 Total  🔗 1 Unique  ✅ 0 OK  🚫 0 Errors  ⏳ 3 Timeouts

Three occurrences, one unique request, three TIMEOUT classifications -- the reused result kept its status. Adding --accept-timeouts=true takes the same run from exit 2 to exit 0, covering all three.

So on the pinned version, a plain repeated timeout does not become Error (cached), and --accept-timeouts is not defeated by the reuse. Whatever produced the [ERROR] ... | Error (cached) line in run 30610933921 is something narrower than "lychee reclassifies a cached timeout" -- most likely a network-level failure (connection reset / TLS abort) against the real host that lychee stores as Error rather than Timeout, which --accept-timeouts is not meant to cover and accept cannot express. Upstream #2190 is the closed issue in that area.

What this means for the fix already shipped

.lychee.toml sets no cache, so lychee's disk cache is off and the reuse is per-process. The retry added in #325 therefore starts from a clean slate and genuinely re-probes the host -- it is not re-reading a poisoned cache entry. That makes it effective against the transient case, which is the case that was actually turning PRs red.

Recommendation

Keep #325's retry as the fix and close this issue, rather than pursuing a version bump that does not exist or a config change that cannot express the condition. Reopen with a fresh log if a Error (cached) line survives both attempts -- that log would show the underlying status and finally identify the real classification, which the current evidence cannot.