[Bug] Broken symlink when installed via Volta due to staging directory

[Lanbasara]

Bug Description

When installing agent-browser globally via Volta, the resulting agent-browser binary symlink is broken, causing the CLI to fail with a "No such file or directory" error.

Environment

• Volta version: 2.0.2 (likely affects all versions)
• Node version: 22.22.0 (managed by Volta)
• OS: Linux x64 (likely affects macOS as well)
• agent-browser version: 0.8.5

Steps to Reproduce

1. Install Volta: curl https://get.volta.sh | bash
2. Install agent-browser globally: volta install agent-browser
3. Try to run: agent-browser --help

Expected: CLI runs successfully
Actual: bash: /root/.volta/bin/agent-browser: No such file or directory

Root Cause Analysis

1. Volta's Staging Directory Mechanism

Volta uses a staging directory pattern during package installation:

• Package is first installed to a temp directory: /root/.volta/tmp/image/packages/.tmpXXXXXX/
• After all scripts complete, the directory is renamed to the final location: /root/.volta/tools/image/packages/agent-browser/

This is a deliberate design to ensure atomic installations (see Volta source).

2. The Conflict

The postinstall.js script's fixUnixSymlink() function:

1. Gets the npm prefix via npm prefix -g → returns the staging directory
2. Creates an absolute symlink to the native binary using this staging path
3. Volta then moves the package to its final location
4. The symlink now points to a non-existent directory

# The broken symlink
$ ls -la /root/.volta/tools/image/packages/agent-browser/bin/agent-browser
agent-browser -> /root/.volta/tmp/image/packages/.tmpf5Mfos/lib/node_modules/agent-browser/bin/agent-browser-linux-x64
#               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
#               This directory no longer exists!

Proposed Solution

Detect the Volta environment and skip the symlink optimization, allowing Volta to manage shims as intended:

async function fixUnixSymlink() {
  // Skip optimization in Volta environment - Volta uses a staging directory
  // that gets renamed after postinstall, breaking absolute symlinks
  if (process.env.VOLTA_HOME) {
    console.log('ℹ Volta detected: skipping bin optimization (Volta manages shims)');
    return;
  }
  // ... existing code
}

The same check should be added to fixWindowsShims().

This is safe because:

1. VOLTA_HOME is always set when running under Volta
2. Volta's shim system handles binary invocation automatically
3. The JS wrapper fallback still works correctly

Workaround

Users can manually fix the symlink after installation:

cd /root/.volta/tools/image/packages/agent-browser/bin
rm agent-browser
ln -s agent-browser-linux-x64 agent-browser

Or reinstall with npm instead of Volta.

Related

This is a common issue when packages modify symlinks during postinstall. Similar problems have been reported with other package managers that use staging directories.

[Lanbasara]

Update: Unit Tests Added

I've added comprehensive unit tests in test/postinstall.test.ts to document and verify the fix:

$ pnpm vitest run test/postinstall.test.ts

 ✓ test/postinstall.test.ts (11 tests) 8ms

 Test Files  1 passed (1)
      Tests  11 passed (11)

Test Coverage

1. shouldSkipBinOptimization logic

   • Skip when VOLTA_HOME is set to any path
   • Do NOT skip when VOLTA_HOME is undefined or empty

2. Staging directory documentation tests

   • Demonstrates why absolute symlinks break
   • Shows the path transformation: /tmp/ → /tools/
   • Documents that Volta intentionally uses same nesting depth (for relative symlinks)

3. Environment variable edge cases

   • Various path formats (Unix, Windows)
   • Other version managers (nvm, fnm) are NOT affected

4. Integration tests

   • Verifies console output message when Volta detected
   • Verifies no message in standard npm environment

The tests serve as both verification and documentation of the root cause for future maintainers.

PR: #325

[azhang]

not working on macos as well.

workaround:

cd ~/.volta/tools/image/packages/agent-browser/bin
ln -sf ../lib/node_modules/agent-browser/bin/agent-browser-darwin-arm64 agent-browser