Repository navigation
fix: isolate bundled desktop gateway from Python overrides - #17852
Conversation
UX Review (Opus 5.5) — ✅ PASSUX-level review of UX-Verdict: PASS Nothing to check. [UX-REVIEWED] 93ed8b5 Description read[DESCRIPTION-READ] dd6216fd06deda36cccbfdb997f9a9cf4881f43d32198310934ce756fa3960c4 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, check that it's acceptable for the bundled gateway's operator-Python, MCP and cron children to lose a shell-exported What this change shipsInventory (5 items) — 5 justifiedIntent: when the desktop app is opened from a development shell, it should run its own packaged backend, not checkout code pulled in by the shell's Python environment. This is a FIX (#17850).
[FIRST-PRINCIPLES-REVIEWED] 93ed8b5 Description read[DESCRIPTION-READ] 45ae93cfb1ba7cb6b414e865347c59cd69b6e0677efd55d41251c1054503badb That sha256 names the PR description this verdict read. Recompute it with |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Before merge, check one thing: does a packaged build launched from a shell that exports [DESIGN-REVIEWED] 93ed8b5 Description read[DESCRIPTION-READ] 54deb120b7bf197bbc26731cd0ff4a0f9727261fda8b7d5f6d375803f591a7f9 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: |
9ad99ca to
ba6d0a2
Compare
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
Deep review passed: fix (4 files). The First Principles CONCERN is real but not a regression: runGatewayStop (gateway-supervisor.js, execFile of the same bundled bin with unscrubbed env) still inherits PYTHONPATH/PYTHONHOME, a pre-existing Linux-only stuck-gateway stop path this PR leaves as it was. The Design lane's descendant point is a suggestion; the spawn change itself is correct and tested on all three platforms.
[Security: the change only removes PYTHONPATH and PYTHONHOME from the environment of the bundled backend child, so the packaged backend loads its own code; it widens nothing. The unscrubbed stop path in gateway-supervisor.js is pre-existing and not touched here.]
|
Self-review (crew-pr-reviewer, read-only): CHANGES NEEDED Reviewed head |
Pull request was converted to draft
|
Moved to draft by crew-pr-reviewer (self-review gate). The self-review comment above lists a point this PR still needs. GitHub does not let an author request changes on their own PR, and PR Readiness does not read human reviews, so a draft is the signal: it keeps readiness at To resume: fix it, push, then run |
ba6d0a2 to
20fcb3a
Compare
|
Addressed the self-review point (crew-pr-reviewer, head
Added a regression test ( New head: |
|
Self-review (crew-pr-reviewer, read-only): CHANGES NEEDED The PR strips inherited |
|
Moved to draft by crew-pr-reviewer: the self-review above is CHANGES NEEDED. GitHub refuses a self-request-changes, and the readiness check ignores human reviews, so draft is how this PR is kept from merging (it also turns auto-merge off). Once the points above are fixed, mark it ready again with |
There was a problem hiding this comment.
Approve at 20fcb3a292a7e59099f879dae6f184d84c6882ee.
Verified at head:
website/electron/gateway-env.js:50-68buildGatewayEnvironment: whenbundled, it removesPYTHONPATHandPYTHONHOMEfrom the environment handed to the gateway, matching keys case-insensitively on Windows.website/electron/gateway-supervisor.js:881(stop path for a stuck gateway) and:1341(spawn) both build the child environment through it, withbundledderived from the resolved binary, so the packaged backend runs its own code on both paths.packaging/build-desktop.sh:548keeps the build consistent with the runtime isolation.
Fail-closed: no new refusal path; the only effect is a narrower inherited environment for the bundled binary. A source-tree gateway keeps the variables.
Upgrade impact / audience fit: an app opened from Finder, Dock, the Start menu or a launcher never inherited these variables, so default users see no change. Only someone launching the packaged app from a shell that exports them is affected, and today that silently runs checkout code under the packaged app, which is the bug.
Mutation: 4 mutations each redden a named test (the spawn-site one via a source assertion). node --test on gateway-env + gateway-supervisor: 115/118 locally; the 3 failing stale-bundle tests also fail on the merge base on this host, and CI is green.
Non-blocking follow-up: log one line when keys are removed, so someone relying on an intentional override can see why it stopped applying.
Not run: Windows or macOS, a packaged build launch.
…YTHONHOME The bundled gateway's environment is what its operator Python, MCP server, and cron child processes inherit. Since the spawn and stop paths now scrub PYTHONPATH/PYTHONHOME, those descendants no longer inherit a shell-exported value either. Document it so a child that relied on one knows to set it for itself (Design Review Watch item on #17852).
20fcb3a to
1d58773
Compare
A desktop app launched from a development shell can inherit PYTHONPATH and load checkout code instead of its packaged backend. That makes the saved prompt URI fail essential document admission after an update. Drop Python import-root overrides at the bundled spawn boundary while preserving them for source-tree gateways. Co-authored-by: pstarkgit <48455568+pstarkgit@users.noreply.github.com>
The launch path strips PYTHONPATH/PYTHONHOME for a bundled binary, but runGatewayStop still execFile'd the same bundled binary with the raw process env. A stuck-gateway stop triggered from a development shell could therefore run checkout code in the packaged backend — the exact override leak this PR exists to close, left open on the stop path. Route runGatewayStop's execFile env through buildGatewayEnvironment with the same bundled detection (resolveGatewayBin lands under backend-dist) the spawn uses, so the stop inherits the identical scrubbed environment. Adds a regression test that fails without the fix. Co-authored-by: pstarkgit <48455568+pstarkgit@users.noreply.github.com>
1d58773 to
93ed8b5
Compare
|
Addressed the self-review points on head
Also rebased onto current |
|
Self-review (crew-pr-reviewer, read-only): RECOMMEND APPROVE
|
buluoray
left a comment
There was a problem hiding this comment.
Re-review after the dismissed approval (previous approved head 20fcb3a, now 93ed8b5).
This revision is a rebase onto current main plus one documentation addition. The gateway environment builder, the supervisor's start and stop paths and their tests are identical to the approved revision. The new paragraph in the desktop-app build doc spells out the consequence of the scrub: processes the bundled gateway spawns (operator Python, MCP servers, cron children) no longer inherit a shell-exported PYTHONPATH or PYTHONHOME, so a child that relied on one has to set it itself. That's the right upgrade note for anyone affected.
CI is green on this head (91 success, 8 skipped). Approval holds.
Problem / Motivation
Goal: A desktop app launched from a development shell runs its packaged backend, not whatever checkout the shell's Python environment points at.
A desktop app launched from a development shell inherits
PYTHONPATHandPYTHONHOMEfrom that shell. When the shell spawns the bundled (packaged) backend, those inherited import roots make Python load checkout code instead of the packaged backend. After an app update this makes the saved-prompt URI fail essential document admission, because the running code no longer matches the shipped backend.Why it matters
A user who develops against a checkout and also runs the installed desktop app silently gets the wrong backend after an update. The symptom (saved-prompt URI failing document admission) is confusing and hard to diagnose, because nothing visibly says the app is importing checkout code.
Not a goal
PYTHONPATH/PYTHONHOMEonly on the processes Electron spawns and stops throughgateway-supervisor.js. It does not touch the bundledbin/kirocrewlauncher (packaging/build-desktop.sh:548) or the~/.local/bin/kirocrewshim, which still pass these variables through when a user runs the CLI directly. That launcher/shim path is tracked as a follow-up in Bundled bin/kirocrew launcher and ~/.local/bin shim still pass PYTHONPATH/PYTHONHOME through #18378, kept out of this PR to keep the change minimal.PYTHONNOUSERSITE: user-site imports in operator Python, ACP, and MCP child processes must keep working. The bundled launcher already uses-sto disable user-site for the gateway itself.PYTHONUTF8/PYTHONIOENCODING), which still deliberately override hostile inherited values.What changed (motivation → approach → change)
Symptom: a bundled desktop gateway imports checkout code → root cause:
buildGatewayEnvironment()never strips the inherited import-root variables for a bundled spawn → change: for a bundled backend spawn only,buildGatewayEnvironment()now deletes inheritedPYTHONPATHandPYTHONHOME(including Windows mixed-case spellings, since Windows env keys are case-insensitive) so the packaged backend imports its own code and stdlib. Both owned boundaries ingateway-supervisor.js— the spawn and the stuck-gateway stop (runGatewayStop) — pass{ bundled, platform: processObj.platform }through the same helper, so the stop path is scrubbed the same way and the stop child also receives the same UTF-8 env overrides the spawn uses. Development launches passbundled: falseand are unchanged.Because the bundled gateway's environment is what its operator Python, MCP-server, and cron child processes inherit, those descendants no longer inherit a shell-exported
PYTHONPATH/PYTHONHOMEeither;docs/build/desktop-app.mdnow documents this so a child that relied on one must set it for itself.Files:
website/electron/gateway-env.js— add{ bundled, platform }option; delete import-root vars when bundled.website/electron/gateway-supervisor.js— pass{ bundled, platform: processObj.platform }at both the owned spawn boundary and therunGatewayStopboundary.website/electron/test/gateway-env.test.js— new per-platform tests.website/electron/test/gateway-supervisor.test.js— regression test that the bundled stop env is scrubbed.docs/build/desktop-app.md— document the bundled-spawn isolation and that spawned descendants no longer inheritPYTHONPATH/PYTHONHOME.Backwards compatibility
Compatible: the new behavior applies only to a bundled spawn (
bundled: true); development/source-tree launches (bundled: false, the default) keep every inherited variable exactly as before. The second argument is optional and defaults to{ bundled: false, platform: process.platform }, so existing callers are unaffected.Removes nothing: no user-facing capability, record, key, or public function is removed; only inherited process-environment variables are dropped from a packaged backend child it already owns.
Tests
website/electron/test/gateway-env.test.js— newwin32/darwin/linuxcases assert that a bundled spawn removesPYTHONPATH/PYTHONHOME, handles Windows mixed-case keys, preservesPYTHONNOUSERSITE, does not mutate the input env, and that a development (bundled: false) spawn passes every variable through unchanged.website/electron/test/gateway-supervisor.test.js— a regression test asserts the bundled stuck-gateway stop runs with the scrubbed env, and fails without the fix.Manual verification
N/A — unit coverage over the environment builder across all three desktop platforms, plus the supervisor stop regression test, is sufficient; the change is to process-environment construction with no UI surface.
Related Issues
Fixes #17850
Follow-up: #18378 (bundled launcher /
~/.local/binshim still passPYTHONPATH/PYTHONHOME)Pattern harvest
Not generalizable: this is scoped to the Electron-owned bundled-gateway spawn and stop boundaries; the launcher/shim entry point is tracked separately in #18378, and the new per-platform tests lock the boundary's behavior in.
Replaces #13669 by @pstarkgit