Repository navigation
fix(packaging): drop PYTHONPATH/PYTHONHOME in the bundled kirocrew launchers - #19690
Conversation
UX Review (Opus 5.5) — ✅ PASSUX-level review of UX-Verdict: PASS Nothing to check. [UX-REVIEWED] d6d5778 Description read[DESCRIPTION-READ] c40cef0d14c52d6e41be9bfb50758859c6dcf1126d33563302cbddd50c87469f That sha256 names everything this verdict read: the PR description, plus the 3 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Before merge, confirm that this head's What this change shipsInventory (6 items) — 6 justifiedIntent: when someone runs the packaged
[FIRST-PRINCIPLES-REVIEWED] d6d5778 Description read[DESCRIPTION-READ] 93efb76114fe832dd57e088ce0467fe6c4e7b6a8211e39f58d1c03d7a3a9add6 That sha256 names the PR description this verdict read. Recompute it with |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Check that this PR's [DESIGN-REVIEWED] d6d5778 Description read[DESCRIPTION-READ] eca06705a461304d481efd8703d72b583055702ba9cac0114f933fed5ac3d136 That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
a9734d8 to
9797492
Compare
da37e2b to
9d474b2
Compare
9d474b2 to
d6d5778
Compare
buluoray
left a comment
There was a problem hiding this comment.
Verdict: APPROVE at d6d5778690
What it fixes
If you ran the packaged kirocrew CLI (token, stop, the ~/.local/bin/kirocrew symlink) from a dev shell that exports PYTHONPATH=<checkout>/src or PYTHONHOME, the bundled interpreter imported checkout code into the shipped backend. #17852 scrubbed these variables only in the desktop shell's own spawn. This PR moves the scrub into the launcher that every caller goes through, which fixes the cause rather than one caller.
What I verified
- POSIX launcher
packaging/build-desktop.sh:577:unset PYTHONPATH PYTHONHOMEruns right before theexec.build_backendwrites this heredoc for both Linux and macOS (called at:886-887and:926), so both platforms get it. No other launcher writer exists inpackaging/. - Windows:
packaging/build-desktop.sh:763and.github/workflows/build.yml:218write the same five lines (setlocal, then twoset "X=", then the unchangedpython.exe -s -Pline).setlocalkeeps the deletion out of the caller's interactivecmd, and the implicitendlocalkeeps the exit code. - The Windows gateway spawn skips the
.cmd(gateway-recovery.js:567). On that path the scrub is still the existingbundledbranch ingateway-env.js:63, as the new comment says. - Dev and source installs are not affected. Source and venv installs use pip's console script, not this heredoc. Every in-process
PYTHONPATHinjection I found (apps/bridges.py:581,2348,apps/backend.py:1104, the auto-improvement profile:437) launchessys.executableor an app interpreter directly, never the bundledbin/kirocrew. So no intentionalPYTHONPATHgets dropped.PYTHONUTF8and the bytecode settings still pass through because-Ewas not used, andtest_keeps_the_other_python_knobs_the_shell_hands_downpins that. - Docs:
docs/build/desktop-app.mdis updated. The launcher prose indocs/system-specs(cli.md, about-P) is still accurate. - Targeted suites pass (13). CI on this head: 95 pass, 7 skipped, 0 fail, including
Build Windows Installer (x64)and all threeBuild Desktopjobs.
Mutations (one at a time, worktree restored and clean between runs):
- removing
unset→test_strips_inherited_pythonpath_and_pythonhome_through_the_shim,test_keeps_the_other_python_knobs…andtest_launcher_keeps_the_python_env_scrubfail - removing the cmd
set "PYTHONPATH="→test_cmd_launcher_clears_pythonpath_and_pythonhome_before_python_runsand the workflow parity test fail - removing the cmd
setlocal→test_cmd_launcher_scopes_the_deletion_with_setlocaland the parity test fail - removing the workflow's
PYTHONHOMEline →test_build_workflow_writes_the_same_cmd_launcherfails
Blocking
None.
Non-blocking follow-ups
- None needed. A real
cmd.exerun with a poisonedPYTHONPATHwould be the end-to-end proof, but the installer smoke only shows that the new shim still boots.
Not verified
- No
cmd.exeor macOS run on my side. Windowssetlocaland exit-code behaviour were checked against source and documented cmd semantics only, plus the green Windows installer job.
iamwhatever
left a comment
There was a problem hiding this comment.
This PR moves the PYTHONPATH/PYTHONHOME scrub from the desktop shell's spawn helper (one caller) into the bundled launchers that every caller goes through. The POSIX bin/kirocrew script now runs unset PYTHONPATH PYTHONHOME before exec, and the Windows kirocrew.cmd clears both under setlocal, so the root cause from #18378 is fixed where it lives. I read the full diff and checked every other consumer of kirocrew.cmd on main: gateway-recovery.js and mcp_discovery unwrap the shim to python.exe, which still matches the unchanged last line, and agent.py's launcher sniff reads only the first line, so neither breaks. On Windows the unwrapped spawns skip the shim, but they still get buildGatewayEnvironment({ bundled: true }), as the new comment says. The scrub is narrow on purpose: it drops no other PYTHON* variable and does not use -E, so PYTHONUTF8 and the bytecode settings still reach the interpreter. setlocal keeps a user's interactive cmd window intact. The new behavioural test runs the real heredoc directly and through a ~/.local/bin symlink and fails on main. The parity test keeps the build.yml PowerShell copy and the build-desktop.sh printf identical line for line. Base is main, it is mergeable, checks are green and all three AI lanes say PASS. — crew-pr-reviewer (deep re-check)
Problem / Motivation
Goal: Running the packaged
kirocrewCLI from a shell that exportsPYTHONPATHorPYTHONHOMEalways runs the shipped backend, never a checkout mixed into it.PR #17852 made the desktop shell drop
PYTHONPATH/PYTHONHOMEfor the gateway it spawns. The bundled launchers users run directly were left alone: the POSIXbin/kirocrewscript (reached through the~/.local/bin/kirocrewsymlink and named by the AppImage token page) and the Windowsbin\kirocrew.cmdshim both forwarded the whole inherited environment to the bundled interpreter. Akirocrew tokenorkirocrew stoptyped in a development shell withPYTHONPATH=<checkout>/srctherefore imported checkout code into the packaged CLI, the same "wrong backend" failure as #17850 through a path the shell-side scrub cannot see.Why it matters
Anyone who develops Kiro Crew and also uses the desktop app hits this the first time they mint a token or stop the gateway from their dev shell. The failure looks like an unrelated import or attribute error from the packaged CLI, so it is slow to diagnose, and
stopagainst the wrong code can leave a gateway running.Not a goal
gateway-env.js); its scrub stays as the second guard.PYTHON*variable (PYTHONUTF8,PYTHONIOENCODING, bytecode knobs); the shell relies on handing those down.packaging/build-desktop.shand which keepPYTHONPATHfor development by design.Intended? / Repro
Intended? No. The launcher's only env-related comment on main explains
-s/-P(user site and cwd offsys.path); nothing mentions keepingPYTHONPATH.git log -S'-s -P -m kiro_crew' -- packaging/build-desktop.shfinds one commit, #13307, which added-Pfor the stdlib-shadowing case and says nothing about the environment.docs/build/desktop-app.md(as written by #17852) documents the scrub as a property of bundled backends and states that only "source-tree gateway launches retain those environment variables for development"; the bundled launcher is never a source-tree launch. #17852 itself filed #18378 as a deliberately deferred follow-up on the Design lane's watch item. No doc, comment, or override env names a mode where the bundled launcher should honourPYTHONPATH.Repro on
origin/main@ de2d143, no test suite: extract the launcher heredoc frompackaging/build-desktop.shinto a temp fake bundle beside a stubpython3.12that prints its environment, plant a~/.local/bin/kirocrew-style symlink, run withPYTHONPATH=/home/dev/checkout/src PYTHONHOME=/home/dev/other-python PYTHONUTF8=1.Observed (both the direct launcher and the symlink shim):
Expected:
PYTHONPATH=<unset>,PYTHONHOME=<unset>,PYTHONUTF8=1. The same run against this branch prints the expected lines. The Windows shim on main renders to two lines,@echo offand thepython.exeinvocation, with nosetin between.What changed (motivation → approach → change)
Symptom: the bundled interpreter inherited
PYTHONPATH/PYTHONHOMEwhen a user ran the launcher directly. Root cause: the scrub from #17852 lives in the desktop shell's spawn helper, which is one caller; the launcher is the entry point every caller shares (shell, user shell,~/.local/binsymlink, AppImage token page), and it did nothing to its environment.Approach: scrub at the shared entry point. The POSIX launcher runs
unset PYTHONPATH PYTHONHOMEbeforeexec; the Windowskirocrew.cmdrunsset "PYTHONPATH="andset "PYTHONHOME="undersetlocal, so cmd's case-insensitive environment loses mixed-case spellings too and an interactivecmdwindow keeps its own variables after the command returns.-Ewas rejected because it also discardsPYTHONUTF8,PYTHONIOENCODINGand the bytecode settings the shell deliberately hands down. Descendants of the backend (operator Python, MCP servers, cron) inherit the scrubbed environment, which is already the documented behaviour under the desktop shell.The Windows installer workflow (
.github/workflows/build.yml) writes its own copy ofkirocrew.cmdin PowerShell, and that copy is the shim the Windows installer smoke actually boots; it now writes the same five lines, and a parity test holds the two writers to identical lines so they cannot drift again.gateway-recovery.jsonly gains a comment: the Windows unwrap bypasses the.cmd, so for that spawn the shell'sbuildGatewayEnvironment({ bundled: true })remains the scrub.docs/build/desktop-app.mdgains a paragraph on the launcher-level scrub.Backwards compatibility
Compatible: the launchers accept the same arguments and exec the same interpreter with the same flags; only
PYTHONPATH/PYTHONHOMEstop reaching the bundled interpreter, anddocs/build/desktop-app.mdalready told a child relying on them under the desktop app to set them itself.Removes nothing: no path, record, key, or function is removed or renamed; the diff adds two environment deletions to generated scripts and documents them.
Tests
test/test_build_desktop_launcher_symlink.py::test_strips_inherited_pythonpath_and_pythonhome_through_the_shimruns the real launcher heredoc, directly and through a~/.local/bin-style symlink, with both variables poisoned and asserts the stub interpreter sees neither. Red on main (the stub printed the poisoned values).::test_keeps_the_other_python_knobs_the_shell_hands_downpins thatPYTHONUTF8andPYTHONDONTWRITEBYTECODEstill reach the interpreter (guards against a future-E).::test_launcher_keeps_the_python_env_scrubnames theunsetline and forbids-Eon the exec line.test/test_build_desktop_windows_launcher.pyrenders thekirocrew.cmdprintfformat (%%,\\,\r\n) and asserts the twosetdeletions precede thepython.exeline,setlocalprecedes the firstset, and the interpreter line is still exactly"%~dp0..\python.exe" -s -P -m kiro_crew %*. Red on main (two-line shim, noset).::test_build_workflow_writes_the_same_cmd_launcherparses theSet-Content -Value @(...)array in.github/workflows/build.ymland asserts it equals the renderedprintflines. Red on main (the workflow wrote the two-line shim).Manual verification
Standalone repro script described under Intended? / Repro, run against main (observed poisoned values) and against this branch (observed
<unset>for both,PYTHONUTF8=1kept). Theprintfformat was rendered with bash and inspected withcat -Ato confirm CRLF line endings and the quotedsetlines.bash -n packaging/build-desktop.shandnode --check website/electron/gateway-recovery.jspass. A realcmd.exerun of the new shim happens in this PR'sBuild Windows Installer (x64)job, which builds the installer from thebuild.ymlcopy and boots the bundled backend through it; aPYTHONPATH-poisoned run on real Windows was not performed by hand.Related Issues
Fixes #18378
Refs #17852, #17850
Pattern harvest
Rule candidate: review-prompt
Pattern: an environment scrub added at one spawner while the shared launcher or entry point every caller uses still forwards the raw environment.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)