Windows: kernel bootstrap uses venv bin/python, so the IPython kernel never starts and each retry wipes the venv

[skulitom]

Summary

On Windows, bootstrapVenv builds the kernel interpreter path as <venv>/bin/python, which is the POSIX venv layout. Windows venvs put the interpreter at <venv>/Scripts/python.exe, so the path never exists, uv pip install --python <that path> exits 2, and the kernel never starts.

Because the persistent IPython kernel is Prime Agent's only tool, the agent comes up with no ability to read files, grep, or run commands at all. It still answers from context files, which makes the failure easy to misread as a model problem rather than a bootstrap problem.

There is a second effect that makes it worse: each attempt re-runs uv venv --seed before it fails, so every retry recreates the venv and discards anything installed into it. Manually populating the venv appears to work and then silently vanishes on the next launch.

Environment

• Prime Agent 0.7.0 (installed via the official install.sh → npm install -g path)
• Windows 11 Pro 26200, Node 22.14.0, npm 10.9.2
• Git Bash present at C:\Program Files\Git\bin\bash.exe (satisfies docs/windows.md)
• uv 0.12.2, Python 3.13.9
• Kernel bootstrap ran at install time with PRIME_AGENT_BOOTSTRAP_KERNEL_ON_INSTALL=1 PRIME_AGENT_INSTALL_UV=1

Reproduce

prime-agent -p --cwd /path/to/any/repo "Use your Python kernel to grep this repo for the definition of some function. Report the file and line."

The agent replies that its kernel could not start and that it will not guess. ~/.prime/agent/kernel-venv/Lib/site-packages/ contains only pip, setuptools, and wheel — the --seed packages — and no ipykernel.

Observed errors

Straight out of the box:

Failed to set up the Python kernel runtime.
uv.exe pip install --python C:\Users\<user>\.prime\agent\kernel-venv\bin\python ipykernel ... failed with exit code 2

Note kernel-venv\bin\python: that path does not exist on Windows, and it has no .exe.

Setting PRIME_AGENT_KERNEL_PYTHON to the real interpreter (...\kernel-venv\Scripts\python.exe) moves past that, but then surfaces the remaining requirements one set at a time, so it takes three separate runs to discover the full list:

PRIME_AGENT_KERNEL_PYTHON points to a Python missing ipykernel and a current prime-agent-runtime: ...
PRIME_AGENT_KERNEL_PYTHON points to a Python missing default Python packages
  (requests, httpx, yaml, tomli, dotenv, pandas, numpy, scipy, bs4, lxml, pydantic): ...

Root cause

packages/coding-agent/src/core/kernel/bootstrap.ts:

• L728 — const python = path.join(venv, "bin", "python"); in bootstrapVenv, then passed as --python to uv pip install at L735-744.
• L889 — the same join in ensureKernelPython, feeding kernelReady(python, ...) at L891.

Neither branches on platform, although the same file does exactly that elsewhere — L503 (process.platform === "win32" ? [name, ${name}.exe] : [name]) and L518 for locating uv.

The wipe-on-retry follows from the same bad path: kernelReady at L891 is checked against <venv>/bin/python, so on Windows it is always false, the code always falls through to bootstrapVenv, and L734 runs uv venv <venv> --seed again, recreating the directory before the install fails.

The existing tests bake in the POSIX layout too — test/ipython-bootstrap.test.ts and test/kernel-state-roundtrip.test.ts both assert join(homedir(), ".prime", "agent", "kernel-venv", "bin", "python"), and test/kernel-bootstrap.test.ts writes its fake interpreter to $venv/bin/python with chmod +x, so no test would catch this.

Suggested fix

A platform-aware helper used by both sites, matching the L503 pattern:

const venvPython = (venv: string) =>
  process.platform === "win32"
    ? path.join(venv, "Scripts", "python.exe")
    : path.join(venv, "bin", "python");

Two things worth pairing with it:

1. Don't run uv venv --seed until the interpreter path resolves, so a failed bootstrap can't destroy a working venv.
2. Report the full missing-requirement set at once instead of one group per run.

Workaround

For anyone hitting this before a fix lands — provision the venv directly and pin the override, since letting auto-bootstrap run again will clear it:

P="$HOME/.prime/agent/kernel-venv/Scripts/python.exe"
R="<npm-global>/node_modules/prime-agent/dist/prime-agent-runtime"
uv pip install --python "$P" ipykernel "$R"
uv pip install --python "$P" requests httpx pyyaml tomli python-dotenv pandas numpy scipy beautifulsoup4 lxml pydantic
export PRIME_AGENT_KERNEL_PYTHON='C:\Users\<user>\.prime\agent\kernel-venv\Scripts\python.exe'

With that in place the kernel starts and works correctly — verified by having the agent grep a repo and return a function's defining file and line number, which matched an independent grep exactly.

[melanson633]

Independent reproduction on a source checkout rather than the install.sh / npm-global route, plus confirmation that the suggested fix works end-to-end.

Environment: Prime Agent 0.7.0 at c22549a, Windows 11 Pro 26200, Node 24.16.0, Git Bash.

Same failure, same two lines. Worth adding: the report above verifies the workaround (PRIME_AGENT_KERNEL_PYTHON plus a hand-provisioned venv), not the patch. I applied the proposed venvPython helper at L728 and L889, rebuilt, deleted kernel-venv entirely, and let auto-bootstrap run unassisted:

› setting up python kernel (one-time, ~30s)…
✓ ready
KERNEL PYTHON: C:\Users\<user>\.prime\agent\kernel-venv\Scripts\python.exe

Then confirmed the interpreter actually executes rather than merely existing:

imports OK, rlm callable: True
4

So the two-line change is sufficient on its own — no env-var override needed. The retry-wipe symptom also disappears with it, since kernelReady then resolves truthfully instead of always returning false.

The test observation is right and worth not skipping: kernel-bootstrap.test.ts writes its fake interpreter to $venv/bin/python and chmod +xs it, so a fix without test changes passes CI on Linux while the Windows path stays untested.

[1xadz]

Confirmed on Windows 11 (v0.7.0, npm install). Patching the two path.join(venv, "bin", "python") sites in dist/core/kernel/bootstrap.js (plus their copies in dist/bundle/chunk-*.js) to a platform-aware path fixes it — kernel boots and all imports work:

const python = process.platform === "win32"
  ? path.join(venv, "Scripts", "python.exe")
  : path.join(venv, "bin", "python");

Note the same file already handles win32 for the uv binary (uv.exe), so this is the only remaining POSIX assumption in the bootstrap path resolution.

[schn4ppi]

Confirmed on a second machine via the stable release channel tarball (prime-agent-0.7.0.tgz, checksum-verified, npm install -g with PRIME_AGENT_BOOTSTRAP_TOOLS_ON_INSTALL=1 PRIME_AGENT_BOOTSTRAP_KERNEL_ON_INSTALL=1 PRIME_AGENT_INSTALL_UV=1), Windows 11, Node 24.18.0, npm 11.16.0. Same failure, same root cause. Three additions:

1. The uv auto-install is POSIX-only too. ensureUv runs sh -c "curl -LsSf https://astral.sh/uv/install.sh | sh" (L527-529). On a default Git-for-Windows setup there is no sh on PATH (sh.exe lives in Git\usr\bin, which the Git installer does not add), so PRIME_AGENT_INSTALL_UV=1 fails with ENOENT before the venv is even attempted. Manual install via the official PowerShell route works and is picked up from ~/.local/bin/uv.exe:

irm https://astral.sh/uv/install.ps1 | iex

2. The npm postinstall fails silently. postinstall.cjs catches all errors and exits 0 by design, and install.sh passes --loglevel=error, so the Windows install reports success while the kernel runtime was never set up. The failure only surfaces on first ipython use. Until the fix lands, it may be worth printing a warning unconditionally when process.platform === "win32" and the bootstrap didn't complete.

3. The workaround list is missing two packages. dill (state snapshots) and tyro (in DEFAULT_RLM_EXTRA_PACKAGES, checked by the override branch) are required; without tyro the override check reports "missing default Python packages" on the next run. Complete one-shot provisioning that passes Prime Agent's own validation:

$uv = "$env:USERPROFILE\.local\bin\uv.exe"
$py = "$env:USERPROFILE\.prime\agent\kernel-venv\Scripts\python.exe"
$rt = "$env:APPDATA\npm\node_modules\prime-agent\dist\prime-agent-runtime"
& $uv pip install --python $py ipykernel $rt dill requests httpx pyyaml tomli python-dotenv pandas numpy scipy beautifulsoup4 lxml pydantic tyro
[Environment]::SetEnvironmentVariable("PRIME_AGENT_KERNEL_PYTHON", $py, "User")

Verified with Prime Agent's own checker — node ...\dist\core\kernel\bootstrap-cli.js prints kernel python: C:\Users\<user>\.prime\agent\kernel-venv\Scripts\python.exe, meaning ipykernel, the runtime harness CRUD surface, and all default packages resolve.

[abdulazizFarhan]

Fourth reproduction + a workaround the maintainers should document

Environment: prime-agent v0.7.0 → v0.7.1 via npm install -g (the official tarball path, not a source checkout). Windows 11 Pro, Node v24.13.0 (nvm-managed), uv 0.12.x, Python 3.11.14. Same failure, same two-line error from the bootstrap.

Two new details beyond what's already in this issue:

1. The fix needs to land in the BUNDLE, not just the source bootstrap.js.

I patched dist/core/kernel/bootstrap.js (the source) at lines 639, 749 with the platform-aware ternary. No effect at runtime. The runtime loads the bundled dist/bundle/chunk-VNU2AJHD.js, which still has path5.join(venv, "bin", "python") at lines ~43075 and ~43169. Patching only the source gives a false sense of security. Both the source bootstrap.ts AND the bundle need to be patched, and the bundle needs to be regenerated by the build.

A user who wants to verify the fix locally without waiting for a release can:

• apply the patch to dist/bundle/chunk-VNU2AJHD.js lines ~43075 and ~43169 (the only two sites that need it in v0.7.1)
• OR set PRIME_AGENT_KERNEL_PYTHON to a pre-installed Python (with all 13 packages: ipykernel, prime-agent-runtime, dill, requests, httpx, pyyaml, tomli, python-dotenv, pandas, numpy, scipy, beautifulsoup4, lxml, pydantic, tyro) and the bootstrap is skipped entirely

2. The PowerShell wrapper drops user-level env vars silently.

docs/windows.md should note that setx writes a user-level var, but PowerShell does NOT auto-inherit user-level vars into the process env. cmd does. PowerShell doesn't. So a wrapper that runs under PowerShell (e.g. prime-agent.ps1 shipping with the user) needs to explicitly pull PRIME_AGENT_KERNEL_PYTHON (and MINIMAX_API_KEY, PRIME_AGENT_BOOTSTRAP_KERNEL_ON_INSTALL, etc.) from the user-level store into the process env before spawning prime-agent. Without that, every PowerShell-launched session silently falls back to the broken ~/.prime/agent/kernel-venv/bin/python path even when setx was run.

Minimal wrapper snippet that works:

foreach ($name in @('PRIME_AGENT_KERNEL_PYTHON','MINIMAX_API_KEY','PRIME_AGENT_BOOTSTRAP_KERNEL_ON_INSTALL')) {
    $value = [System.Environment]::GetEnvironmentVariable($name, 'User')
    if ($value -and [string]::IsNullOrEmpty($env:$name)) {
        [System.Environment]::SetEnvironmentVariable($name, $value, 'Process')
    }
}

3. Stale session-leases/*.lock directories block resume.

prime-agent's proper-lockfile uses DIRECTORIES as locks on Windows. When a previous process is killed (e.g. by npm update or Stop-Process), the lock directory remains. The next resume tries rename *.lock.candidate-<id> → *.lock and fails with EPERM because you can't rename a file to a directory name. The wrapper should clear stale locks whose owner.json PID is no longer alive:

Get-ChildItem -Path "$env:USERPROFILE\.prime\agent\session-leases" -Filter "*.lock" -Directory -ErrorAction SilentlyContinue | ForEach-Object {
    $owner = Get-Content "$($_.FullName)\owner.json" -Raw -ErrorAction SilentlyContinue | ConvertFrom-Json -ErrorAction SilentlyContinue
    if (-not $owner -or -not (Get-Process -Id $owner.pid -ErrorAction SilentlyContinue)) {
        Remove-Item -LiteralPath $_.FullName -Recurse -Force -ErrorAction SilentlyContinue
    }
}

4. End-to-end verification

After applying the wrapper changes above and pointing PRIME_AGENT_KERNEL_PYTHON at a pre-installed Python:

• prime-agent -p "use ipython to compute 17 * 23" --tools ipython → 391 ✓
• prime-agent -p "use ipython to print 2**10" --tools ipython → 1024 ✓
• prime-agent -p "use ipython: import pandas; df = pd.DataFrame({'x':[1,2,3],'y':[10,20,30]}); print(df.shape, df['x'].mean())" --tools ipython → (3, 2) 2.0 ✓
• prime-agent -p "use ipython: read C:\Users\…\.prime\agent\settings.json and print settings['defaultModel']" --tools ipython → MiniMax-M3 ✓

All four execute Python in the override kernel. The kernel side is fully functional.

PR #825

I see PR #825 (fix(coding-agent): Windows support for kernel bootstrap and console-less daemon spawns, +55 lines) covers both the kernel path fix AND the windowsHide spawn patches in the bundle. That's the right home for the kernel-path fix. The four things I found above (bundle vs source, PowerShell env inheritance, stale-lock cleanup) are wrappers/docs/windows.md concerns and probably belong in a separate documentation PR.