@kr78/pi-coding-agent 17.2.10

package/src/cli/update-cli.ts

@@ -0,0 +1,1184 @@
+/**
+ * Update CLI command handler.
+ *
+ * Handles `omp update` to check for and install updates.
+ * Uses the installer that owns the active omp executable when it can be detected.
+ */
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { $env, $which, APP_NAME, compareVersions, isEnoent, VERSION } from "@oh-my-pi/pi-utils";
+import chalk from "@oh-my-pi/pi-utils/chalk";
+import { $ } from "bun";
+import { theme } from "../modes/theme/theme";
+import { isTimeoutError, withTimeoutSignal } from "../utils/fetch-timeout";
+
+const REPO = "can1357/oh-my-pi";
+const PACKAGE = "@oh-my-pi/pi-coding-agent";
+const HOMEBREW_FORMULA = "can1357/tap/omp";
+const MISE_TOOL = "github:can1357/oh-my-pi";
+/**
+ * Official npm registry origin.
+ *
+ * Pinned across both the version check and the bun install step so the two
+ * agree on which catalog they are talking to. A user's bun may be pointed at
+ * an unofficial mirror (corporate proxy, Taobao, etc.) that lags the upstream
+ * registry by minutes-to-hours, in which case `getLatestRelease` would resolve
+ * a version the mirror has not yet replicated and the install would fail with
+ * `No version matching "X" found for specifier "<pkg>" (but package exists)`.
+ * See #1686.
+ */
+const NPM_REGISTRY = "https://registry.npmjs.org/";
+const GITHUB_API = "https://api.github.com";
+const RELEASE_METADATA_TIMEOUT_MS = 30_000;
+const BINARY_DOWNLOAD_TIMEOUT_MS = 15 * 60_000;
+
+/**
+ * Core native addon package. Bumped in lock-step with {@link PACKAGE} so the
+ * version sentinel the loader looks up at runtime matches the `.node` on
+ * disk; see {@link buildBunInstallArgs} for why this must be installed
+ * explicitly rather than inherited as a transitive dependency.
+ */
+const NATIVES_PACKAGE = "@oh-my-pi/pi-natives";
+
+/**
+ * Platform tags the release pipeline publishes as
+ * `@oh-my-pi/pi-natives-<tag>` leaves. Mirrors `SUPPORTED_PLATFORMS` in
+ * `packages/natives/native/loader-state.js` and `LEAF_TARGETS` in
+ * `packages/natives/scripts/gen-npm-packages.ts`; kept here as the local
+ * source of truth so the update path stays free of cross-package imports.
+ */
+const SUPPORTED_NATIVE_TAGS: ReadonlySet<string> = new Set([
+	"linux-x64",
+	"linux-arm64",
+	"darwin-x64",
+	"darwin-arm64",
+	"win32-x64",
+]);
+
+function currentNativeTag(): string {
+	return `${process.platform}-${process.arch}`;
+}
+
+interface ReleaseInfo {
+	tag: string;
+	version: string;
+}
+
+export interface ReleaseBinaryAsset {
+	url: string;
+	size: number;
+	digest: string;
+}
+
+type Fetch = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+/**
+ * Select and validate the binary asset from GitHub release metadata.
+ */
+export function resolveReleaseBinaryAsset(
+	release: unknown,
+	expectedTag: string,
+	binaryName: string,
+): ReleaseBinaryAsset {
+	if (!isRecord(release)) {
+		throw new Error("Invalid GitHub release metadata");
+	}
+	if (release.tag_name !== expectedTag) {
+		throw new Error(`GitHub release tag mismatch: expected ${expectedTag}`);
+	}
+	if (release.draft !== false || release.prerelease !== false) {
+		throw new Error(`GitHub release ${expectedTag} is not a published stable release`);
+	}
+	if (!Array.isArray(release.assets)) {
+		throw new Error(`GitHub release ${expectedTag} has no asset list`);
+	}
+
+	const matches = release.assets.filter(asset => isRecord(asset) && asset.name === binaryName);
+	if (matches.length !== 1) {
+		throw new Error(`GitHub release ${expectedTag} has ${matches.length} assets named ${binaryName}`);
+	}
+
+	const asset = matches[0];
+	if (!isRecord(asset) || asset.state !== "uploaded") {
+		throw new Error(`GitHub release asset ${binaryName} is not fully uploaded`);
+	}
+	if (typeof asset.size !== "number" || !Number.isSafeInteger(asset.size) || asset.size <= 0) {
+		throw new Error(`GitHub release asset ${binaryName} has an invalid size`);
+	}
+	if (typeof asset.digest !== "string") {
+		throw new Error(`GitHub release asset ${binaryName} has no digest`);
+	}
+	const digest = /^sha256:([0-9a-f]{64})$/i.exec(asset.digest)?.[1];
+	if (!digest) {
+		throw new Error(`GitHub release asset ${binaryName} has an unsupported digest`);
+	}
+
+	const expectedUrl = `https://github.com/${REPO}/releases/download/${expectedTag}/${binaryName}`;
+	if (asset.browser_download_url !== expectedUrl) {
+		throw new Error(`GitHub release asset ${binaryName} has an unexpected download URL`);
+	}
+
+	return {
+		url: expectedUrl,
+		size: asset.size,
+		digest: `sha256:${digest.toLowerCase()}`,
+	};
+}
+
+async function getReleaseBinaryAsset(
+	expectedVersion: string,
+	binaryName: string,
+	fetchImpl: Fetch = fetch,
+	githubToken: string | undefined = $env.GITHUB_TOKEN || $env.GH_TOKEN,
+): Promise<ReleaseBinaryAsset> {
+	const tag = `v${expectedVersion}`;
+	const headers: Record<string, string> = {
+		Accept: "application/vnd.github+json",
+		"X-GitHub-Api-Version": "2022-11-28",
+	};
+	if (githubToken) headers.Authorization = `Bearer ${githubToken}`;
+
+	let response: Response;
+	try {
+		response = await fetchImpl(`${GITHUB_API}/repos/${REPO}/releases/tags/${encodeURIComponent(tag)}`, {
+			headers,
+			signal: withTimeoutSignal(RELEASE_METADATA_TIMEOUT_MS),
+		});
+	} catch (err) {
+		if (isTimeoutError(err)) {
+			throw new Error("Timed out fetching GitHub release metadata after 30s", { cause: err });
+		}
+		throw err;
+	}
+	if ((response.status === 403 && !githubToken) || response.status === 429) {
+		throw new Error(
+			"GitHub API rate limit exceeded while fetching release metadata; retry later or set GITHUB_TOKEN or GH_TOKEN",
+		);
+	}
+	if (!response.ok) {
+		throw new Error(`Failed to fetch GitHub release metadata: ${response.statusText}`);
+	}
+
+	return resolveReleaseBinaryAsset(await response.json(), tag, binaryName);
+}
+
+export interface VerifiedBinaryDownloadOptions {
+	url: string;
+	targetPath: string;
+	expectedSize: number;
+	expectedDigest: string;
+	fetchImpl?: Fetch;
+}
+
+/**
+ * Download a binary and verify its GitHub-reported size and SHA-256 digest.
+ */
+export async function downloadVerifiedBinary(options: VerifiedBinaryDownloadOptions): Promise<void> {
+	const fetchImpl = options.fetchImpl ?? fetch;
+	await unlinkIfExists(options.targetPath);
+
+	let response: Response;
+	try {
+		response = await fetchImpl(options.url, {
+			redirect: "follow",
+			signal: withTimeoutSignal(BINARY_DOWNLOAD_TIMEOUT_MS),
+		});
+	} catch (err) {
+		if (isTimeoutError(err)) {
+			throw new Error("Timed out downloading release binary after 15 minutes", { cause: err });
+		}
+		throw err;
+	}
+	if (!response.ok || !response.body) {
+		throw new Error(`Download failed: ${response.statusText}`);
+	}
+
+	const hash = createHash("sha256");
+	let size = 0;
+	const verifier = new Transform({
+		transform(chunk, _encoding, callback) {
+			size += chunk.byteLength;
+			if (size > options.expectedSize) {
+				callback(
+					new Error(
+						`Downloaded binary size mismatch: expected ${options.expectedSize} bytes, received at least ${size}`,
+					),
+				);
+				return;
+			}
+			hash.update(chunk);
+			callback(null, chunk);
+		},
+	});
+
+	try {
+		await pipeline(response.body, verifier, fs.createWriteStream(options.targetPath, { mode: 0o600 }));
+		const digest = `sha256:${hash.digest("hex")}`;
+		if (size !== options.expectedSize) {
+			throw new Error(`Downloaded binary size mismatch: expected ${options.expectedSize} bytes, received ${size}`);
+		}
+		if (digest !== options.expectedDigest) {
+			throw new Error(`Downloaded binary digest mismatch: expected ${options.expectedDigest}, received ${digest}`);
+		}
+		await fs.promises.chmod(options.targetPath, 0o755);
+	} catch (err) {
+		await unlinkIfExists(options.targetPath);
+		if (isTimeoutError(err)) {
+			throw new Error("Timed out downloading release binary after 15 minutes", { cause: err });
+		}
+		throw err;
+	}
+}
+
+/** Result from running the installed binary and parsing its reported version. */
+export interface InstalledVersionVerification {
+	ok: boolean;
+	actual?: string;
+	path?: string;
+}
+
+/** Paths and verifier used while replacing a downloaded binary update. */
+export interface BinaryReplacementOptions {
+	targetPath: string;
+	tempPath: string;
+	backupPath: string;
+	expectedVersion: string;
+	verifyInstalledVersion: (expectedVersion: string) => Promise<InstalledVersionVerification>;
+}
+
+/**
+ * Parse update subcommand arguments.
+ * Returns undefined if not an update command.
+ */
+export function parseUpdateArgs(args: string[]): { force: boolean; check: boolean; plugins: boolean } | undefined {
+	if (args.length === 0 || args[0] !== "update") {
+		return undefined;
+	}
+
+	return {
+		force: args.includes("--force") || args.includes("-f"),
+		check: args.includes("--check") || args.includes("-c"),
+		plugins: args.includes("--plugins") || args.includes("-l"),
+	};
+}
+
+async function getBunGlobalBinDir(): Promise<string | undefined> {
+	if (!$which("bun")) return undefined;
+	try {
+		const result = await $`bun pm bin -g`.quiet().nothrow();
+		if (result.exitCode !== 0) return undefined;
+		const output = result.text().trim();
+		return output.length > 0 ? output : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+async function getNpmGlobalBinDir(): Promise<string | undefined> {
+	if (!$which("npm")) return undefined;
+	try {
+		const result = await $`npm prefix -g`.quiet().nothrow();
+		if (result.exitCode !== 0) return undefined;
+		const prefix = result.text().trim();
+		if (prefix.length === 0) return undefined;
+		return process.platform === "win32" ? prefix : path.join(prefix, "bin");
+	} catch {
+		return undefined;
+	}
+}
+
+async function getHomebrewFormulaPrefix(): Promise<string | undefined> {
+	if (!$which("brew")) return undefined;
+	for (const formula of [HOMEBREW_FORMULA, APP_NAME]) {
+		try {
+			const result = await $`brew --prefix ${formula}`.quiet().nothrow();
+			if (result.exitCode !== 0) continue;
+			const output = result.text().trim();
+			if (output.length > 0) return output;
+		} catch {}
+	}
+	return undefined;
+}
+
+async function getMiseBinDirs(): Promise<string[]> {
+	if (!$which("mise")) return [];
+	try {
+		const result = await $`mise bin-paths ${MISE_TOOL}`.quiet().nothrow();
+		if (result.exitCode !== 0) return [];
+		return result
+			.text()
+			.split(/\r?\n/)
+			.map(line => line.trim())
+			.filter(line => line.length > 0);
+	} catch {
+		return [];
+	}
+}
+
+function getMiseDataDir(): string {
+	const override = process.env.MISE_DATA_DIR;
+	if (override && override.length > 0) return override;
+	if (process.platform === "win32") {
+		const localAppData = process.env.LOCALAPPDATA;
+		if (localAppData && localAppData.length > 0) return path.join(localAppData, "mise");
+	}
+	const xdgDataHome = process.env.XDG_DATA_HOME;
+	if (xdgDataHome && xdgDataHome.length > 0) return path.join(xdgDataHome, "mise");
+	return path.join(os.homedir(), ".local", "share", "mise");
+}
+
+function normalizePathForComparison(filePath: string): string {
+	const normalized = path.normalize(filePath);
+	if (process.platform === "win32") return normalized.toLowerCase();
+	return normalized;
+}
+
+function tryRealpath(p: string): string | undefined {
+	try {
+		return fs.realpathSync.native(p);
+	} catch {
+		return undefined;
+	}
+}
+
+function isPathInDirectoryLexical(filePath: string, directoryPath: string): boolean {
+	const normalizedPath = normalizePathForComparison(path.resolve(filePath));
+	const normalizedDirectory = normalizePathForComparison(path.resolve(directoryPath));
+	const relativePath = path.relative(normalizedDirectory, normalizedPath);
+	return relativePath === "" || (!relativePath.startsWith("..") && !path.isAbsolute(relativePath));
+}
+
+function isPathInDirectory(filePath: string, directoryPath: string): boolean {
+	if (isPathInDirectoryLexical(filePath, directoryPath)) return true;
+	// Layer realpath resolution on top of the lexical guard. On Windows, ~/.bun
+	// is a junction when Bun is installed via Scoop, so `bun pm bin -g` and the
+	// PATH-resolved omp path can refer to the same directory through different
+	// strings. path.resolve does not traverse junctions/symlinks; realpath does.
+	// Resolve both the file and its parent directory: the file catches manager
+	// links like Homebrew's `bin/omp -> Cellar/.../bin/omp`; the parent fallback
+	// still tolerates fresh install paths where the file does not exist yet.
+	const dirReal = tryRealpath(path.resolve(directoryPath));
+	if (!dirReal) return false;
+	const fileReal = tryRealpath(path.resolve(filePath));
+	if (fileReal && isPathInDirectoryLexical(fileReal, dirReal)) return true;
+	const fileDir = tryRealpath(path.dirname(path.resolve(filePath)));
+	if (!fileDir) return false;
+	const resolvedFile = path.join(fileDir, path.basename(filePath));
+	return isPathInDirectoryLexical(resolvedFile, dirReal);
+}
+
+type UpdateMethod = "brew" | "mise" | "bun" | "npm" | "binary";
+
+interface UpdateMethodResolutionOptions {
+	homebrewPrefix?: string;
+	miseBinDirs?: readonly string[];
+	miseDataDir?: string;
+	npmBinDir?: string;
+	/**
+	 * Whether the resolved omp path is a plain file (the standalone binary)
+	 * rather than a package-manager symlink. Stops a binary install from being
+	 * misrouted to npm/bun when the global bin dir overlaps the installer's
+	 * target directory.
+	 */
+	ompIsRegularFile?: boolean;
+}
+
+type UpdateTarget =
+	| { method: "brew" }
+	| { method: "mise" }
+	| { method: "bun" }
+	| { method: "npm" }
+	| { method: "binary"; path: string };
+
+function resolveUpdateMethod(
+	ompPath: string,
+	bunBinDir: string | undefined,
+	options: UpdateMethodResolutionOptions = {},
+): UpdateMethod {
+	const { homebrewPrefix, miseBinDirs = [], miseDataDir, npmBinDir, ompIsRegularFile = false } = options;
+	const launcherExtension = path.extname(ompPath).toLowerCase();
+	const isWindowsScriptLauncher =
+		launcherExtension === ".cmd" || launcherExtension === ".ps1" || launcherExtension === ".bat";
+	if (homebrewPrefix && isPathInDirectory(ompPath, path.join(homebrewPrefix, "bin"))) return "brew";
+	if (miseBinDirs.some(dir => isPathInDirectory(ompPath, dir))) return "mise";
+	if (miseDataDir && isPathInDirectory(ompPath, path.join(miseDataDir, "shims"))) return "mise";
+	// A plain executable file in a package-manager bin dir is the standalone
+	// binary the installer placed there, not an npm/bun-managed install (those
+	// symlink into node_modules on POSIX). When the global bin dir overlaps the
+	// installer's default (~/.local/bin), classifying by directory alone routes
+	// a binary install through npm/bun, whose reinstall then collides with the
+	// existing file (npm EEXIST). Fall through to binary replacement instead.
+	// Windows is excluded: there package managers write regular-file shims
+	// (bun's .exe launcher, npm's .cmd/.ps1), so a regular file is NOT evidence
+	// of a standalone install and the override would hijack managed installs.
+	const isStandaloneRegularFile = ompIsRegularFile && process.platform !== "win32";
+	if (bunBinDir && isPathInDirectory(ompPath, bunBinDir) && !isStandaloneRegularFile) return "bun";
+	if ((npmBinDir && isPathInDirectory(ompPath, npmBinDir) && !isStandaloneRegularFile) || isWindowsScriptLauncher)
+		return "npm";
+	return "binary";
+}
+
+export function resolveUpdateMethodForTest(
+	ompPath: string,
+	bunBinDir: string | undefined,
+	options: UpdateMethodResolutionOptions = {},
+): UpdateMethod {
+	return resolveUpdateMethod(ompPath, bunBinDir, options);
+}
+async function resolveUpdateTarget(): Promise<UpdateTarget> {
+	const bunBinDir = await getBunGlobalBinDir();
+	const npmBinDir = await getNpmGlobalBinDir();
+	const homebrewPrefix = await getHomebrewFormulaPrefix();
+	const miseAvailable = $which("mise") !== undefined;
+	const miseBinDirs = miseAvailable ? await getMiseBinDirs() : [];
+	const miseDataDir = miseAvailable ? getMiseDataDir() : undefined;
+	const ompPath = resolveOmpPath();
+
+	if (ompPath) {
+		// Package-manager installs symlink the bin entry into node_modules; the
+		// standalone installer writes a plain executable. When the global bin dir
+		// overlaps the installer's default (~/.local/bin), that file type — not
+		// directory containment — distinguishes a binary install from npm/bun.
+		let ompIsRegularFile = false;
+		try {
+			const stat = fs.lstatSync(ompPath);
+			ompIsRegularFile = stat.isFile() && !stat.isSymbolicLink();
+		} catch {}
+		const method = resolveUpdateMethod(ompPath, bunBinDir, {
+			homebrewPrefix,
+			miseBinDirs,
+			miseDataDir,
+			npmBinDir,
+			ompIsRegularFile,
+		});
+		if (method === "binary") return { method, path: ompPath };
+		return { method };
+	}
+
+	if (bunBinDir) return { method: "bun" };
+
+	throw new Error(`Could not resolve ${APP_NAME} binary path in PATH`);
+}
+
+/**
+ * Get the latest release info from the npm registry.
+ * Uses npm instead of GitHub API to avoid unauthenticated rate limiting.
+ */
+async function getLatestRelease(): Promise<ReleaseInfo> {
+	let response: Response;
+	try {
+		response = await fetch(`${NPM_REGISTRY}${PACKAGE}/latest`, {
+			signal: withTimeoutSignal(RELEASE_METADATA_TIMEOUT_MS),
+		});
+	} catch (err) {
+		if (isTimeoutError(err)) {
+			throw new Error("Timed out fetching release info after 30s", { cause: err });
+		}
+		throw err;
+	}
+	if (!response.ok) {
+		throw new Error(`Failed to fetch release info: ${response.statusText}`);
+	}
+
+	const data = (await response.json()) as { version: string };
+	const version = data.version;
+	const tag = `v${version}`;
+
+	return {
+		tag,
+		version,
+	};
+}
+
+interface BunInstallCachePruneResult {
+	scannedPackages: number;
+	removedEntries: number;
+}
+
+interface BunCachePackageGroup {
+	actualDirs: Map<string, string[]>;
+	markerDir?: string;
+	markerEntries: Map<string, string[]>;
+}
+
+function stripBunCacheVersionSuffix(name: string): string {
+	const metadataIndex = name.indexOf("@@");
+	return metadataIndex === -1 ? name : name.slice(0, metadataIndex);
+}
+
+async function readdirIfExists(dir: string): Promise<fs.Dirent[]> {
+	try {
+		return await fs.promises.readdir(dir, { withFileTypes: true });
+	} catch (err) {
+		if (isEnoent(err)) return [];
+		throw err;
+	}
+}
+
+function getBunCacheGroup(groups: Map<string, BunCachePackageGroup>, packageName: string): BunCachePackageGroup {
+	let group = groups.get(packageName);
+	if (!group) {
+		group = { actualDirs: new Map(), markerEntries: new Map() };
+		groups.set(packageName, group);
+	}
+	return group;
+}
+
+function addVersionPath(entries: Map<string, string[]>, version: string, entryPath: string): void {
+	const paths = entries.get(version);
+	if (paths) {
+		paths.push(entryPath);
+		return;
+	}
+	entries.set(version, [entryPath]);
+}
+
+async function addBunCacheActualDir(
+	groups: Map<string, BunCachePackageGroup>,
+	dirPath: string,
+	packageNames: Set<string> | undefined,
+): Promise<void> {
+	try {
+		const manifest = (await Bun.file(path.join(dirPath, "package.json")).json()) as Partial<
+			Record<"name" | "version", unknown>
+		>;
+		if (typeof manifest.name !== "string" || typeof manifest.version !== "string") return;
+		if (packageNames && !packageNames.has(manifest.name)) return;
+		const group = getBunCacheGroup(groups, manifest.name);
+		addVersionPath(group.actualDirs, manifest.version, dirPath);
+	} catch (err) {
+		if (isEnoent(err)) return;
+		throw err;
+	}
+}
+
+async function addBunCacheMarkerDir(
+	groups: Map<string, BunCachePackageGroup>,
+	packageName: string,
+	markerDir: string,
+	packageNames: Set<string> | undefined,
+): Promise<void> {
+	if (packageNames && !packageNames.has(packageName)) return;
+	const markerEntries = await readdirIfExists(markerDir);
+	const group = getBunCacheGroup(groups, packageName);
+	group.markerDir = markerDir;
+	for (const entry of markerEntries) {
+		const cacheVersion = stripBunCacheVersionSuffix(entry.name);
+		addVersionPath(group.markerEntries, cacheVersion, path.join(markerDir, entry.name));
+	}
+}
+
+async function collectBunCacheGroups(
+	cacheDir: string,
+	packageNames: Set<string> | undefined,
+): Promise<Map<string, BunCachePackageGroup>> {
+	const groups = new Map<string, BunCachePackageGroup>();
+	for (const entry of await readdirIfExists(cacheDir)) {
+		if (!entry.isDirectory()) continue;
+		const entryPath = path.join(cacheDir, entry.name);
+		if (entry.name.startsWith("@")) {
+			for (const scopedEntry of await readdirIfExists(entryPath)) {
+				if (!scopedEntry.isDirectory()) continue;
+				const scopedEntryPath = path.join(entryPath, scopedEntry.name);
+				const versionSeparator = scopedEntry.name.lastIndexOf("@");
+				if (versionSeparator === -1) {
+					await addBunCacheMarkerDir(groups, `${entry.name}/${scopedEntry.name}`, scopedEntryPath, packageNames);
+				} else {
+					await addBunCacheActualDir(groups, scopedEntryPath, packageNames);
+				}
+			}
+			continue;
+		}
+		const versionSeparator = entry.name.lastIndexOf("@");
+		if (versionSeparator === -1) {
+			await addBunCacheMarkerDir(groups, entry.name, entryPath, packageNames);
+		} else {
+			await addBunCacheActualDir(groups, entryPath, packageNames);
+		}
+	}
+	return groups;
+}
+
+async function removeCacheEntries(paths: string[]): Promise<number> {
+	for (const entryPath of paths) {
+		await fs.promises.rm(entryPath, { recursive: true, force: true });
+	}
+	return paths.length;
+}
+
+/**
+ * Prune Bun's package cache so each package keeps only its newest cached version.
+ *
+ * Bun stores package cache entries as both a package marker directory
+ * (`react/19.2.6@@@1`) and a materialized package directory
+ * (`react@19.2.6@@@1`). Global `omp` updates can leave one full copy per
+ * release. The marker and materialized entries are removed together so the
+ * cache stays internally consistent.
+ */
+export async function pruneBunInstallCache(
+	cacheDir: string,
+	packageNames?: Set<string>,
+): Promise<BunInstallCachePruneResult> {
+	const groups = await collectBunCacheGroups(cacheDir, packageNames);
+	let scannedPackages = 0;
+	let removedEntries = 0;
+	for (const group of groups.values()) {
+		if (group.actualDirs.size === 0) continue;
+		scannedPackages++;
+		let latestVersion: string | undefined;
+		for (const version of group.actualDirs.keys()) {
+			if (!latestVersion || compareVersions(version, latestVersion) > 0) latestVersion = version;
+		}
+		if (!latestVersion) continue;
+		for (const [version, paths] of group.actualDirs) {
+			if (version !== latestVersion) removedEntries += await removeCacheEntries(paths);
+		}
+		for (const [version, paths] of group.markerEntries) {
+			if (version !== latestVersion) removedEntries += await removeCacheEntries(paths);
+		}
+	}
+	return { scannedPackages, removedEntries };
+}
+
+async function resolveBunInstallCacheDir(): Promise<string | undefined> {
+	try {
+		const result = await $`bun pm cache`.quiet().nothrow();
+		if (result.exitCode !== 0) return undefined;
+		const output = result.text().trim();
+		return output.length > 0 ? output : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+export function resolveBunGlobalNodeModulesDirFromLocations(
+	globalBinDir: string | undefined,
+	cacheDir: string | undefined,
+): string | undefined {
+	if (globalBinDir && globalBinDir.length > 0) {
+		return path.join(path.dirname(globalBinDir), "install", "global", "node_modules");
+	}
+	if (cacheDir && cacheDir.length > 0) {
+		return path.join(path.dirname(cacheDir), "global", "node_modules");
+	}
+	return undefined;
+}
+
+async function resolveBunGlobalNodeModulesDir(cacheDir: string): Promise<string | undefined> {
+	try {
+		const result = await $`bun pm bin -g`.quiet().nothrow();
+		const globalBinDir = result.exitCode === 0 ? result.text().trim() : undefined;
+		return resolveBunGlobalNodeModulesDirFromLocations(globalBinDir, cacheDir);
+	} catch {
+		return resolveBunGlobalNodeModulesDirFromLocations(undefined, cacheDir);
+	}
+}
+
+async function collectInstalledPackageNames(nodeModulesDir: string): Promise<Set<string>> {
+	const packageNames = new Set<string>();
+	for (const entry of await readdirIfExists(nodeModulesDir)) {
+		if (!entry.isDirectory() || entry.name === ".bin") continue;
+		if (entry.name.startsWith("@")) {
+			for (const scopedEntry of await readdirIfExists(path.join(nodeModulesDir, entry.name))) {
+				if (scopedEntry.isDirectory()) packageNames.add(`${entry.name}/${scopedEntry.name}`);
+			}
+			continue;
+		}
+		packageNames.add(entry.name);
+	}
+	return packageNames;
+}
+
+async function pruneBunCacheAfterGlobalInstall(): Promise<BunInstallCachePruneResult | undefined> {
+	const cacheDir = await resolveBunInstallCacheDir();
+	if (!cacheDir) return undefined;
+	const globalNodeModulesDir = await resolveBunGlobalNodeModulesDir(cacheDir);
+	const packageNames = globalNodeModulesDir
+		? await collectInstalledPackageNames(globalNodeModulesDir)
+		: new Set<string>();
+	if (packageNames.size === 0 && !path.basename(cacheDir).toLowerCase().includes("omp")) return undefined;
+	return await pruneBunInstallCache(cacheDir, packageNames.size === 0 ? undefined : packageNames);
+}
+
+/**
+ * Detect a musl-libc Linux host (Alpine, Void-musl) so self-update replaces a
+ * musl binary with the musl release asset instead of the glibc build, which
+ * would fail to start on the next run. The loader file alone is not sufficient:
+ * glibc hosts may have musl installed for cross-compilation.
+ */
+interface MuslDetectionOptions {
+	platform?: NodeJS.Platform;
+	alpineRelease?: boolean;
+	lddOutput?: string;
+}
+
+function detectLddOutput(): string | undefined {
+	try {
+		const result = Bun.spawnSync(["ldd", "--version"], { stdout: "pipe", stderr: "pipe" });
+		return `${result.stdout.toString("utf-8")}\n${result.stderr.toString("utf-8")}`;
+	} catch {
+		return undefined;
+	}
+}
+
+function isMuslLinux(options: MuslDetectionOptions = {}): boolean {
+	if ((options.platform ?? process.platform) !== "linux") return false;
+	if (options.alpineRelease ?? fs.existsSync("/etc/alpine-release")) return true;
+	return /\bmusl\b/i.test(options.lddOutput ?? detectLddOutput() ?? "");
+}
+
+/** Test seam for libc detection. */
+export function isMuslLinuxForTest(options: Required<MuslDetectionOptions>): boolean {
+	return isMuslLinux(options);
+}
+
+/**
+ * Get the appropriate binary name for this platform.
+ */
+function getBinaryName(): string {
+	const platform = process.platform;
+	const arch = process.arch;
+
+	let os: string;
+	switch (platform) {
+		case "linux":
+			os = isMuslLinux() ? "linux-musl" : "linux";
+			break;
+		case "darwin":
+			os = "darwin";
+			break;
+		case "win32":
+			os = "windows";
+			break;
+		default:
+			throw new Error(`Unsupported platform: ${platform}`);
+	}
+
+	let archName: string;
+	switch (arch) {
+		case "x64":
+			archName = "x64";
+			break;
+		case "arm64":
+			archName = "arm64";
+			break;
+		default:
+			throw new Error(`Unsupported architecture: ${arch}`);
+	}
+
+	if (os === "windows") {
+		return `${APP_NAME}-${os}-${archName}.exe`;
+	}
+	return `${APP_NAME}-${os}-${archName}`;
+}
+
+/**
+ * Resolve the path that `omp` maps to in the user's PATH.
+ */
+function resolveOmpPath(): string | undefined {
+	return $which(APP_NAME) ?? undefined;
+}
+
+/**
+ * Run the resolved omp binary and check if it reports the expected version.
+ */
+async function verifyInstalledVersion(expectedVersion: string): Promise<InstalledVersionVerification> {
+	const ompPath = resolveOmpPath();
+	if (!ompPath) return { ok: false };
+	try {
+		const result = await $`${ompPath} --version`.quiet().nothrow();
+		if (result.exitCode !== 0) return { ok: false, path: ompPath };
+		const output = result.text().trim();
+		// Output format: "omp/X.Y.Z"
+		const match = output.match(/\/(\d+\.\d+\.\d+)/);
+		const actual = match?.[1];
+		return { ok: actual === expectedVersion, actual, path: ompPath };
+	} catch {
+		return { ok: false, path: ompPath };
+	}
+}
+
+function printVerifiedVersion(expectedVersion: string): void {
+	console.log(chalk.green(`\n${theme.status.success} Updated to ${expectedVersion}`));
+}
+
+function formatVerificationFailure(result: InstalledVersionVerification, expectedVersion: string): string {
+	if (result.actual) {
+		return `${APP_NAME} at ${result.path} still reports ${result.actual} (expected ${expectedVersion})`;
+	}
+	return `could not verify updated version${result.path ? ` at ${result.path}` : ""}`;
+}
+
+/**
+ * Print post-update verification result.
+ */
+async function printVerification(expectedVersion: string): Promise<void> {
+	const result = await verifyInstalledVersion(expectedVersion);
+	if (result.ok) {
+		printVerifiedVersion(expectedVersion);
+		return;
+	}
+	console.log(chalk.yellow(`\nWarning: ${formatVerificationFailure(result, expectedVersion)}`));
+	console.log(chalk.yellow(`You may need to reinstall: curl -fsSL https://omp.sh/install | sh`));
+}
+
+async function unlinkIfExists(filePath: string): Promise<void> {
+	try {
+		await fs.promises.unlink(filePath);
+	} catch (err) {
+		if (!isEnoent(err)) throw err;
+	}
+}
+
+/**
+ * Remove a backup binary without letting the removal abort a completed update.
+ *
+ * On Windows the executable that was just moved aside is still mapped as the
+ * running process image, so unlinking it fails with EPERM/EACCES until this
+ * process exits (issue #845). The replacement and verification already
+ * succeeded by the time we get here, so every error is swallowed; the leftover
+ * is reclaimed by {@link sweepStaleBackups} on the next update once it is no
+ * longer in use. Returns whether the file is gone.
+ */
+async function removeBackupBestEffort(filePath: string): Promise<boolean> {
+	try {
+		await fs.promises.unlink(filePath);
+		return true;
+	} catch (err) {
+		return isEnoent(err);
+	}
+}
+
+/**
+ * Best-effort removal of binary-update backups left by earlier runs.
+ *
+ * Each self-update moves the previous executable to `<binary>.<timestamp>.<pid>.bak`
+ * before swapping the new one in. On Windows that backup cannot be deleted
+ * while the updating process is alive, so it is left for a later run to reclaim
+ * once its owning process has exited. Also matches the legacy fixed
+ * `<binary>.bak` name produced before backups were timestamped, so users
+ * upgrading from a buggy release get the orphaned file cleaned up.
+ */
+export async function sweepStaleBackups(targetPath: string): Promise<void> {
+	const dir = path.dirname(targetPath);
+	const base = path.basename(targetPath);
+	let entries: string[];
+	try {
+		entries = await fs.promises.readdir(dir);
+	} catch {
+		return;
+	}
+	for (const entry of entries) {
+		if (!entry.startsWith(`${base}.`) || !entry.endsWith(".bak")) continue;
+		// Legacy "<base>.bak" → empty middle; new "<base>.<timestamp>.<pid>.bak"
+		// → dot-separated numeric run. Anything else is an unrelated *.bak file.
+		const middle = entry.slice(base.length + 1, entry.length - ".bak".length);
+		if (middle.length > 0 && !/^\d+(\.\d+)*$/.test(middle)) continue;
+		await removeBackupBestEffort(path.join(dir, entry));
+	}
+}
+
+/**
+ * Atomically replace the installed binary and roll back if version verification fails.
+ */
+export async function replaceBinaryForUpdate(options: BinaryReplacementOptions): Promise<InstalledVersionVerification> {
+	let backupReady = false;
+	try {
+		// `backupPath` is unique per attempt (see updateViaBinaryAt), so this rename
+		// never has to overwrite — or unlink — a possibly-locked leftover from an
+		// earlier run. Renaming the running executable itself is permitted on
+		// Windows; only deleting its still-mapped image is not.
+		await fs.promises.rename(options.targetPath, options.backupPath);
+		backupReady = true;
+		await fs.promises.rename(options.tempPath, options.targetPath);
+
+		const verification = await options.verifyInstalledVersion(options.expectedVersion);
+		if (!verification.ok) {
+			throw new Error(
+				`${formatVerificationFailure(verification, options.expectedVersion)}; restored previous ${APP_NAME} binary`,
+			);
+		}
+
+		backupReady = false;
+		// Swap done and verified. On Windows the backup is still the running
+		// process image and cannot be unlinked until this process exits, so a
+		// failure here must NOT fail an otherwise-successful update.
+		await removeBackupBestEffort(options.backupPath);
+		return verification;
+	} catch (err) {
+		if (backupReady) {
+			await unlinkIfExists(options.targetPath);
+			await fs.promises.rename(options.backupPath, options.targetPath);
+		}
+		await unlinkIfExists(options.tempPath);
+		throw err;
+	}
+}
+
+function buildVersionedPackageInstallArgs(expectedVersion: string, nativeTag: string): string[] {
+	const args = [`${PACKAGE}@${expectedVersion}`, `${NATIVES_PACKAGE}@${expectedVersion}`];
+	if (SUPPORTED_NATIVE_TAGS.has(nativeTag)) {
+		args.push(`${NATIVES_PACKAGE}-${nativeTag}@${expectedVersion}`);
+	}
+	return args;
+}
+
+/**
+ * Build the bun argv used to globally install a specific omp version.
+ *
+ * The version is selected by hitting {@link NPM_REGISTRY} directly in
+ * {@link getLatestRelease}, so the install MUST observe the same catalog:
+ *
+ * - `--registry=${NPM_REGISTRY}` pins the install to the official registry
+ *   regardless of the user's bunfig/`.npmrc`. A mirror (corporate proxy,
+ *   Taobao, …) that hasn't yet replicated the release would otherwise reject
+ *   a version the upstream registry already advertises.
+ * - `--no-cache` tells bun to ignore its on-disk manifest snapshot so it
+ *   re-fetches metadata from that registry on every invocation.
+ *
+ * Together these two flags make `omp update` produce exactly the registry
+ * lookup the version check just performed. See #1686.
+ *
+ * Also pins {@link NATIVES_PACKAGE} and the platform-specific
+ * `@oh-my-pi/pi-natives-<tag>` leaf to `expectedVersion`. `bun install -g`
+ * does not reliably refresh transitive `optionalDependencies` when the
+ * top-level package is the only one bumped, so the native addon and its
+ * version sentinel can drift out of sync with the freshly installed
+ * `@oh-my-pi/pi-coding-agent` and the loader aborts at
+ * `validateLoadedBindings` on the next launch
+ * (`The .node file on disk is from a different release than this loader`).
+ * Listing the natives explicitly forces bun to replace them in lock-step.
+ * The leaf is added only on tags the release pipeline actually publishes
+ * ({@link SUPPORTED_NATIVE_TAGS}) so unsupported platforms still fail with
+ * the original "no matching version" message instead of `EBADPLATFORM`.
+ * See #1824.
+ */
+export function buildBunInstallArgs(expectedVersion: string, nativeTag: string = currentNativeTag()): string[] {
+	return [
+		"install",
+		"-g",
+		"--no-cache",
+		`--registry=${NPM_REGISTRY}`,
+		...buildVersionedPackageInstallArgs(expectedVersion, nativeTag),
+	];
+}
+
+/** Build the npm argv used to update npm-managed global installs. */
+export function buildNpmInstallArgs(expectedVersion: string, nativeTag: string = currentNativeTag()): string[] {
+	const args = [
+		"install",
+		"-g",
+		`--registry=${NPM_REGISTRY}`,
+		...buildVersionedPackageInstallArgs(expectedVersion, nativeTag),
+	];
+	return args;
+}
+
+export function buildHomebrewUpdateArgs(force: boolean): string[] {
+	return [force ? "reinstall" : "upgrade", HOMEBREW_FORMULA];
+}
+
+export function buildMiseUpgradeArgs(): string[] {
+	return ["upgrade", MISE_TOOL, "--bump"];
+}
+
+export function buildMiseForceInstallArgs(expectedVersion: string): string[] {
+	return ["install", "--force", `${MISE_TOOL}@${expectedVersion}`];
+}
+
+/**
+ * Update via package manager.
+ */
+async function updateViaBun(expectedVersion: string): Promise<void> {
+	console.log(chalk.dim("Updating via bun..."));
+	const args = buildBunInstallArgs(expectedVersion);
+	const result = await $`bun ${args}`.nothrow();
+	if (result.exitCode !== 0) {
+		throw new Error(`bun install failed with exit code ${result.exitCode}`);
+	}
+
+	await printVerification(expectedVersion);
+	try {
+		const pruneResult = await pruneBunCacheAfterGlobalInstall();
+		if (pruneResult && pruneResult.removedEntries > 0) {
+			console.log(chalk.dim(`Pruned ${pruneResult.removedEntries} stale Bun cache entries`));
+		}
+	} catch (err) {
+		console.log(chalk.yellow(`Warning: could not prune stale Bun cache entries: ${err}`));
+	}
+}
+
+async function updateViaNpm(expectedVersion: string): Promise<void> {
+	console.log(chalk.dim("Updating via npm..."));
+	const args = buildNpmInstallArgs(expectedVersion);
+	const result = await $`npm ${args}`.nothrow();
+	if (result.exitCode !== 0) {
+		throw new Error(`npm install failed with exit code ${result.exitCode}`);
+	}
+
+	await printVerification(expectedVersion);
+}
+
+async function updateViaHomebrew(expectedVersion: string, force: boolean): Promise<void> {
+	console.log(chalk.dim("Updating Homebrew formulae..."));
+	const update = await $`brew update`.nothrow();
+	if (update.exitCode !== 0) {
+		throw new Error(`brew update failed with exit code ${update.exitCode}`);
+	}
+
+	console.log(chalk.dim("Updating via Homebrew..."));
+	const args = buildHomebrewUpdateArgs(force);
+	const result = await $`brew ${args}`.nothrow();
+	if (result.exitCode !== 0) {
+		throw new Error(`brew ${args[0]} failed with exit code ${result.exitCode}`);
+	}
+
+	await printVerification(expectedVersion);
+}
+
+async function updateViaMise(expectedVersion: string, force: boolean): Promise<void> {
+	console.log(chalk.dim("Updating via mise..."));
+	const args = buildMiseUpgradeArgs();
+	const result = await $`mise ${args}`.nothrow();
+	if (result.exitCode !== 0) {
+		throw new Error(`mise upgrade failed with exit code ${result.exitCode}`);
+	}
+
+	if (force) {
+		const forceArgs = buildMiseForceInstallArgs(expectedVersion);
+		const forceResult = await $`mise ${forceArgs}`.nothrow();
+		if (forceResult.exitCode !== 0) {
+			throw new Error(`mise install --force failed with exit code ${forceResult.exitCode}`);
+		}
+	}
+
+	await printVerification(expectedVersion);
+}
+
+/**
+ * Download a release binary to a target path, replacing an existing file.
+ */
+export async function updateViaBinaryAt(
+	targetPath: string,
+	expectedVersion: string,
+	options: {
+		binaryName?: string;
+		fetchImpl?: Fetch;
+		githubToken?: string;
+		verifyInstalledVersion?: typeof verifyInstalledVersion;
+	} = {},
+): Promise<void> {
+	const binaryName = options.binaryName ?? getBinaryName();
+	const tempPath = `${targetPath}.new`;
+	// Unique per attempt: a stale backup from an earlier update may still be
+	// locked (it is the previous process image on Windows), and a fixed name
+	// would force the move-aside rename to overwrite it. pid + timestamp keeps
+	// two forced updates in the same millisecond from colliding.
+	const backupPath = `${targetPath}.${Date.now()}.${process.pid}.bak`;
+	const asset = await getReleaseBinaryAsset(expectedVersion, binaryName, options.fetchImpl, options.githubToken);
+	console.log(chalk.dim(`Downloading ${binaryName}…`));
+	await downloadVerifiedBinary({
+		url: asset.url,
+		targetPath: tempPath,
+		expectedSize: asset.size,
+		expectedDigest: asset.digest,
+		fetchImpl: options.fetchImpl,
+	});
+	console.log(chalk.dim(`Verified ${asset.digest}`));
+
+	console.log(chalk.dim("Installing update..."));
+	await replaceBinaryForUpdate({
+		targetPath,
+		tempPath,
+		backupPath,
+		expectedVersion,
+		verifyInstalledVersion: options.verifyInstalledVersion ?? verifyInstalledVersion,
+	});
+	// Reclaim backups from earlier updates whose owning process has since exited.
+	await sweepStaleBackups(targetPath);
+	printVerifiedVersion(expectedVersion);
+	console.log(chalk.dim(`Restart ${APP_NAME} to use the new version`));
+}
+
+/**
+ * Run the update command.
+ */
+export async function runUpdateCommand(opts: { force: boolean; check: boolean }): Promise<void> {
+	console.log(chalk.dim(`Current version: ${VERSION}`));
+
+	// Check for updates
+	let release: ReleaseInfo;
+	try {
+		release = await getLatestRelease();
+	} catch (err) {
+		console.error(chalk.red(`Failed to check for updates: ${err}`));
+		process.exit(1);
+	}
+
+	const comparison = compareVersions(release.version, VERSION);
+
+	if (comparison <= 0 && !opts.force) {
+		console.log(chalk.green(`${theme.status.success} Already up to date`));
+		return;
+	}
+
+	if (comparison > 0) {
+		console.log(chalk.cyan(`New version available: ${release.version}`));
+	} else {
+		console.log(chalk.yellow(`Forcing reinstall of ${release.version}`));
+	}
+
+	if (opts.check) {
+		// Just check, don't install
+		return;
+	}
+
+	// Choose update method based on the prioritized omp binary in PATH
+	try {
+		const target = await resolveUpdateTarget();
+		if (target.method === "brew") {
+			await updateViaHomebrew(release.version, opts.force);
+		} else if (target.method === "mise") {
+			await updateViaMise(release.version, opts.force);
+		} else if (target.method === "bun") {
+			await updateViaBun(release.version);
+		} else if (target.method === "npm") {
+			await updateViaNpm(release.version);
+		} else {
+			await updateViaBinaryAt(target.path, release.version);
+		}
+	} catch (err) {
+		console.error(chalk.red(`Update failed: ${err}`));
+		process.exit(1);
+	}
+}
+
+/**
+ * Print update command help.
+ */
+export function printUpdateHelp(): void {
+	console.log(`${chalk.bold(`${APP_NAME} update`)} - Check for and install updates
+
+${chalk.bold("Usage:")}
+  ${APP_NAME} update [options]
+
+${chalk.bold("Options:")}
+  -c, --check     Check for updates without installing
+  -f, --force     Force reinstall even if up to date
+  -l, --plugins   Update installed plugins
+
+${chalk.bold("Examples:")}
+  ${APP_NAME} update              Update to latest version
+  ${APP_NAME} update --check      Check if updates are available
+  ${APP_NAME} update --force      Force reinstall
+  ${APP_NAME} update -l           Update installed plugins
+`);
+}