[SaladDay]

What

oac install explains Docker, permission, lock, pull and download failures in one line with the next step:

• Docker checks report Docker's own reason from stderr only, with no exit status 1 and no stray / from the empty {{.OSType}}/{{.Architecture}} template.
  • Socket permission denied: This account cannot use Docker: add it to the docker group and log in again, or use Docker Desktop or rootless Docker. Do not run the installer with sudo.
  • No docker binary: says to install Docker Engine 26+ with the Compose plugin, or Docker Desktop.
  • Daemon unreachable: Docker is not running or not reachable; start it and rerun the installer: <Docker's reason>.
  • Compose missing or too old: says to install or update the plugin. Engine too old: says to update Docker.
• Permission errors on ~/.oac, <dir>, <dir>.lock or <dir>.staging print one message. It names the blocked path and gives sudo chown -R "$(id -un)" <paths>. The path is the deepest one this account can still see, so a root-owned ~/.oac is named rather than the ~/.oac/core below it. For the installation's own paths, the command covers every one that exists, so one chown fixes a whole sudo run. Paths outside the home directory are never suggested for a recursive chown. Windows names the path only. oac apply and rotate-core-key get the same message through withLock.
• Lock busy: Another oac command is running on this installation; wait for it to finish and retry. The errno text is gone.
• Image pull failure names the image and Docker's reason. It then says pulls go through the Docker daemon, which does not use the shell's proxy, and points to the daemon proxy, a registry mirror or the offline archive (Offline hosts in the installation options).
• Release downloads (downloadAsset) retry network errors, 429 and 5xx up to 3 attempts with backoff (1 s, 2 s). Each attempt keeps its 2-minute timeout. The final error is download <file>: <cause>; check the network or HTTPS_PROXY and rerun, and it does not repeat the whole URL.
• Docs (EN + zh):
  • install.md prerequisites cover the docker group, rootless Docker, never running with sudo, and the Docker daemon's own proxy.
  • install-options.md#offline-hosts replaces "installation requires GitHub and registries" with the daemon proxy and mirror, plus the release's oac-<commit>-linux-amd64-offline.tar.gz and its install.py.
  • The operations.md troubleshooting table gets rows for Docker access, sudo leftovers and pull failures, and an updated Compose row.

Why

Installer polish lane B1. Audit findings (audit-core.md) 4, 3c (message part), 2 (the oac download part), P2-a and P2-m; mx probes 1 and 3. Users without Docker access got a raw exit status 1 plus /, so they retried with sudo. That left root-owned ~/.oac/*, and every later run then failed with a raw permission denied.

No new setting, flag, route or command. downloadRetryDelay is a package variable so tests can skip the backoff.

Verification

• go test -count=1 ./services/core/cmd/oac/: pass. New acceptance tests:
  • TestInstallExplainsDockerFailures: the five Docker or pull failures give the exact message and leave no directory or stage.
  • TestDownloadRetriesTransientFailures: a dropped connection, then a 503, then success; a persistent 503 gives the final message after 3 attempts.
  • TestInstallExplainsPathsAnotherAccountOwns (unix): an unreadable parent or lock gives the exact message and creates no directory.
  • TestInstallRejectsBusyPortAndLock: now asserts the lock-busy message.
• go vet ./... passes. GOOS=windows and GOOS=darwin go vet ./services/core/cmd/oac/ pass.
• Live run on this host with the built oac:
  • A DOCKER_HOST socket with mode 000 gives the access message.
  • A missing socket gives the not-running message with Docker's reason.
  • An empty PATH gives the not-installed message.
  • Root-owned ~/.oac and root-owned core+core.lock were created through a container. The installer printed the expected path and chown command. After the chown it proceeded to downloading.
  • HTTPS_PROXY=http://127.0.0.1:1 gives download compose-sha256sums.txt: proxyconnect tcp: dial tcp 127.0.0.1:1: connect: connection refused; check the network or HTTPS_PROXY and rerun after the retries.
• node --test website/tests/translations.test.mjs: 3/3 pass (website deps installed).
• python3 scripts/check-names.py: pass. python3 scripts/core-distribution-manifest.test.py BundledDocsTests: pass.

Skipped

• Full make check, per the focused-checks rule.
• The website build tests (dist.test.mjs), which need a site build; CI's website job covers them.
• A live image pull failure: the release images are cached on this host, so the pull message is covered by the unit test.

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}