docs(ci): propose runner archive cache for Debian download failures - #4086

Summary

Debian packaging failed before any workflow step when runner 2.337.0 received a codeload 404 for an existing pinned action. Document the verified boundary and propose the runner's existing action-archive cache, populated with bounded retries in a trusted image build. This is a draft runner configuration proposal, not an activated repository fix; runner-admin review, rollout, and fault-injection validation remain required.

Related Issue

Closes #4085 (scoped investigation and proposal task). Related testing tracker #3954 remains open; fleet rollout and proof of prevention are outside this task's closure scope.

Changes

• Link contributor CI guidance to a concrete Linux runner cache layout and process environment configuration for the unchanged actions/download-artifact pin.
• Provide an image-build recipe with at most three transfer attempts, per-transfer/connect timeouts, a retry-start budget, structural archive validation, atomic publication, and first-failure log retention.
• Explain cache ownership/provenance, fallback behavior, rollout/rollback, remaining GitHub resolution dependency, and the required disposable-runner tests before deployment.
• Preserve the original attempt-1 failure separately from later validation. Compare same-pin successful Debian packaging on the same runner version/image. The failing Debian workflow is unchanged between these runs.

Runner source maps the error to HTTP 404, which bypasses its existing three-attempt download loop. There is no verified setting to enable 404 retries; packaging-step/action-body retries cannot intercept preparation. The pin exists and its archive downloaded successfully during investigation, but the cause and repeatability of the original 404 remain unproven. NVIDIA fleet documentation requires SSO and fleet configuration was not accessible. No action unpinning, transport replacement, broad job/Cargo/test retries, CI gate changes, or deployment is included.

Testing

• Relevant Markdown, Bash syntax, ShellCheck, and diff checks pass.
• Exact recipe tested with real curl 8.7.1 and loopback HTTP fixtures (only URL origin/cache path changed): first success, 404 then success, three permanent 404s, failed refill preserves existing entry, malformed archive, and valid archive missing required members. Confirmed request ceiling, final nonzero exits, retained first-failure diagnostics, staging cleanup, and successful mode 0444.
• Exact public action archive downloaded and required members confirmed; this does not reproduce the original runner failure.
• Debian amd64/arm64 and downstream E2E validated on the final PR SHA with matching artifacts: manual Branch E2E run 36935159082, head 7a16a9e8cffbfccf3a41caf064a331c4254918da (in progress).
• Fleet cache activation, permissions, injected codeload 404/cache hit, cache miss/unreadable/corrupt archive, and permanent uncached failure tests (runner-admin dependency).

plans/debian-download.md and preserved logs contain local investigation details. Green ordinary CI will be recorded as baseline validation and will not be described as proof that archive retries or the proposed runner cache were exercised.

The configured repository pre-commit hook also passed its formatting/lint checks (Rust workspace/examples, Python, Helm, proto, TypeScript, license and Markdown). GitHub verified the signed commit. copy-pr-bot disables automatic mirroring for drafts in this repository, so the manual run is the actual validation evidence; E2E gate statuses skipped for absent labels are not counted as tests. The draft remains draft.

Checklist

• Follows Conventional Commits.
• Commits are signed off (DCO).
• Related diagnostic skills reviewed using the maintenance map; no existing commands/workflow relationships change.
• Runner-admin review and rollout validation complete.