subagent-cli 0.3.0 → 0.3.1

package/src/utils/nativeInstaller/installer.ts

@@ -1,1708 +0,0 @@
-/**
- * Native Installer Implementation
- *
- * This module implements the file-based native installer system described in
- * docs/native-installer.md. It provides:
- * - Directory structure management with symlinks
- * - Version installation and activation
- * - Multi-process safety with locking
- * - Simple fallback mechanism using modification time
- * - Support for both JS and native builds
- */
-
-import { constants as fsConstants, type Stats } from 'fs'
-import {
-  access,
-  chmod,
-  copyFile,
-  lstat,
-  mkdir,
-  readdir,
-  readlink,
-  realpath,
-  rename,
-  rm,
-  rmdir,
-  stat,
-  symlink,
-  unlink,
-  writeFile,
-} from 'fs/promises'
-import { homedir } from 'os'
-import { basename, delimiter, dirname, join, resolve } from 'path'
-import {
-  type AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
-  logEvent,
-} from 'src/services/analytics/index.js'
-import { getMaxVersion, shouldSkipVersion } from '../autoUpdater.js'
-import { registerCleanup } from '../cleanupRegistry.js'
-import { getGlobalConfig, saveGlobalConfig } from '../config.js'
-import { logForDebugging } from '../debug.js'
-import { getCurrentInstallationType } from '../doctorDiagnostic.js'
-import { env } from '../env.js'
-import { envDynamic } from '../envDynamic.js'
-import { isEnvTruthy } from '../envUtils.js'
-import { errorMessage, getErrnoCode, isENOENT, toError } from '../errors.js'
-import { execFileNoThrowWithCwd } from '../execFileNoThrow.js'
-import { getShellType } from '../localInstaller.js'
-import * as lockfile from '../lockfile.js'
-import { logError } from '../log.js'
-import { gt, gte } from '../semver.js'
-import {
-  filterClaudeAliases,
-  getShellConfigPaths,
-  readFileLines,
-  writeFileLines,
-} from '../shellConfig.js'
-import { sleep } from '../sleep.js'
-import {
-  getUserBinDir,
-  getXDGCacheHome,
-  getXDGDataHome,
-  getXDGStateHome,
-} from '../xdg.js'
-import { downloadVersion, getLatestVersion } from './download.js'
-import {
-  acquireProcessLifetimeLock,
-  cleanupStaleLocks,
-  isLockActive,
-  isPidBasedLockingEnabled,
-  readLockContent,
-  withLock,
-} from './pidLock.js'
-
-export const VERSION_RETENTION_COUNT = 2
-
-// 7 days in milliseconds - used for mtime-based lock stale timeout.
-// This is long enough to survive laptop sleep durations while still
-// allowing cleanup of abandoned locks from crashed processes within a reasonable time.
-const LOCK_STALE_MS = 7 * 24 * 60 * 60 * 1000
-
-export type SetupMessage = {
-  message: string
-  userActionRequired: boolean
-  type: 'path' | 'alias' | 'info' | 'error'
-}
-
-export function getPlatform(): string {
-  // Use env.platform which already handles platform detection and defaults to 'linux'
-  const os = env.platform
-
-  const arch =
-    process.arch === 'x64' ? 'x64' : process.arch === 'arm64' ? 'arm64' : null
-
-  if (!arch) {
-    const error = new Error(`Unsupported architecture: ${process.arch}`)
-    logForDebugging(
-      `Native installer does not support architecture: ${process.arch}`,
-      { level: 'error' },
-    )
-    throw error
-  }
-
-  // Check for musl on Linux and adjust platform accordingly
-  if (os === 'linux' && envDynamic.isMuslEnvironment()) {
-    return `linux-${arch}-musl`
-  }
-
-  return `${os}-${arch}`
-}
-
-export function getBinaryName(platform: string): string {
-  return platform.startsWith('win32') ? 'claude.exe' : 'claude'
-}
-
-function getBaseDirectories() {
-  const platform = getPlatform()
-  const executableName = getBinaryName(platform)
-
-  return {
-    // Data directories (permanent storage)
-    versions: join(getXDGDataHome(), 'claude', 'versions'),
-
-    // Cache directories (can be deleted)
-    staging: join(getXDGCacheHome(), 'claude', 'staging'),
-
-    // State directories
-    locks: join(getXDGStateHome(), 'claude', 'locks'),
-
-    // User bin
-    executable: join(getUserBinDir(), executableName),
-  }
-}
-
-async function isPossibleClaudeBinary(filePath: string): Promise<boolean> {
-  try {
-    const stats = await stat(filePath)
-    // before download, the version lock file (located at the same filePath) will be size 0
-    // also, we allow small sizes because we want to treat small wrapper scripts as valid
-    if (!stats.isFile() || stats.size === 0) {
-      return false
-    }
-
-    // Check if file is executable. Note: On Windows, this relies on file extensions
-    // (.exe, .bat, .cmd) and ACL permissions rather than Unix permission bits,
-    // so it may not work perfectly for all executable files on Windows.
-    await access(filePath, fsConstants.X_OK)
-    return true
-  } catch {
-    return false
-  }
-}
-
-async function getVersionPaths(version: string) {
-  const dirs = getBaseDirectories()
-
-  // Create directories, but not the executable path (which is a file)
-  const dirsToCreate = [dirs.versions, dirs.staging, dirs.locks]
-  await Promise.all(dirsToCreate.map(dir => mkdir(dir, { recursive: true })))
-
-  // Ensure parent directory of executable exists
-  const executableParentDir = dirname(dirs.executable)
-  await mkdir(executableParentDir, { recursive: true })
-
-  const installPath = join(dirs.versions, version)
-
-  // Create an empty file if it doesn't exist
-  try {
-    await stat(installPath)
-  } catch {
-    await writeFile(installPath, '', { encoding: 'utf8' })
-  }
-
-  return {
-    stagingPath: join(dirs.staging, version),
-    installPath,
-  }
-}
-
-// Execute a callback while holding a lock on a version file
-// Returns false if the file is already locked, true if callback executed
-async function tryWithVersionLock(
-  versionFilePath: string,
-  callback: () => void | Promise<void>,
-  retries = 0,
-): Promise<boolean> {
-  const dirs = getBaseDirectories()
-
-  const lockfilePath = getLockFilePathFromVersionPath(dirs, versionFilePath)
-
-  // Ensure the locks directory exists
-  await mkdir(dirs.locks, { recursive: true })
-
-  if (isPidBasedLockingEnabled()) {
-    // Use PID-based locking with optional retries
-    let attempts = 0
-    const maxAttempts = retries + 1
-    const minTimeout = retries > 0 ? 1000 : 100
-    const maxTimeout = retries > 0 ? 5000 : 500
-
-    while (attempts < maxAttempts) {
-      const success = await withLock(
-        versionFilePath,
-        lockfilePath,
-        async () => {
-          try {
-            await callback()
-          } catch (error) {
-            logError(error)
-            throw error
-          }
-        },
-      )
-
-      if (success) {
-        logEvent('tengu_version_lock_acquired', {
-          is_pid_based: true,
-          is_lifetime_lock: false,
-          attempts: attempts + 1,
-        })
-        return true
-      }
-
-      attempts++
-      if (attempts < maxAttempts) {
-        // Wait before retrying with exponential backoff
-        const timeout = Math.min(
-          minTimeout * Math.pow(2, attempts - 1),
-          maxTimeout,
-        )
-        await sleep(timeout)
-      }
-    }
-
-    logEvent('tengu_version_lock_failed', {
-      is_pid_based: true,
-      is_lifetime_lock: false,
-      attempts: maxAttempts,
-    })
-    logLockAcquisitionError(
-      versionFilePath,
-      new Error('Lock held by another process'),
-    )
-    return false
-  }
-
-  // Use mtime-based locking (proper-lockfile) with 30-day stale timeout
-  let release: (() => Promise<void>) | null = null
-  try {
-    // Lock acquisition phase - catch lock errors and return false
-    // Use 30 days for stale to match lockCurrentVersion() - this ensures we never
-    // consider a running process's lock as stale during normal usage (including
-    // laptop sleep). 30 days allows eventual cleanup of abandoned locks from
-    // crashed processes while being long enough for any realistic session.
-    try {
-      release = await lockfile.lock(versionFilePath, {
-        stale: LOCK_STALE_MS,
-        retries: {
-          retries,
-          minTimeout: retries > 0 ? 1000 : 100,
-          maxTimeout: retries > 0 ? 5000 : 500,
-        },
-        lockfilePath,
-        // Handle lock compromise gracefully to prevent unhandled rejections
-        // This can happen if another process deletes the lock directory while we hold it
-        onCompromised: (err: Error) => {
-          logForDebugging(
-            `NON-FATAL: Version lock was compromised during operation: ${err.message}`,
-            { level: 'info' },
-          )
-        },
-      })
-    } catch (lockError) {
-      logEvent('tengu_version_lock_failed', {
-        is_pid_based: false,
-        is_lifetime_lock: false,
-      })
-      logLockAcquisitionError(versionFilePath, lockError)
-      return false
-    }
-
-    // Operation phase - log errors but let them propagate
-    try {
-      await callback()
-      logEvent('tengu_version_lock_acquired', {
-        is_pid_based: false,
-        is_lifetime_lock: false,
-      })
-      return true
-    } catch (error) {
-      logError(error)
-      throw error
-    }
-  } finally {
-    if (release) {
-      await release()
-    }
-  }
-}
-
-async function atomicMoveToInstallPath(
-  stagedBinaryPath: string,
-  installPath: string,
-) {
-  // Create installation directory if it doesn't exist
-  await mkdir(dirname(installPath), { recursive: true })
-
-  // Move from staging to final location atomically
-  const tempInstallPath = `${installPath}.tmp.${process.pid}.${Date.now()}`
-
-  try {
-    // Copy to temp next to install path, then rename. A direct rename from staging
-    // would fail with EXDEV if staging and install are on different filesystems.
-    await copyFile(stagedBinaryPath, tempInstallPath)
-    await chmod(tempInstallPath, 0o755)
-    await rename(tempInstallPath, installPath)
-    logForDebugging(`Atomically installed binary to ${installPath}`)
-  } catch (error) {
-    // Clean up temp file if it exists
-    try {
-      await unlink(tempInstallPath)
-    } catch {
-      // Ignore cleanup errors
-    }
-    throw error
-  }
-}
-
-async function installVersionFromPackage(
-  stagingPath: string,
-  installPath: string,
-) {
-  try {
-    // Extract binary from npm package structure in staging
-    const nodeModulesDir = join(stagingPath, 'node_modules', '@anthropic-ai')
-    const entries = await readdir(nodeModulesDir)
-    const nativePackage = entries.find((entry: string) =>
-      entry.startsWith('claude-cli-native-'),
-    )
-
-    if (!nativePackage) {
-      logEvent('tengu_native_install_package_failure', {
-        stage_find_package: true,
-        error_package_not_found: true,
-      })
-      const error = new Error('Could not find platform-specific native package')
-      throw error
-    }
-
-    const stagedBinaryPath = join(nodeModulesDir, nativePackage, 'cli')
-
-    try {
-      await stat(stagedBinaryPath)
-    } catch {
-      logEvent('tengu_native_install_package_failure', {
-        stage_binary_exists: true,
-        error_binary_not_found: true,
-      })
-      const error = new Error('Native binary not found in staged package')
-      throw error
-    }
-
-    await atomicMoveToInstallPath(stagedBinaryPath, installPath)
-
-    // Clean up staging directory
-    await rm(stagingPath, { recursive: true, force: true })
-
-    logEvent('tengu_native_install_package_success', {})
-  } catch (error) {
-    // Log if not already logged above
-    const msg = errorMessage(error)
-    if (
-      !msg.includes('Could not find platform-specific') &&
-      !msg.includes('Native binary not found')
-    ) {
-      logEvent('tengu_native_install_package_failure', {
-        stage_atomic_move: true,
-        error_move_failed: true,
-      })
-    }
-    logError(toError(error))
-    throw error
-  }
-}
-
-async function installVersionFromBinary(
-  stagingPath: string,
-  installPath: string,
-) {
-  try {
-    // For direct binary downloads (GCS, generic bucket), the binary is directly in staging
-    const platform = getPlatform()
-    const binaryName = getBinaryName(platform)
-    const stagedBinaryPath = join(stagingPath, binaryName)
-
-    try {
-      await stat(stagedBinaryPath)
-    } catch {
-      logEvent('tengu_native_install_binary_failure', {
-        stage_binary_exists: true,
-        error_binary_not_found: true,
-      })
-      const error = new Error('Staged binary not found')
-      throw error
-    }
-
-    await atomicMoveToInstallPath(stagedBinaryPath, installPath)
-
-    // Clean up staging directory
-    await rm(stagingPath, { recursive: true, force: true })
-
-    logEvent('tengu_native_install_binary_success', {})
-  } catch (error) {
-    if (!errorMessage(error).includes('Staged binary not found')) {
-      logEvent('tengu_native_install_binary_failure', {
-        stage_atomic_move: true,
-        error_move_failed: true,
-      })
-    }
-    logError(toError(error))
-    throw error
-  }
-}
-
-async function installVersion(
-  stagingPath: string,
-  installPath: string,
-  downloadType: 'npm' | 'binary',
-) {
-  // Use the explicit download type instead of guessing
-  if (downloadType === 'npm') {
-    await installVersionFromPackage(stagingPath, installPath)
-  } else {
-    await installVersionFromBinary(stagingPath, installPath)
-  }
-}
-
-/**
- * Performs the core update operation: download (if needed), install, and update symlink.
- * Returns whether a new install was performed (vs just updating symlink).
- */
-async function performVersionUpdate(
-  version: string,
-  forceReinstall: boolean,
-): Promise<boolean> {
-  const { stagingPath: baseStagingPath, installPath } =
-    await getVersionPaths(version)
-  const { executable: executablePath } = getBaseDirectories()
-
-  // For lockless updates, use a unique staging path to avoid conflicts between concurrent downloads
-  const stagingPath = isEnvTruthy(process.env.ENABLE_LOCKLESS_UPDATES)
-    ? `${baseStagingPath}.${process.pid}.${Date.now()}`
-    : baseStagingPath
-
-  // Only download if not already installed (or if force reinstall)
-  const needsInstall = !(await versionIsAvailable(version)) || forceReinstall
-  if (needsInstall) {
-    logForDebugging(
-      forceReinstall
-        ? `Force reinstalling native installer version ${version}`
-        : `Downloading native installer version ${version}`,
-    )
-    const downloadType = await downloadVersion(version, stagingPath)
-    await installVersion(stagingPath, installPath, downloadType)
-  } else {
-    logForDebugging(`Version ${version} already installed, updating symlink`)
-  }
-
-  // Create direct symlink from ~/.local/bin/claude to the version binary
-  await removeDirectoryIfEmpty(executablePath)
-  await updateSymlink(executablePath, installPath)
-
-  // Verify the executable was actually created/updated
-  if (!(await isPossibleClaudeBinary(executablePath))) {
-    let installPathExists = false
-    try {
-      await stat(installPath)
-      installPathExists = true
-    } catch {
-      // installPath doesn't exist
-    }
-    throw new Error(
-      `Failed to create executable at ${executablePath}. ` +
-        `Source file exists: ${installPathExists}. ` +
-        `Check write permissions to ${executablePath}.`,
-    )
-  }
-  return needsInstall
-}
-
-async function versionIsAvailable(version: string): Promise<boolean> {
-  const { installPath } = await getVersionPaths(version)
-  return isPossibleClaudeBinary(installPath)
-}
-
-async function updateLatest(
-  channelOrVersion: string,
-  forceReinstall: boolean = false,
-): Promise<{
-  success: boolean
-  latestVersion: string
-  lockFailed?: boolean
-  lockHolderPid?: number
-}> {
-  const startTime = Date.now()
-  let version = await getLatestVersion(channelOrVersion)
-  const { executable: executablePath } = getBaseDirectories()
-
-  logForDebugging(`Checking for native installer update to version ${version}`)
-
-  // Check if max version is set (server-side kill switch for auto-updates)
-  if (!forceReinstall) {
-    const maxVersion = await getMaxVersion()
-    if (maxVersion && gt(version, maxVersion)) {
-      logForDebugging(
-        `Native installer: maxVersion ${maxVersion} is set, capping update from ${version} to ${maxVersion}`,
-      )
-      // If we're already at or above maxVersion, skip the update entirely
-      if (gte(MACRO.VERSION, maxVersion)) {
-        logForDebugging(
-          `Native installer: current version ${MACRO.VERSION} is already at or above maxVersion ${maxVersion}, skipping update`,
-        )
-        logEvent('tengu_native_update_skipped_max_version', {
-          latency_ms: Date.now() - startTime,
-          max_version:
-            maxVersion as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
-          available_version:
-            version as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
-        })
-        return { success: true, latestVersion: version }
-      }
-      version = maxVersion
-    }
-  }
-
-  // Early exit: if we're already running this exact version AND both the version binary
-  // and executable exist and are valid. We need to proceed if the executable doesn't exist,
-  // is invalid (e.g., empty/corrupted from a failed install), or we're running via npx.
-  if (
-    !forceReinstall &&
-    version === MACRO.VERSION &&
-    (await versionIsAvailable(version)) &&
-    (await isPossibleClaudeBinary(executablePath))
-  ) {
-    logForDebugging(`Found ${version} at ${executablePath}, skipping install`)
-    logEvent('tengu_native_update_complete', {
-      latency_ms: Date.now() - startTime,
-      was_new_install: false,
-      was_force_reinstall: false,
-      was_already_running: true,
-    })
-    return { success: true, latestVersion: version }
-  }
-
-  // Check if this version should be skipped due to minimumVersion setting
-  if (!forceReinstall && shouldSkipVersion(version)) {
-    logEvent('tengu_native_update_skipped_minimum_version', {
-      latency_ms: Date.now() - startTime,
-      target_version:
-        version as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
-    })
-    return { success: true, latestVersion: version }
-  }
-
-  // Track if we're actually installing or just symlinking
-  let wasNewInstall = false
-  let latencyMs: number
-
-  if (isEnvTruthy(process.env.ENABLE_LOCKLESS_UPDATES)) {
-    // Lockless: rely on atomic operations, errors propagate
-    wasNewInstall = await performVersionUpdate(version, forceReinstall)
-    latencyMs = Date.now() - startTime
-  } else {
-    // Lock-based updates
-    const { installPath } = await getVersionPaths(version)
-    // If force reinstall, remove any existing lock to bypass stale locks
-    if (forceReinstall) {
-      await forceRemoveLock(installPath)
-    }
-
-    const lockAcquired = await tryWithVersionLock(
-      installPath,
-      async () => {
-        wasNewInstall = await performVersionUpdate(version, forceReinstall)
-      },
-      3, // retries
-    )
-
-    latencyMs = Date.now() - startTime
-
-    // Lock acquisition failed - get lock holder PID for error message
-    if (!lockAcquired) {
-      const dirs = getBaseDirectories()
-      let lockHolderPid: number | undefined
-      if (isPidBasedLockingEnabled()) {
-        const lockfilePath = getLockFilePathFromVersionPath(dirs, installPath)
-        if (isLockActive(lockfilePath)) {
-          lockHolderPid = readLockContent(lockfilePath)?.pid
-        }
-      }
-      logEvent('tengu_native_update_lock_failed', {
-        latency_ms: latencyMs,
-        lock_holder_pid: lockHolderPid,
-      })
-      return {
-        success: false,
-        latestVersion: version,
-        lockFailed: true,
-        lockHolderPid,
-      }
-    }
-  }
-
-  logEvent('tengu_native_update_complete', {
-    latency_ms: latencyMs,
-    was_new_install: wasNewInstall,
-    was_force_reinstall: forceReinstall,
-  })
-  logForDebugging(`Successfully updated to version ${version}`)
-  return { success: true, latestVersion: version }
-}
-
-// Exported for testing
-export async function removeDirectoryIfEmpty(path: string): Promise<void> {
-  // rmdir alone handles all cases: ENOTDIR if path is a file, ENOTEMPTY if
-  // directory is non-empty, ENOENT if missing. No need to stat+readdir first.
-  try {
-    await rmdir(path)
-    logForDebugging(`Removed empty directory at ${path}`)
-  } catch (error) {
-    const code = getErrnoCode(error)
-    // Expected cases (not-a-dir, missing, not-empty) — silently skip.
-    // ENOTDIR is the normal path: executablePath is typically a symlink.
-    if (code !== 'ENOTDIR' && code !== 'ENOENT' && code !== 'ENOTEMPTY') {
-      logForDebugging(`Could not remove directory at ${path}: ${error}`)
-    }
-  }
-}
-
-async function updateSymlink(
-  symlinkPath: string,
-  targetPath: string,
-): Promise<boolean> {
-  const platform = getPlatform()
-  const isWindows = platform.startsWith('win32')
-
-  // On Windows, directly copy the executable instead of creating a symlink
-  if (isWindows) {
-    try {
-      // Ensure parent directory exists
-      const parentDir = dirname(symlinkPath)
-      await mkdir(parentDir, { recursive: true })
-
-      // Check if file already exists and has same content
-      let existingStats: Stats | undefined
-      try {
-        existingStats = await stat(symlinkPath)
-      } catch {
-        // symlinkPath doesn't exist
-      }
-
-      if (existingStats) {
-        try {
-          const targetStats = await stat(targetPath)
-          // If sizes match, assume files are the same (avoid reading large files)
-          if (existingStats.size === targetStats.size) {
-            return false
-          }
-        } catch {
-          // Continue with copy if we can't compare
-        }
-        // Use rename strategy to handle file locking on Windows
-        // Rename always works even for running executables, unlike delete
-        const oldFileName = `${symlinkPath}.old.${Date.now()}`
-        await rename(symlinkPath, oldFileName)
-
-        // Try to copy new executable, with rollback on failure
-        try {
-          await copyFile(targetPath, symlinkPath)
-          // Success - try immediate cleanup of old file (non-blocking)
-          try {
-            await unlink(oldFileName)
-          } catch {
-            // File still running - ignore, Windows will clean up eventually
-          }
-        } catch (copyError) {
-          // Copy failed - restore the old executable
-          try {
-            await rename(oldFileName, symlinkPath)
-          } catch (restoreError) {
-            // Critical: User left without working executable - prioritize restore error
-            const errorWithCause = new Error(
-              `Failed to restore old executable: ${restoreError}`,
-              { cause: copyError },
-            )
-            logError(errorWithCause)
-            throw errorWithCause
-          }
-          throw copyError
-        }
-      } else {
-        // First-time installation (no existing file to rename)
-        // Copy the executable directly; handle ENOENT from copyFile itself
-        // rather than a stat() pre-check (avoids TOCTOU + extra syscall)
-        try {
-          await copyFile(targetPath, symlinkPath)
-        } catch (e) {
-          if (isENOENT(e)) {
-            throw new Error(`Source file does not exist: ${targetPath}`)
-          }
-          throw e
-        }
-      }
-      // chmod is not needed on Windows - executability is determined by .exe extension
-      return true
-    } catch (error) {
-      logError(
-        new Error(
-          `Failed to copy executable from ${targetPath} to ${symlinkPath}: ${error}`,
-        ),
-      )
-      return false
-    }
-  }
-
-  // For non-Windows platforms, use symlinks as before
-  // Ensure parent directory exists (same as Windows path above)
-  const parentDir = dirname(symlinkPath)
-  try {
-    await mkdir(parentDir, { recursive: true })
-    logForDebugging(`Created directory ${parentDir} for symlink`)
-  } catch (mkdirError) {
-    logError(
-      new Error(`Failed to create directory ${parentDir}: ${mkdirError}`),
-    )
-    return false
-  }
-
-  // Check if symlink already exists and points to the correct target
-  try {
-    let symlinkExists = false
-    try {
-      await stat(symlinkPath)
-      symlinkExists = true
-    } catch {
-      // symlinkPath doesn't exist
-    }
-
-    if (symlinkExists) {
-      try {
-        const currentTarget = await readlink(symlinkPath)
-        const resolvedCurrentTarget = resolve(
-          dirname(symlinkPath),
-          currentTarget,
-        )
-        const resolvedTargetPath = resolve(targetPath)
-
-        if (resolvedCurrentTarget === resolvedTargetPath) {
-          return false
-        }
-      } catch {
-        // Path exists but is not a symlink - will remove it below
-      }
-
-      // Remove existing file/symlink before creating new one
-      await unlink(symlinkPath)
-    }
-  } catch (error) {
-    logError(new Error(`Failed to check/remove existing symlink: ${error}`))
-  }
-
-  // Use atomic rename to avoid race conditions. Create symlink with temporary name
-  // then atomically rename to final name. This ensures the symlink always exists
-  // and is always valid, even with concurrent updates.
-  const tempSymlink = `${symlinkPath}.tmp.${process.pid}.${Date.now()}`
-  try {
-    await symlink(targetPath, tempSymlink)
-
-    // Atomically rename to final name (replaces existing)
-    await rename(tempSymlink, symlinkPath)
-    logForDebugging(
-      `Atomically updated symlink ${symlinkPath} -> ${targetPath}`,
-    )
-    return true
-  } catch (error) {
-    // Clean up temp symlink if it exists
-    try {
-      await unlink(tempSymlink)
-    } catch {
-      // Ignore cleanup errors
-    }
-    logError(
-      new Error(
-        `Failed to create symlink from ${symlinkPath} to ${targetPath}: ${error}`,
-      ),
-    )
-    return false
-  }
-}
-
-export async function checkInstall(
-  force: boolean = false,
-): Promise<SetupMessage[]> {
-  // Skip all installation checks if disabled via environment variable
-  if (isEnvTruthy(process.env.DISABLE_INSTALLATION_CHECKS)) {
-    return []
-  }
-
-  // Get the actual installation type and config
-  const installationType = await getCurrentInstallationType()
-
-  // Skip checks for development builds - config.installMethod from a previous
-  // native installation shouldn't trigger warnings when running dev builds
-  if (installationType === 'development') {
-    return []
-  }
-
-  const config = getGlobalConfig()
-
-  // Only show warnings if:
-  // 1. User is actually running from native installation, OR
-  // 2. User has explicitly set installMethod to 'native' in config (they're trying to use native)
-  // 3. force is true (used during installation process)
-  const shouldCheckNative =
-    force || installationType === 'native' || config.installMethod === 'native'
-
-  if (!shouldCheckNative) {
-    return []
-  }
-
-  const dirs = getBaseDirectories()
-  const messages: SetupMessage[] = []
-  const localBinDir = dirname(dirs.executable)
-  const resolvedLocalBinPath = resolve(localBinDir)
-  const platform = getPlatform()
-  const isWindows = platform.startsWith('win32')
-
-  // Check if bin directory exists
-  try {
-    await access(localBinDir)
-  } catch {
-    messages.push({
-      message: `installMethod is native, but directory ${localBinDir} does not exist`,
-      userActionRequired: true,
-      type: 'error',
-    })
-  }
-
-  // Check if claude executable exists and is valid.
-  // On non-Windows, call readlink directly and route errno — ENOENT means
-  // the executable is missing, EINVAL means it exists but isn't a symlink.
-  // This avoids an access()→readlink() TOCTOU where deletion between the
-  // two calls produces a misleading "Not a symlink" diagnostic.
-  // isPossibleClaudeBinary stats the path internally, so we don't pre-check
-  // with access() — that would be a TOCTOU between access and the stat.
-  if (isWindows) {
-    // On Windows it's a copied executable, not a symlink
-    if (!(await isPossibleClaudeBinary(dirs.executable))) {
-      messages.push({
-        message: `installMethod is native, but claude command is missing or invalid at ${dirs.executable}`,
-        userActionRequired: true,
-        type: 'error',
-      })
-    }
-  } else {
-    try {
-      const target = await readlink(dirs.executable)
-      const absoluteTarget = resolve(dirname(dirs.executable), target)
-      if (!(await isPossibleClaudeBinary(absoluteTarget))) {
-        messages.push({
-          message: `Claude symlink points to missing or invalid binary: ${target}`,
-          userActionRequired: true,
-          type: 'error',
-        })
-      }
-    } catch (e) {
-      if (isENOENT(e)) {
-        messages.push({
-          message: `installMethod is native, but claude command not found at ${dirs.executable}`,
-          userActionRequired: true,
-          type: 'error',
-        })
-      } else {
-        // EINVAL (not a symlink) or other — check as regular binary
-        if (!(await isPossibleClaudeBinary(dirs.executable))) {
-          messages.push({
-            message: `${dirs.executable} exists but is not a valid Claude binary`,
-            userActionRequired: true,
-            type: 'error',
-          })
-        }
-      }
-    }
-  }
-
-  // Check if bin directory is in PATH
-  const isInCurrentPath = (process.env.PATH || '')
-    .split(delimiter)
-    .some(entry => {
-      try {
-        const resolvedEntry = resolve(entry)
-        // On Windows, perform case-insensitive comparison for paths
-        if (isWindows) {
-          return (
-            resolvedEntry.toLowerCase() === resolvedLocalBinPath.toLowerCase()
-          )
-        }
-        return resolvedEntry === resolvedLocalBinPath
-      } catch {
-        return false
-      }
-    })
-
-  if (!isInCurrentPath) {
-    if (isWindows) {
-      // Windows-specific PATH instructions
-      const windowsBinPath = localBinDir.replace(/\//g, '\\')
-      messages.push({
-        message: `Native installation exists but ${windowsBinPath} is not in your PATH. Add it by opening: System Properties → Environment Variables → Edit User PATH → New → Add the path above. Then restart your terminal.`,
-        userActionRequired: true,
-        type: 'path',
-      })
-    } else {
-      // Unix-style PATH instructions
-      const shellType = getShellType()
-      const configPaths = getShellConfigPaths()
-      const configFile = configPaths[shellType as keyof typeof configPaths]
-      const displayPath = configFile
-        ? configFile.replace(homedir(), '~')
-        : 'your shell config file'
-
-      messages.push({
-        message: `Native installation exists but ~/.local/bin is not in your PATH. Run:\n\necho 'export PATH="$HOME/.local/bin:$PATH"' >> ${displayPath} && source ${displayPath}`,
-        userActionRequired: true,
-        type: 'path',
-      })
-    }
-  }
-
-  return messages
-}
-
-type InstallLatestResult = {
-  latestVersion: string | null
-  wasUpdated: boolean
-  lockFailed?: boolean
-  lockHolderPid?: number
-}
-
-// In-process singleflight guard. NativeAutoUpdater remounts whenever the
-// prompt suggestions overlay toggles (PromptInput.tsx:2916), and the
-// isUpdating guard does not survive the remount. Each remount kicked off a
-// fresh 271MB binary download while previous ones were still in flight.
-// Telemetry: session 42fed33f saw arrayBuffers climb to 91GB at ~650MB/s.
-let inFlightInstall: Promise<InstallLatestResult> | null = null
-
-export function installLatest(
-  channelOrVersion: string,
-  forceReinstall: boolean = false,
-): Promise<InstallLatestResult> {
-  if (forceReinstall) {
-    return installLatestImpl(channelOrVersion, forceReinstall)
-  }
-  if (inFlightInstall) {
-    logForDebugging('installLatest: joining in-flight call')
-    return inFlightInstall
-  }
-  const promise = installLatestImpl(channelOrVersion, forceReinstall)
-  inFlightInstall = promise
-  const clear = (): void => {
-    inFlightInstall = null
-  }
-  void promise.then(clear, clear)
-  return promise
-}
-
-async function installLatestImpl(
-  channelOrVersion: string,
-  forceReinstall: boolean = false,
-): Promise<InstallLatestResult> {
-  const updateResult = await updateLatest(channelOrVersion, forceReinstall)
-
-  if (!updateResult.success) {
-    return {
-      latestVersion: null,
-      wasUpdated: false,
-      lockFailed: updateResult.lockFailed,
-      lockHolderPid: updateResult.lockHolderPid,
-    }
-  }
-
-  // Installation succeeded (early return above covers failure). Mark as native
-  // and disable legacy auto-updater to protect symlinks.
-  const config = getGlobalConfig()
-  if (config.installMethod !== 'native') {
-    saveGlobalConfig(current => ({
-      ...current,
-      installMethod: 'native',
-      // Disable legacy auto-updater to prevent npm sessions from deleting native symlinks.
-      // Native installations use NativeAutoUpdater instead, which respects native installation.
-      autoUpdates: false,
-      // Mark this as protection-based, not user preference
-      autoUpdatesProtectedForNative: true,
-    }))
-    logForDebugging(
-      'Native installer: Set installMethod to "native" and disabled legacy auto-updater for protection',
-    )
-  }
-
-  void cleanupOldVersions()
-
-  return {
-    latestVersion: updateResult.latestVersion,
-    wasUpdated: updateResult.success,
-    lockFailed: false,
-  }
-}
-
-async function getVersionFromSymlink(
-  symlinkPath: string,
-): Promise<string | null> {
-  try {
-    const target = await readlink(symlinkPath)
-    const absoluteTarget = resolve(dirname(symlinkPath), target)
-    if (await isPossibleClaudeBinary(absoluteTarget)) {
-      return absoluteTarget
-    }
-  } catch {
-    // Not a symlink / doesn't exist / target doesn't exist
-  }
-  return null
-}
-
-function getLockFilePathFromVersionPath(
-  dirs: ReturnType<typeof getBaseDirectories>,
-  versionPath: string,
-) {
-  const versionName = basename(versionPath)
-  return join(dirs.locks, `${versionName}.lock`)
-}
-
-/**
- * Acquire a lock on the current running version to prevent it from being deleted
- * This lock is held for the entire lifetime of the process
- *
- * Uses PID-based locking (when enabled) which can immediately detect crashed processes
- * (unlike mtime-based locking which requires a 30-day timeout)
- */
-export async function lockCurrentVersion(): Promise<void> {
-  const dirs = getBaseDirectories()
-
-  // Only lock if we're running from the versions directory
-  if (!process.execPath.includes(dirs.versions)) {
-    return
-  }
-
-  const versionPath = resolve(process.execPath)
-  try {
-    const lockfilePath = getLockFilePathFromVersionPath(dirs, versionPath)
-
-    // Ensure locks directory exists
-    await mkdir(dirs.locks, { recursive: true })
-
-    if (isPidBasedLockingEnabled()) {
-      // Acquire PID-based lock and hold it for the process lifetime
-      // PID-based locking allows immediate detection of crashed processes
-      // while still surviving laptop sleep (process is suspended but PID exists)
-      const acquired = await acquireProcessLifetimeLock(
-        versionPath,
-        lockfilePath,
-      )
-
-      if (!acquired) {
-        logEvent('tengu_version_lock_failed', {
-          is_pid_based: true,
-          is_lifetime_lock: true,
-        })
-        logLockAcquisitionError(
-          versionPath,
-          new Error('Lock already held by another process'),
-        )
-        return
-      }
-
-      logEvent('tengu_version_lock_acquired', {
-        is_pid_based: true,
-        is_lifetime_lock: true,
-      })
-      logForDebugging(`Acquired PID lock on running version: ${versionPath}`)
-    } else {
-      // Acquire mtime-based lock and never release it (until process exits)
-      // Use 30 days for stale to prevent the lock from being considered stale during
-      // normal usage. This is critical because laptop sleep suspends the process,
-      // stopping the mtime heartbeat. 30 days is long enough for any realistic session
-      // while still allowing eventual cleanup of abandoned locks.
-      let release: (() => Promise<void>) | undefined
-      try {
-        release = await lockfile.lock(versionPath, {
-          stale: LOCK_STALE_MS,
-          retries: 0, // Don't retry - if we can't lock, that's fine
-          lockfilePath,
-          // Handle lock compromise gracefully (e.g., if another process deletes the lock directory)
-          onCompromised: (err: Error) => {
-            logForDebugging(
-              `NON-FATAL: Lock on running version was compromised: ${err.message}`,
-              { level: 'info' },
-            )
-          },
-        })
-        logEvent('tengu_version_lock_acquired', {
-          is_pid_based: false,
-          is_lifetime_lock: true,
-        })
-        logForDebugging(
-          `Acquired mtime-based lock on running version: ${versionPath}`,
-        )
-
-        // Release lock explicitly; proper-lockfile's cleanup is unreliable with signal-exit v3+v4
-        registerCleanup(async () => {
-          try {
-            await release?.()
-          } catch {
-            // Lock may already be released
-          }
-        })
-      } catch (lockError) {
-        if (isENOENT(lockError)) {
-          logForDebugging(
-            `Cannot lock current version - file does not exist: ${versionPath}`,
-            { level: 'info' },
-          )
-          return
-        }
-        logEvent('tengu_version_lock_failed', {
-          is_pid_based: false,
-          is_lifetime_lock: true,
-        })
-        logLockAcquisitionError(versionPath, lockError)
-        return
-      }
-    }
-  } catch (error) {
-    if (isENOENT(error)) {
-      logForDebugging(
-        `Cannot lock current version - file does not exist: ${versionPath}`,
-        { level: 'info' },
-      )
-      return
-    }
-    // We fallback to previous behavior where we don't acquire a lock on a running version
-    // This ~mostly works but using native binaries like ripgrep will fail
-    logForDebugging(
-      `NON-FATAL: Failed to lock current version during execution ${errorMessage(error)}`,
-      { level: 'info' },
-    )
-  }
-}
-
-function logLockAcquisitionError(versionPath: string, lockError: unknown) {
-  logError(
-    new Error(
-      `NON-FATAL: Lock acquisition failed for ${versionPath} (expected in multi-process scenarios)`,
-      { cause: lockError },
-    ),
-  )
-}
-
-/**
- * Force-remove a lock file for a given version path.
- * Used when --force is specified to bypass stale locks.
- */
-async function forceRemoveLock(versionFilePath: string): Promise<void> {
-  const dirs = getBaseDirectories()
-  const lockfilePath = getLockFilePathFromVersionPath(dirs, versionFilePath)
-
-  try {
-    await unlink(lockfilePath)
-    logForDebugging(`Force-removed lock file at ${lockfilePath}`)
-  } catch (error) {
-    // Log but don't throw - we'll try to acquire the lock anyway
-    logForDebugging(`Failed to force-remove lock file: ${errorMessage(error)}`)
-  }
-}
-
-export async function cleanupOldVersions(): Promise<void> {
-  // Yield to ensure we don't block startup
-  await Promise.resolve()
-
-  const dirs = getBaseDirectories()
-  const oneHourAgo = Date.now() - 3600000
-
-  // Clean up old renamed executables on Windows (no longer running at startup)
-  if (getPlatform().startsWith('win32')) {
-    const executableDir = dirname(dirs.executable)
-    try {
-      const files = await readdir(executableDir)
-      let cleanedCount = 0
-      for (const file of files) {
-        if (!/^claude\.exe\.old\.\d+$/.test(file)) continue
-        try {
-          await unlink(join(executableDir, file))
-          cleanedCount++
-        } catch {
-          // File might still be in use by another process
-        }
-      }
-      if (cleanedCount > 0) {
-        logForDebugging(
-          `Cleaned up ${cleanedCount} old Windows executables on startup`,
-        )
-      }
-    } catch (error) {
-      if (!isENOENT(error)) {
-        logForDebugging(`Failed to clean up old Windows executables: ${error}`)
-      }
-    }
-  }
-
-  // Clean up orphaned staging directories older than 1 hour
-  try {
-    const stagingEntries = await readdir(dirs.staging)
-    let stagingCleanedCount = 0
-    for (const entry of stagingEntries) {
-      const stagingPath = join(dirs.staging, entry)
-      try {
-        // stat() is load-bearing here (we need mtime). There is a theoretical
-        // TOCTOU where a concurrent installer could freshen a stale staging
-        // dir between stat and rm — but the 1-hour threshold makes this
-        // vanishingly unlikely, and rm({force:true}) tolerates concurrent
-        // deletion.
-        const stats = await stat(stagingPath)
-        if (stats.mtime.getTime() < oneHourAgo) {
-          await rm(stagingPath, { recursive: true, force: true })
-          stagingCleanedCount++
-          logForDebugging(`Cleaned up old staging directory: ${entry}`)
-        }
-      } catch {
-        // Ignore individual errors
-      }
-    }
-    if (stagingCleanedCount > 0) {
-      logForDebugging(
-        `Cleaned up ${stagingCleanedCount} orphaned staging directories`,
-      )
-      logEvent('tengu_native_staging_cleanup', {
-        cleaned_count: stagingCleanedCount,
-      })
-    }
-  } catch (error) {
-    if (!isENOENT(error)) {
-      logForDebugging(`Failed to clean up staging directories: ${error}`)
-    }
-  }
-
-  // Clean up stale PID locks (crashed processes) — cleanupStaleLocks handles ENOENT
-  if (isPidBasedLockingEnabled()) {
-    const staleLocksCleaned = cleanupStaleLocks(dirs.locks)
-    if (staleLocksCleaned > 0) {
-      logForDebugging(`Cleaned up ${staleLocksCleaned} stale version locks`)
-      logEvent('tengu_native_stale_locks_cleanup', {
-        cleaned_count: staleLocksCleaned,
-      })
-    }
-  }
-
-  // Single readdir of versions dir. Partition into temp files vs candidate binaries,
-  // stat'ing each entry at most once.
-  let versionEntries: string[]
-  try {
-    versionEntries = await readdir(dirs.versions)
-  } catch (error) {
-    if (!isENOENT(error)) {
-      logForDebugging(`Failed to readdir versions directory: ${error}`)
-    }
-    return
-  }
-
-  type VersionInfo = {
-    name: string
-    path: string
-    resolvedPath: string
-    mtime: Date
-  }
-  const versionFiles: VersionInfo[] = []
-  let tempFilesCleanedCount = 0
-
-  for (const entry of versionEntries) {
-    const entryPath = join(dirs.versions, entry)
-    if (/\.tmp\.\d+\.\d+$/.test(entry)) {
-      // Orphaned temp install file — pattern: {version}.tmp.{pid}.{timestamp}
-      try {
-        const stats = await stat(entryPath)
-        if (stats.mtime.getTime() < oneHourAgo) {
-          await unlink(entryPath)
-          tempFilesCleanedCount++
-          logForDebugging(`Cleaned up orphaned temp install file: ${entry}`)
-        }
-      } catch {
-        // Ignore individual errors
-      }
-      continue
-    }
-    // Candidate version binary — stat once, reuse for isFile/size/mtime/mode
-    try {
-      const stats = await stat(entryPath)
-      if (!stats.isFile()) continue
-      if (
-        process.platform !== 'win32' &&
-        stats.size > 0 &&
-        (stats.mode & 0o111) === 0
-      ) {
-        // Check executability via mode bits from the existing stat result —
-        // avoids a second syscall (access(X_OK)) and the TOCTOU window between
-        // stat and access. Skip on Windows: libuv only sets execute bits for
-        // .exe/.com/.bat/.cmd, but version files are extensionless semver
-        // strings (e.g. "1.2.3"), so this check would reject all of them.
-        // The previous access(X_OK) passed any readable file on Windows anyway.
-        continue
-      }
-      versionFiles.push({
-        name: entry,
-        path: entryPath,
-        resolvedPath: resolve(entryPath),
-        mtime: stats.mtime,
-      })
-    } catch {
-      // Skip files we can't stat
-    }
-  }
-
-  if (tempFilesCleanedCount > 0) {
-    logForDebugging(
-      `Cleaned up ${tempFilesCleanedCount} orphaned temp install files`,
-    )
-    logEvent('tengu_native_temp_files_cleanup', {
-      cleaned_count: tempFilesCleanedCount,
-    })
-  }
-
-  if (versionFiles.length === 0) {
-    return
-  }
-
-  try {
-    // Identify protected versions
-    const currentBinaryPath = process.execPath
-    const protectedVersions = new Set<string>()
-    if (currentBinaryPath && currentBinaryPath.includes(dirs.versions)) {
-      protectedVersions.add(resolve(currentBinaryPath))
-    }
-
-    const currentSymlinkVersion = await getVersionFromSymlink(dirs.executable)
-    if (currentSymlinkVersion) {
-      protectedVersions.add(currentSymlinkVersion)
-    }
-
-    // Protect versions with active locks (running in other processes)
-    for (const v of versionFiles) {
-      if (protectedVersions.has(v.resolvedPath)) continue
-
-      const lockFilePath = getLockFilePathFromVersionPath(dirs, v.resolvedPath)
-      let hasActiveLock = false
-      if (isPidBasedLockingEnabled()) {
-        hasActiveLock = isLockActive(lockFilePath)
-      } else {
-        try {
-          hasActiveLock = await lockfile.check(v.resolvedPath, {
-            stale: LOCK_STALE_MS,
-            lockfilePath: lockFilePath,
-          })
-        } catch {
-          hasActiveLock = false
-        }
-      }
-      if (hasActiveLock) {
-        protectedVersions.add(v.resolvedPath)
-        logForDebugging(`Protecting locked version from cleanup: ${v.name}`)
-      }
-    }
-
-    // Eligible versions: not protected, sorted newest first (reuse cached mtime)
-    const eligibleVersions = versionFiles
-      .filter(v => !protectedVersions.has(v.resolvedPath))
-      .sort((a, b) => b.mtime.getTime() - a.mtime.getTime())
-
-    const versionsToDelete = eligibleVersions.slice(VERSION_RETENTION_COUNT)
-
-    if (versionsToDelete.length === 0) {
-      logEvent('tengu_native_version_cleanup', {
-        total_count: versionFiles.length,
-        deleted_count: 0,
-        protected_count: protectedVersions.size,
-        retained_count: VERSION_RETENTION_COUNT,
-        lock_failed_count: 0,
-        error_count: 0,
-      })
-      return
-    }
-
-    let deletedCount = 0
-    let lockFailedCount = 0
-    let errorCount = 0
-
-    await Promise.all(
-      versionsToDelete.map(async version => {
-        try {
-          const deleted = await tryWithVersionLock(version.path, async () => {
-            await unlink(version.path)
-          })
-          if (deleted) {
-            deletedCount++
-          } else {
-            lockFailedCount++
-            logForDebugging(
-              `Skipping deletion of ${version.name} - locked by another process`,
-            )
-          }
-        } catch (error) {
-          errorCount++
-          logError(
-            new Error(`Failed to delete version ${version.name}: ${error}`),
-          )
-        }
-      }),
-    )
-
-    logEvent('tengu_native_version_cleanup', {
-      total_count: versionFiles.length,
-      deleted_count: deletedCount,
-      protected_count: protectedVersions.size,
-      retained_count: VERSION_RETENTION_COUNT,
-      lock_failed_count: lockFailedCount,
-      error_count: errorCount,
-    })
-  } catch (error) {
-    if (!isENOENT(error)) {
-      logError(new Error(`Version cleanup failed: ${error}`))
-    }
-  }
-}
-
-/**
- * Check if a given path is managed by npm
- * @param executablePath - The path to check (can be a symlink)
- * @returns true if the path is npm-managed, false otherwise
- */
-async function isNpmSymlink(executablePath: string): Promise<boolean> {
-  // Resolve symlink to its target if applicable
-  let targetPath = executablePath
-  const stats = await lstat(executablePath)
-  if (stats.isSymbolicLink()) {
-    targetPath = await realpath(executablePath)
-  }
-
-  // checking npm prefix isn't guaranteed to work, as prefix can change
-  // and users may set --prefix manually when installing
-  // thus we use this heuristic:
-  return targetPath.endsWith('.js') || targetPath.includes('node_modules')
-}
-
-/**
- * Remove the claude symlink from the executable directory
- * This is used when switching away from native installation
- * Will only remove if it's a native binary symlink, not npm-managed JS files
- */
-export async function removeInstalledSymlink(): Promise<void> {
-  const dirs = getBaseDirectories()
-
-  try {
-    // Check if this is an npm-managed installation
-    if (await isNpmSymlink(dirs.executable)) {
-      logForDebugging(
-        `Skipping removal of ${dirs.executable} - appears to be npm-managed`,
-      )
-      return
-    }
-
-    // It's a native binary symlink, safe to remove
-    await unlink(dirs.executable)
-    logForDebugging(`Removed claude symlink at ${dirs.executable}`)
-  } catch (error) {
-    if (isENOENT(error)) {
-      return
-    }
-    logError(new Error(`Failed to remove claude symlink: ${error}`))
-  }
-}
-
-/**
- * Clean up old claude aliases from shell configuration files
- * Only handles alias removal, not PATH setup
- */
-export async function cleanupShellAliases(): Promise<SetupMessage[]> {
-  const messages: SetupMessage[] = []
-  const configMap = getShellConfigPaths()
-
-  for (const [shellType, configFile] of Object.entries(configMap)) {
-    try {
-      const lines = await readFileLines(configFile)
-      if (!lines) continue
-
-      const { filtered, hadAlias } = filterClaudeAliases(lines)
-
-      if (hadAlias) {
-        await writeFileLines(configFile, filtered)
-        messages.push({
-          message: `Removed claude alias from ${configFile}. Run: unalias claude`,
-          userActionRequired: true,
-          type: 'alias',
-        })
-        logForDebugging(`Cleaned up claude alias from ${shellType} config`)
-      }
-    } catch (error) {
-      logError(error)
-      messages.push({
-        message: `Failed to clean up ${configFile}: ${error}`,
-        userActionRequired: false,
-        type: 'error',
-      })
-    }
-  }
-
-  return messages
-}
-
-async function manualRemoveNpmPackage(
-  packageName: string,
-): Promise<{ success: boolean; error?: string; warning?: string }> {
-  try {
-    // Get npm global prefix
-    const prefixResult = await execFileNoThrowWithCwd('npm', [
-      'config',
-      'get',
-      'prefix',
-    ])
-    if (prefixResult.code !== 0 || !prefixResult.stdout) {
-      return {
-        success: false,
-        error: 'Failed to get npm global prefix',
-      }
-    }
-
-    const globalPrefix = prefixResult.stdout.trim()
-    let manuallyRemoved = false
-
-    // Helper to try removing a file. unlink alone is sufficient — it throws
-    // ENOENT if the file is missing, which the catch handles identically.
-    // A stat() pre-check would add a syscall and a TOCTOU window where
-    // concurrent cleanup causes a false-negative return.
-    async function tryRemove(filePath: string, description: string) {
-      try {
-        await unlink(filePath)
-        logForDebugging(`Manually removed ${description}: ${filePath}`)
-        return true
-      } catch {
-        return false
-      }
-    }
-
-    if (getPlatform().startsWith('win32')) {
-      // Windows - only remove executables, not the package directory
-      const binCmd = join(globalPrefix, 'claude.cmd')
-      const binPs1 = join(globalPrefix, 'claude.ps1')
-      const binExe = join(globalPrefix, 'claude')
-
-      if (await tryRemove(binCmd, 'bin script')) {
-        manuallyRemoved = true
-      }
-
-      if (await tryRemove(binPs1, 'PowerShell script')) {
-        manuallyRemoved = true
-      }
-
-      if (await tryRemove(binExe, 'bin executable')) {
-        manuallyRemoved = true
-      }
-    } else {
-      // Unix/Mac - only remove symlink, not the package directory
-      const binSymlink = join(globalPrefix, 'bin', 'claude')
-
-      if (await tryRemove(binSymlink, 'bin symlink')) {
-        manuallyRemoved = true
-      }
-    }
-
-    if (manuallyRemoved) {
-      logForDebugging(`Successfully removed ${packageName} manually`)
-      const nodeModulesPath = getPlatform().startsWith('win32')
-        ? join(globalPrefix, 'node_modules', packageName)
-        : join(globalPrefix, 'lib', 'node_modules', packageName)
-
-      return {
-        success: true,
-        warning: `${packageName} executables removed, but node_modules directory was left intact for safety. You may manually delete it later at: ${nodeModulesPath}`,
-      }
-    } else {
-      return { success: false }
-    }
-  } catch (manualError) {
-    logForDebugging(`Manual removal failed: ${manualError}`, {
-      level: 'error',
-    })
-    return {
-      success: false,
-      error: `Manual removal failed: ${manualError}`,
-    }
-  }
-}
-
-async function attemptNpmUninstall(
-  packageName: string,
-): Promise<{ success: boolean; error?: string; warning?: string }> {
-  const { code, stderr } = await execFileNoThrowWithCwd(
-    'npm',
-    ['uninstall', '-g', packageName],
-    // eslint-disable-next-line custom-rules/no-process-cwd -- matches original behavior
-    { cwd: process.cwd() },
-  )
-
-  if (code === 0) {
-    logForDebugging(`Removed global npm installation of ${packageName}`)
-    return { success: true }
-  } else if (stderr && !stderr.includes('npm ERR! code E404')) {
-    // Check for ENOTEMPTY error and try manual removal
-    if (stderr.includes('npm error code ENOTEMPTY')) {
-      logForDebugging(
-        `Failed to uninstall global npm package ${packageName}: ${stderr}`,
-        { level: 'error' },
-      )
-      logForDebugging(`Attempting manual removal due to ENOTEMPTY error`)
-
-      const manualResult = await manualRemoveNpmPackage(packageName)
-      if (manualResult.success) {
-        return { success: true, warning: manualResult.warning }
-      } else if (manualResult.error) {
-        return {
-          success: false,
-          error: `Failed to remove global npm installation of ${packageName}: ${stderr}. Manual removal also failed: ${manualResult.error}`,
-        }
-      }
-    }
-
-    // Only report as error if it's not a "package not found" error
-    logForDebugging(
-      `Failed to uninstall global npm package ${packageName}: ${stderr}`,
-      { level: 'error' },
-    )
-    return {
-      success: false,
-      error: `Failed to remove global npm installation of ${packageName}: ${stderr}`,
-    }
-  }
-
-  return { success: false } // Package not found, not an error
-}
-
-export async function cleanupNpmInstallations(): Promise<{
-  removed: number
-  errors: string[]
-  warnings: string[]
-}> {
-  const errors: string[] = []
-  const warnings: string[] = []
-  let removed = 0
-
-  // Always attempt to remove @anthropic-ai/claude-code
-  const codePackageResult = await attemptNpmUninstall(
-    '@anthropic-ai/claude-code',
-  )
-  if (codePackageResult.success) {
-    removed++
-    if (codePackageResult.warning) {
-      warnings.push(codePackageResult.warning)
-    }
-  } else if (codePackageResult.error) {
-    errors.push(codePackageResult.error)
-  }
-
-  // Also attempt to remove MACRO.PACKAGE_URL if it's defined and different
-  if (MACRO.PACKAGE_URL && MACRO.PACKAGE_URL !== '@anthropic-ai/claude-code') {
-    const macroPackageResult = await attemptNpmUninstall(MACRO.PACKAGE_URL)
-    if (macroPackageResult.success) {
-      removed++
-      if (macroPackageResult.warning) {
-        warnings.push(macroPackageResult.warning)
-      }
-    } else if (macroPackageResult.error) {
-      errors.push(macroPackageResult.error)
-    }
-  }
-
-  // Check for local installation at ~/.claude/local
-  const localInstallDir = join(homedir(), '.claude', 'local')
-
-  try {
-    await rm(localInstallDir, { recursive: true })
-    removed++
-    logForDebugging(`Removed local installation at ${localInstallDir}`)
-  } catch (error) {
-    if (!isENOENT(error)) {
-      errors.push(`Failed to remove ${localInstallDir}: ${error}`)
-      logForDebugging(`Failed to remove local installation: ${error}`, {
-        level: 'error',
-      })
-    }
-  }
-
-  return { removed, errors, warnings }
-}