Decide: keep the --update binary swap, or replace it with the installer and keep only the update notifier

[mikolalysenko]

[agent] Filed by the scheduled architecture audit routine (CLI and core). Register: discussion #560 register.

Kind: decision. Source: review §5 ("Self-update binary swap"), §6 Q2, 7.5 and recommendation 15; register C36 (the self-update half; the agent-mode half is a separate row).

Question

Should socket-patch --update keep replacing its own binary, or should it hand the upgrade to the installer and keep only the passive notifier?

Options:

1. Keep the swap (recommended), with no product change. It is the only update path for the Windows standalone zip, and it already uses the installer's trust model. Engineering follow-ups that don't change behavior go through the existing rows: its two private HTTP clients and 300 s whole-download budget fold into the shared retry and timeout primitive (Tracking: one retry primitive for the patch API client (JSON, vendor service, blob and diff) #676), and the SOCKET_FORCE sharing stays Decide: give SOCKET_FORCE per-command names so forcing a self-update doesn't also force apply and vendor #615.
2. Replace the swap with an installer hint. --update would print (or, with --yes, run) curl -fsSL https://install.socket.dev/patch | sh, honoring the SOCKET_PATCH_VERSION pin. That deletes update/download.rs, update/swap.rs, the update lock and most of commands/update.rs: about −1.1K production lines and −1.5K test lines. It's a contract MAJOR (the self-update section, its error codes, the --update --dry-run probe). Windows standalone users lose their only updater, because there is no PowerShell installer: the README tells them to extract the zip by hand.
3. Hybrid: delegate to install.sh on Unix and keep the swap only for Windows. This keeps every piece of the swap machinery for one platform and adds a second path, so it saves the least.

Whatever is chosen, the notifier stays: the review and this issue agree it's cheap and channel-aware.

Problem (main @ 9c43dfc)

Self-update is 2,350 production lines (unchanged since the review's 2,351), plus 2,369 inline and 2,634 external test lines:

• core update/: channel 245, download 378, mod 161, release 452, state 135, swap 208;
• CLI: commands/update.rs 416, update_notifier.rs 355.

What it does, against the installer:

• Only InstallChannel::Standalone may swap; npm, Cargo and Homebrew get their own upgrade command, and the pre-v5 PyPI and gem locations get a migration hint.
• Release resolution has two strategies: a releases/latest redirect probe, then a GitHub API JSON fallback (fetch_latest_version). install.sh needs neither, because it downloads from latest/download/.
• Download, SHA256SUMS check, stage, sanity-exec and atomic rename run under a separate lock (perform_update). install.sh does the same download and checksum steps, then install -m 755. The trust model is the same (HTTPS + GitHub, unsigned checksums), as docs/installer-hosting.md says.
• The asset name comes from the compiled target triple (asset_name_for_target), so a musl binary updates to musl. install.sh re-detects libc with ldd (L55-L70), and its platform table has no Windows rows.
• Windows: the README says to extract the zip by hand and then use socket-patch --update. swap.rs has its own #[cfg(windows)] path.
• Two private reqwest clients (download_client, metadata_client) with whole-request budgets (30 s metadata, 300 s download) and no retry.

Symptoms

No open bugs. #128, #140 and #171 were the swap's own flake and hardening fixes.

Impact

This is a product and maintenance trade-off, not a defect. Option 2 removes the code that's the most expensive to test (exec sanity checks, ETXTBSY retries, Windows rename), but it costs Windows users and changes a documented contract.

Proposed change (after the decision)

• Option 1: close this issue as "keep". No code change; Tracking: one retry primitive for the patch API client (JSON, vendor service, blob and diff) #676 and Decide: give SOCKET_FORCE per-command names so forcing a self-update doesn't also force apply and vendor #615 carry the follow-ups.
• Option 2: one PR that replaces perform_update's call site with the hint, deletes update/download.rs, update/swap.rs and the update lock, keeps channel.rs, release.rs (the notifier's version check) and state.rs, and rewrites the contract's "Self-update contract" section with a MAJOR note.
• Option 3: gate perform_update on cfg(windows) and add the Unix hint.

Size and scope

Option 2: about −1.1K production and −1.5K test lines in update/, commands/update.rs, the self_update_* and tests/update/ suites, CLI_CONTRACT.md and the README. The notifier and channel detection are out of scope.

Acceptance criteria

• An owner picks an option.
• If 2 or 3: CLI_CONTRACT.md documents the new --update behavior with a MAJOR note, the README's install section matches, and update_notifier_e2e stays green.
• If 1: the living document's §5 and 7.5 rows record the decision.

Dependencies

• Related: Decide: give SOCKET_FORCE per-command names so forcing a self-update doesn't also force apply and vendor #615 (SOCKET_FORCE is shared with --update --force) and Tracking: one retry primitive for the patch API client (JSON, vendor service, blob and diff) #676 (one retry primitive).
• Blocks nothing.

[mikolalysenko]

[agent] Triaged as priority:p3. This is a product decision (keep the self-update swap, replace it, or go hybrid), so it stays agent:needs-human and isn't eligible for an agent claim until a maintainer chooses an option. Related follow-ups: #676 and #615.

---

Generated by Claude Code