Skip to content

docs(windows): expand windows.md with kernel bootstrap, env inheritance, lock cleanup - #962

Open
abdulazizFarhan wants to merge 1 commit into
PrimeIntellect-ai:mainfrom
abdulazizFarhan:docs-windows
Open

docs(windows): expand windows.md with kernel bootstrap, env inheritance, lock cleanup#962
abdulazizFarhan wants to merge 1 commit into
PrimeIntellect-ai:mainfrom
abdulazizFarhan:docs-windows

Conversation

@abdulazizFarhan

@abdulazizFarhan abdulazizFarhan commented Aug 8, 2026

Copy link
Copy Markdown

Expands packages/coding-agent/docs/windows.md with the IPython kernel bootstrap workflow for Windows.

Added sections:

  • One-shot Python kernel provisioning (PowerShell + Git Bash variants). Lists all 13 required packages — with tyro and dill called out as the easy ones to miss (Prime Agent's bootstrap only reports the first missing group per run).
  • PowerShell user-level env var inheritance quirk. setx writes a user-level var, but PowerShell does NOT auto-inherit user-level vars into the process env (cmd does). The wrapper must explicitly copy them via [System.Environment]::SetEnvironmentVariable($name, $value, 'Process'). This is the most common silent failure for PowerShell-launched prime-agent sessions.
  • Stale session-leases/*.lock cleanup. proper-lockfile uses directories as locks on Windows. If the previous prime-agent was killed, the .lock directory blocks the next resume with EPERM: rename *.lock.candidate-XXX → *.lock. Wrapper should clear locks whose owner.json PID is no longer running.
  • Failure-mode diagnosis checklist for the four common 'kernel broken' symptoms (POSIX-only bootstrap path, missing package, stale lock, bootstrap-version drift).

Why docs-only: the kernel path fix itself is already in PR #825 (fix/windows-console-flicker). This PR makes the existing workaround discoverable and documents the PowerShell + lock gotchas that bit me during setup. Closes the documentation gap for #660.

Note

Expand Windows documentation with kernel bootstrap, env inheritance, and lock cleanup

Adds several new sections to windows.md covering the full Windows setup and troubleshooting workflow:

  • Documents the Python kernel bootstrap: per-user uv-managed venv location, required packages, and one-shot provisioning commands for PowerShell and Git Bash
  • Adds a PowerShell snippet to import user-level environment variables before launching prime-agent, addressing env inheritance gaps on Windows
  • Provides a PowerShell script to clean up stale session-lease *.lock directories whose owning PID no longer exists
  • Adds a failure-mode diagnosis section covering POSIX-only path bugs, missing packages under a custom Python override, stale lock rename errors, and out-of-sync .bootstrap-version

Macroscope summarized f366c91.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant