[Bug]: Source build on non-NTFS/cloud-synced Windows volumes fails cryptically (pnpm workspace links need junctions)

Start with docs/installation.md and the README’s “Build from source” section. Document that Windows checkouts must be on a local NTFS volume because pnpm workspace links require junctions, and mention the affected install failure on cloud-synced, FAT32, exFAT, or network volumes. Done when both source-build entry points clearly state the requirement and workaround.

Issue 2 — Document the local-NTFS requirement for Windows source checkouts

Template: Bug report → Product: Source build or repository tooling (docs gap + cryptic failure)

Title:
[Bug]: Source build: pnpm install fails cryptically on non-NTFS / cloud-synced Windows volumes — workspace links need junctions; requirement is undocumented

Product or interface

Source build or repository tooling

Version

Source @ ae65651 (0.5.1). Node.js v24.18.0, pnpm 9.12.0. Windows 11 x64 (build 26200).

Platform

Windows

Steps to reproduce

1. Clone the repository onto a volume that is not a local NTFS disk — in this case a Google Drive desktop-mirrored volume that reports FAT32 (fsutil fsinfo volumeinfo G: → File system name: FAT32, volume name "Google Drive"). Network shares and exFAT USB drives behave the same way.
2. npx pnpm@9.12.0 install --frozen-lockfile

Expected and actual behavior

Expected: either the install succeeds, or it fails with a message explaining that pnpm workspace links require junctions and therefore a local NTFS volume.

Actual: the install downloads and links ~530 packages, then aborts during linking of the vendored workspace dependency with a bare ENOENT stack that never mentions symlinks, junctions, or the filesystem:

ENOENT: no such file or directory, stat 'G:\…\minimax-code\third_party\pi-mono\packages\agent\node_modules\@earendil-works\pi-ai'
    at async Object.stat (node:internal/fs/promises:1038:18)
    at async renameOverwrite (…/pnpm/dist/pnpm.cjs:54992:15)
    at async forceSymlink (…/pnpm/dist/pnpm.cjs:103483:11)
    at async symlinkDirectRootDependency (…/pnpm/dist/pnpm.cjs:143278:26)

The failure leaves an empty …\agent\node_modules\@earendil-works\ directory behind. Rerunning reproduces the identical failure.

Root cause: the root .npmrc sets node-linker=hoisted, so regular dependencies are copied and work fine, but workspace:* links (e.g. @earendil-works/pi-ai in third_party/pi-mono/packages/agent) still require a filesystem junction/symlink. Junctions cannot exist on FAT32/exFAT/cloud-mirrored or network volumes — mklink /J fails with "Local NTFS volumes are required to complete this operation".

Verification of the diagnosis: the same commit cloned to a local NTFS drive installs cleanly (25 s), builds (10.5 s), and passes typecheck, check:source, check:tsconfig, test:smoke, test:byok, test:status-contract.

Suggested fix

1. Document the requirement in docs/installation.md (and the README "Build from source" section): the checkout must live on a local NTFS volume on Windows; cloud-synced or FAT32/exFAT locations fail during pnpm install at the workspace-link stage. This is especially relevant because "Desktop" folders are commonly redirected to Google Drive/OneDrive on Windows machines.
2. Optionally, fail fast with a clear message: a small preflight (install script or docs CI check) that detects a non-NTFS/non-local checkout root on Windows and prints "clone to a local NTFS drive" instead of the raw pnpm ENOENT stack.

Redacted error summary

npx pnpm@9.12.0 install --frozen-lockfile
…
ENOENT: no such file or directory, stat '…\third_party\pi-mono\packages\agent\node_modules\@earendil-works\pi-ai'
    at async renameOverwrite / forceSymlink / symlinkDirectRootDependency

cmd> mklink /J …\pi-ai …\ai
Local NTFS volumes are required to complete this operation.

Before submitting

• I have searched existing issues.
• I have included my version and removed sensitive information.