fix: skip symlink optimization in Volta environment

[Lanbasara]

Summary

Fixes #324

When installing agent-browser via Volta, the postinstall symlink optimization creates broken symlinks because Volta uses a staging directory that gets renamed after postinstall completes.

Changes

Added Volta environment detection at the beginning of both fixUnixSymlink() and fixWindowsShims() functions:

if (process.env.VOLTA_HOME) {
  console.log('ℹ Volta detected: skipping bin optimization (Volta manages shims)');
  return;
}

Why This Works

1. VOLTA_HOME environment variable is always set when running under Volta
2. Volta has its own shim system that handles binary invocation
3. The JS wrapper fallback continues to work correctly
4. This is a minimal, non-breaking change that only affects Volta users

Testing

Manual Verification

$ VOLTA_HOME=/tmp/fake-volta node scripts/postinstall.js
✓ Downloaded native binary: agent-browser-linux-x64
ℹ Volta detected: skipping bin optimization (Volta manages shims)

Unit Tests Added

Added comprehensive test suite in test/postinstall.test.ts covering:

1. shouldSkipBinOptimization logic - Tests VOLTA_HOME detection with various values
2. Staging directory documentation - Tests that explain the root cause:
   • Why absolute symlinks break (staging → final rename)
   • Path structure differences (/tmp/ vs /tools/)
3. Environment variable handling - Tests for edge cases (empty string, undefined)
4. Integration tests - Verify console output in both environments

$ pnpm vitest run test/postinstall.test.ts

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

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

Root Cause Analysis

The issue occurs because:

1. Volta installs packages to staging: $VOLTA_HOME/tmp/image/packages/.tmpXXX/
2. During postinstall, npm prefix -g returns this temp path
3. fixUnixSymlink() creates symlink pointing to staging directory
4. Volta renames staging to final: $VOLTA_HOME/tools/image/packages/{name}/
5. Result: Symlink now points to non-existent directory

The fix detects Volta environment and skips the optimization, letting Volta's shim system handle binary invocation.

[vercel]

Someone is attempting to deploy a commit to the Vercel Labs Team on Vercel.

A member of the Team first needs to authorize it.

[Lanbasara]

Hi @ctate 👋 Just a gentle ping — this PR fixes a symlink issue when installing via Volta (ref #324). The CI workflow needs maintainer approval to run since this is from a fork. Could you approve the workflow run when you get a chance? Thanks!