Windows: setupUserSeparation() symlinkSync fails with EPERM; the copy fallback promised in INSTALL.md never runs (directory junctions work unelevated)

[umair-a11y]

Summary

setupUserSeparation() in Tools/InstallEngine.ts creates the system/user separation link with plain symlinkSync(dataUserDir, liveUserDir) (lines 604 and 614, no type argument). On Windows, creating a real symlink requires elevation or Developer Mode, so on a stock machine symlinkSync throws EPERM; the engine reports symlink creation failed: EPERM ..., the separation link is never established, and checkSymlinkContract then fails with ... is not a symlink (system/user separation broken).

INSTALL.md line 163 promises otherwise:

| **Claude Code — Windows** | ✅ (copy fallback where symlinks need admin) | ✅ full |

No copy fallback exists in the v7.28.3 code path. Code and docs currently disagree about what happens on Windows.

Environment

LifeOS	v7.28.3 (release tarball)
OS	Windows 11 Home 10.0.26200
Harness	Claude Code v2.1.220
bun	1.3.14
git	2.51.0.windows.1

Repro

1. Windows 11, Developer Mode off, non-elevated PowerShell.
2. Run the install through the user-separation step (with HOME set manually to get past the home-resolution bug, Windows: installer tools resolve home as process.env.HOME || "", so ScaffoldUser silently writes its USER tree into the release directory #1729).
3. symlinkSync fails with EPERM: operation not permitted, symlink .... No fallback runs, and the symlink contract check fails.

Suggested fix: directory junctions

symlinkSync(dataUserDir, liveUserDir, "junction");

Why this works:

• Directory junctions need no elevation and no Developer Mode.
• Node and Bun ignore the type argument on non-Windows platforms, so no platform branch is needed.
• dataUserDir is already absolute, which junctions require.
• The existing contract survives unchanged: lstatSync().isSymbolicLink() returns true for junctions and readlinkSync() returns the target, which is all checkSymlinkContract() (Tools/InstallEngine.ts:625-639) relies on.

Verified on this install: after creating the junction manually,

New-Item -ItemType Junction -Path "$env:USERPROFILE\.claude\LIFEOS\USER" -Target "$env:USERPROFILE\.config\LIFEOS\USER"

checkSymlinkContract passed as written, and the installed system has been running against the junction since.

If the copy fallback described in INSTALL.md is still wanted as a last resort, junction-first is the better order: a copy forks USER state between the two locations, while a junction keeps the live-link semantics the separation design assumes. Either way, INSTALL.md and the code should agree.

Related Windows detection nits (can split into a separate issue if preferred)

• detectTool() (Tools/InstallEngine.ts:108) and detectHarness() (Tools/InstallEngine.ts:132) probe with POSIX command -v, so on Windows the environment report claims bun, git, and sh are missing from PATH even when they are present and working.
• The hook-interpreter probes check the POSIX execute bit (LIFEOS/TOOLS/Doctor.ts:582, LIFEOS/TOOLS/IntegrityCheck.ts:550), reporting registered hooks as not executable (chmod +x) on NTFS even though the hooks demonstrably execute via Git Bash.

Both are cosmetic, but they present as failures mid-install and make real errors harder to spot.

[umair-a11y]

Root cause found and fixed locally (Windows). Doctor's which()/whichPath() split PATH on ':' — the Unix separator — and probed without Windows executable extensions, so every installed binary (rg, gh, jq, ffmpeg, bun, sh, …) read as 'not on PATH'. Three sibling bugs in the same family: chromeBinary() had no Windows candidate paths, the hook check required the Unix execute bit (meaningless on NTFS), and shebang interpreters like /bin/bash were tested with existsSync (invisible to native-Windows Bun, resolvable inside Git Bash).

Fixes applied: Bun.which() first with a path.delimiter + .exe/.cmd/.bat manual fallback; Windows Chrome/Brave install paths; execute-bit check skipped on win32; shebang paths judged by basename-on-PATH on win32. Verified: 10 false 'broken' flags cleared on a Windows 11 + Git Bash install, leaving only genuinely-unconfigured capabilities.

🤖 Generated with Claude Code

[umair-a11y]

Counter-probe evidence table backing the earlier root-cause comment — every binary the unpatched Doctor flagged as ❌ 'not on PATH', re-probed live from Git Bash on the same Windows 11 machine:

Binary	Unpatched Doctor	Git Bash counter-probe	Version
rg	❌ not on PATH	/c/Users/<user>/AppData/Local/Microsoft/WinGet/Packages/.../rg	ripgrep 15.2.0
gh	❌ not on PATH	/c/Program Files/GitHub CLI/gh	2.97.0
jq	❌ not on PATH	/c/Users/<user>/AppData/Local/Microsoft/WinGet/Packages/.../jq	1.8.2
ffmpeg	❌ not on PATH	/c/ffmpeg/ffmpeg-7.1-essentials_build/bin/ffmpeg	7.1
bun	❌ not on PATH	/c/Users/<user>/.bun/bin/bun	1.3.14
sh	❌ not on PATH	/usr/bin/sh	GNU bash 5.2.37 (msys)
node	❌ not on PATH	/c/Program Files/nodejs/node	24.18.0
git	❌ not on PATH	/mingw64/bin/git	2.51.0.windows.1

Discriminating detail: fd and bat probe ABSENT from Git Bash too — genuinely not installed. The patched probe (Bun.which() + path.delimiter split + .exe/.cmd/.bat fallback) keeps flagging those two while clearing the eight above, so it distinguishes real capability gaps from the separator bug rather than blanket-passing everything.

🤖 Generated with Claude Code

[danielmiessler]

Good catch, @umair-a11y — symlinkSync was throwing EPERM on Windows. Fixed in source (now uses a junction, in InstallEngine.ts), ships next release. Closing since the public repo is generated from that source.