fix(cli): keep Windows upgrades and uninstalls from fighting the running binary - #50819

opencode upgrade on Windows hangs for five minutes and then prints Failed to update with bun. This PR makes upgrade, uninstall and manual package-manager upgrades work while OpenCode is running on Windows. Unix and macOS paths are untouched.

Root cause

sequenceDiagram
  participant U as opencode upgrade (running opencode.exe)
  participant B as bun install -g --cache-dir <tmp>
  participant N as NTFS
  U->>B: spawn (updater.ts)
  B->>N: rename @opencode/cli → .old-<hex>  (PackageInstall.rs:1941)
  B->>N: delete .old-<hex>/bin/opencode.exe (worker thread)
  N-->>B: STATUS_CANNOT_DELETE — last link of a mapped image
  Note over B: windows_errno.rs:847 maps it to EPERM
  Note over B: dir.rs:173-184 EPERM ⇒ "must be a dir" ⇒ ENOTDIR ⇒ "must be a file" ⇒ EPERM … forever
  U-->>U: 5 min timeout → "Failed to update with bun"

• NTFS refuses to delete a running executable only when the name being removed is its last hard link; any other link deletes fine (OSR deleteex: "so long as it's not the last link to the file"; STATUS_CANNOT_DELETE = "existing mapped view", MS-FSCC 2.4.11.1; libuv fs.c says the same in its fs__unlink comment). Measured here: non-last link deletes from Win32, node and bun; the last link fails with EPERM.
• updater.ts installs through a throwaway --cache-dir and deletes it, so node_modules holds the only links to the binary. The next upgrade removes the platform package's link first and the running @opencode/cli/bin/opencode.exe becomes the last link.
• bun 1.4.2 src/sys/dir.rs delete_tree loops forever on that EPERM — a regression from 1.3.13, which left an orphan and finished (bun install hangs forever on Windows when the replaced package holds the last hard link of a running exe (regression from 1.3.13) oven-sh/bun#43831). Every .old-* orphan in ~/.bun/install/global/node_modules has links=1 — same mechanism.
• The same fact bites the other installers differently: npm leaves a .cli-* orphan with npm warn cleanup … EPERM; Git Bash mv (curl installer) hits STATUS_ACCESS_DENIED on the in-use target and falls back to moving the 200 MB binary into the Recycle Bin (Cygwin syscalls.cc rename2 → unlink_nt → try_to_bin); uninstall reports Busy because libuv's kill(pid, 0) is GetExitCodeProcess != STILL_ACTIVE while TerminateProcess "is asynchronous" and the service's SQLite handles close a moment later.

Change (win32 only)

Keep a second hard link to the running image for as long as it must survive an installer. The installed path never disappears; installers delete a non-last link and succeed.

// services/retained-image.ts — scoped: link on acquire, best-effort remove on release
fs.link(realpath(process.execPath), `${directory}/opencode-${role}-${process.pid}-${random}.exe`)
// before linking, sweep links whose pid is gone: only ESRCH counts (uv_kill maps an
// inaccessible live process to EPERM), and the random suffix survives Windows pid reuse

// updater.ts — around every installer run (upgrade → cache, uninstall → %TEMP%\opencode)
Effect.scoped(RetainedImage.retain(directory, "upgrade").pipe(Effect.andThen(runInstaller)))

// server-process.ts — for the lifetime of `serve --service`, package-manager or curl installs only
if (mode === "service" && win32 && RetainedImage.installed(global.home)) yield* RetainedImage.retain(global.cache, "service")

// uninstall.ts — a link may be the last name of an image an older OpenCode still runs;
// renaming a running image is allowed, so move links out before deleting the cache
if (win32) yield* RetainedImage.relocate(global.cache, global.tmp)
// …and directory removal races the terminated service's handle teardown
Effect.retry({ while: (e) => process.platform === "win32" && e.reason._tag === "Busy", schedule: 250 ms × 40 })

Only binaries installed by a package manager or the curl installer are linked: never bun/node in a source checkout, never the Desktop app's bundled CLI (Desktop updates it itself). The link is skipped with a warning when the cache is on another volume, in which case behaviour is exactly as before this PR.

Results

Each cell is a real run in an isolated install root with its own managed-service port. Baseline = published @opencode/[email protected] (its updater.ts is identical to v2). Candidate = this branch compiled as 2.0.13. Every run upgrades 2.0.13 → 2.0.14 and checks the binary on disk, the manifest/lockfile, orphaned directories and the Recycle Bin.

✅ completed, consistent, nothing left behind · ⚠️ completed but left a 200 MB orphan dir or Recycle Bin deposit · ❌ hung or failed

opencode upgrade — service stopped (only the upgrader runs the binary)

opencode upgrade — service running (same for TUI /upgrade: update-notification.tsx → updater.apply → Updater.upgrade)

Manual package-manager upgrade in a shell — nothing running (control)

Manual package-manager upgrade in a shell — service running

opencode uninstall --force — service running

Notes on the grid:

• The grid passes --method to pin the installer; the same four service running upgrades were also run without it, and auto-detection picked the right installer every time.
• The TUI /upgrade shares the opencode upgrade — service running row: update-notification.tsx → updater.apply → Updater.install → Updater.upgrade.
• pnpm never hung: its content-addressable store already keeps a second link alive — the same principle this PR applies for bun, npm and curl. pnpm keeps old .pnpm/@opencode+cli@x entries until pnpm store prune; that is normal and not counted.
• The baseline uninstall failures are the Busy race (Failed to remove Data); it is timing-dependent — pnpm baseline passed in two runs and failed in a third.
• Extra check, not in the grid: opencode uninstall while an older OpenCode still runs from a cache link (e.g. a TUI that ran /upgrade). Candidate: all directories removed, the old process keeps running, its link moves to %TEMP%\opencode. Same setup with the published 2.0.13: Failed to remove Cache.
• The curl rows assume Git Bash is the bash on PATH; with WSL bash first, the installer runs under Linux, which is a pre-existing Windows issue not touched here.

Compared with macOS / Linux

Same user-visible semantics: opencode upgrade and /upgrade complete while OpenCode runs, already-running processes keep the old version until restarted, new launches get the new one, and a hand-typed package-manager upgrade works while the service runs. Windows-only differences:

Not run

• yarn and vp (not installed here); the change applies to them by construction because the link exists before any installer runs.
• The TUI /upgrade was not driven interactively; it calls the same Updater.upgrade.
• Desktop-managed service, ~\.cache on another volume, ARM64/baseline binaries.

Not in this PR

• Uninstall stops managed services only; any other OpenCode still running (TUI, serve) keeps the database open and Windows refuses to delete Data. Unchanged by this PR.

• Deleting the uninstaller's own binary after exit needs a self-deleting helper (as self-replace/rustup do); a bun-compiled binary has no hook for it. Possible follow-up.

• An older client still replaces a newer running service (default.ts mismatch: "replace"), which is how a 2.0.8 shell client "downgraded" a Desktop-managed 2.0.14 service. Separate change.

• bun's delete_tree EPERM loop is bun's bug, reported with a 10 MB self-contained repro and a 1.3.13-vs-1.4.2 measurement in bun install hangs forever on Windows when the replaced package holds the last hard link of a running exe (regression from 1.3.13) oven-sh/bun#43831; this PR only stops OpenCode from triggering it.