Skip to content

fix: isolate bundled desktop gateway from Python overrides - #17852

Merged
iamwhatever merged 2 commits into
mainfrom
fix/desktop-bundled-python-env-r21
Oct 9, 2026
Merged

iamwhatever merged 2 commits into
mainfrom
fix/desktop-bundled-python-env-r21

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

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 PYTHONPATH and PYTHONHOME from 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

  • Scoped to Electron-spawned bundled-gateway processes. This PR scrubs PYTHONPATH/PYTHONHOME only on the processes Electron spawns and stops through gateway-supervisor.js. It does not touch the bundled bin/kirocrew launcher (packaging/build-desktop.sh:548) or the ~/.local/bin/kirocrew shim, 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.
  • No change to PYTHONNOUSERSITE: user-site imports in operator Python, ACP, and MCP child processes must keep working. The bundled launcher already uses -s to disable user-site for the gateway itself.
  • No change to the UTF-8 overrides (PYTHONUTF8/PYTHONIOENCODING), which still deliberately override hostile inherited values.
  • No change to source-tree (development) gateway launches, which must retain the inherited import roots.

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 inherited PYTHONPATH and PYTHONHOME (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 in gateway-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 pass bundled: false and 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/PYTHONHOME either; docs/build/desktop-app.md now 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 the runGatewayStop boundary.
  • 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 inherit PYTHONPATH/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 — new win32/darwin/linux cases assert that a bundled spawn removes PYTHONPATH/PYTHONHOME, handles Windows mixed-case keys, preserves PYTHONNOUSERSITE, 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/bin shim still pass PYTHONPATH/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

@iamwhatever
iamwhatever requested a review from a team as a code owner October 7, 2026 20:48
@iamwhatever
iamwhatever requested a review from CrysisDeu October 7, 2026 20:48
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 7, 2026
@github-actions

github-actions Bot commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

UX-level review of 93ed8b5a135e6de18d123e4c6192ffe66b6478c4 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 93ed8b5a135e6de18d123e4c6192ffe66b6478c4 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

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 PYTHONPATH.

What this change ships

Inventory (5 items) — 5 justified

Intent: 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).

  1. When the app spawns its bundled gateway, inherited PYTHONPATH/PYTHONHOME are removed, including mixed-case spellings on Windows. Source-tree launches keep them. — justified
  2. The stuck-gateway stop (the CLI stop the app runs on a gateway that won't respond) gets the same scrub when it runs the bundled binary. — justified
  3. That stop child now also gets the UTF-8 env overrides, a side effect of routing it through buildGatewayEnvironment. — justified
  4. The bundled gateway's descendants (operator Python, MCP servers, cron) no longer inherit a shell PYTHONPATH/PYTHONHOME. — justified
  5. docs/build/desktop-app.md documents the isolation and what descendants lose. — justified

[FIRST-PRINCIPLES-REVIEWED] 93ed8b5

Description read

[DESCRIPTION-READ] 45ae93cfb1ba7cb6b414e865347c59cd69b6e0677efd55d41251c1054503badb

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 93ed8b5a135e6de18d123e4c6192ffe66b6478c4 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Before merge, check one thing: does a packaged build launched from a shell that exports PYTHONPATH/PYTHONHOME now start its own backend? No unit test covers this.

[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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 93ed8b5a135e6de18d123e4c6192ffe66b6478c4 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 93ed8b5

Verdict parsed from the review's SHA-scoped output markers for commit 93ed8b5a135e6de18d123e4c6192ffe66b6478c4.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 93ed8b5a135e6de18d123e4c6192ffe66b6478c4: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 93ed8b5a135e6de18d123e4c6192ffe66b6478c4 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 93ed8b5

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 93ed8b5a135e6de18d123e4c6192ffe66b6478c4: <one-sentence reason>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 7, 2026
@iamwhatever
iamwhatever force-pushed the fix/desktop-bundled-python-env-r21 branch from 9ad99ca to ba6d0a2 Compare October 8, 2026 00:13
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 8, 2026
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 8, 2026
@KiroCrewCaptain
KiroCrewCaptain enabled auto-merge (squash) October 8, 2026 04:23
KiroCrewCaptain
KiroCrewCaptain previously approved these changes Oct 8, 2026

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.]

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Self-review (crew-pr-reviewer, read-only): CHANGES NEEDED

Reviewed head ba6d0a2. The launch path now strips PYTHONPATH and PYTHONHOME. But runGatewayStop (gateway-supervisor.js:870) still runs the same bundled binary with the raw processObj.env, so a stuck-gateway stop from a dev shell can still run checkout code (First Principles). Please route that call through the same clean env, then add a test for it. Moving to draft.

@iamwhatever
iamwhatever marked this pull request as draft October 8, 2026 05:15
auto-merge was automatically disabled October 8, 2026 05:15

Pull request was converted to draft

@iamwhatever

Copy link
Copy Markdown
Contributor Author

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 checking, turns auto-merge off, and stops this PR from merging until the point is fixed.

To resume: fix it, push, then run gh pr ready 17852 and re-enable auto-merge if wanted.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision labels Oct 8, 2026
@iamwhatever
iamwhatever force-pushed the fix/desktop-bundled-python-env-r21 branch from ba6d0a2 to 20fcb3a Compare October 8, 2026 07:51
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Addressed the self-review point (crew-pr-reviewer, head ba6d0a2).

runGatewayStop (gateway-supervisor.js) now routes its execFile env through the same buildGatewayEnvironment(..., { bundled, platform }) helper the launch path uses, detecting bundled the same way the spawn does (resolveGatewayBin() lands under backend-dist). So the stuck-gateway stop runs the bundled binary with PYTHONPATH/PYTHONHOME stripped, closing the dev-shell checkout-code leak on the stop path.

Added a regression test (gateway-supervisor.test.js, "the stuck-gateway stop strips PYTHONPATH/PYTHONHOME from the bundled binary's env") that fails on the raw-env version and passes with the fix.

New head: 20fcb3a292a7e59099f879dae6f184d84c6882ee.

@iamwhatever
iamwhatever marked this pull request as ready for review October 8, 2026 07:52
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 8, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Self-review (crew-pr-reviewer, read-only): CHANGES NEEDED

The PR strips inherited PYTHONPATH/PYTHONHOME from bundled-gateway spawns so a desktop app launched from a dev shell runs its packaged backend. iamwhatever's earlier request is addressed on head 20fcb3a: runGatewayStop (website/electron/gateway-supervisor.js:869-881) now goes through buildGatewayEnvironment(..., { bundled }), with bundled detected the same way as the spawn (bin.includes("backend-dist"), line 1252), and a new supervisor test checks the stop env. Checks are green and the GPT/Opus lanes pass. The Design CONCERNS on this head is still unanswered and points at a real side effect. The gateway's environment is what its operator Python, MCP-server and cron children inherit, so an MCP server or script that relied on a shell-exported PYTHONPATH now silently stops resolving its imports under the desktop app. docs/build/desktop-app.md:602-609 says nothing about this, which is a takeaway users should be told about. The same Design item also notes the bundled bin/kirocrew launcher (packaging/build-desktop.sh:548) and the ~/.local/bin/kirocrew shim still pass these variables through, so the fix covers Electron's spawns only. Suggested fix: add one sentence to the doc paragraph saying the bundled gateway's child processes no longer inherit PYTHONPATH/PYTHONHOME. Then scope the description to Electron-spawned processes and file a follow-up issue for the launcher/shim path (or unset the variables in the launcher). Post a target=design disposition for each Watch item. — crew-pr-reviewer

@iamwhatever
iamwhatever marked this pull request as draft October 8, 2026 15:50
@iamwhatever

Copy link
Copy Markdown
Contributor Author

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 gh pr ready 17852 and it will be re-reviewed on the new head. — crew-pr-reviewer

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision labels Oct 8, 2026
buluoray
buluoray previously approved these changes Oct 8, 2026

@buluoray buluoray left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approve at 20fcb3a292a7e59099f879dae6f184d84c6882ee.

Verified at head:

  • website/electron/gateway-env.js:50-68 buildGatewayEnvironment: when bundled, it removes PYTHONPATH and PYTHONHOME from 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, with bundled derived from the resolved binary, so the packaged backend runs its own code on both paths.
  • packaging/build-desktop.sh:548 keeps 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.

iamwhatever pushed a commit that referenced this pull request Oct 9, 2026
…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).
@iamwhatever
iamwhatever force-pushed the fix/desktop-bundled-python-env-r21 branch from 20fcb3a to 1d58773 Compare October 9, 2026 07:18
cixuuz and others added 2 commits October 9, 2026 07:30
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>
@iamwhatever
iamwhatever force-pushed the fix/desktop-bundled-python-env-r21 branch from 1d58773 to 93ed8b5 Compare October 9, 2026 07:31
@iamwhatever
iamwhatever marked this pull request as ready for review October 9, 2026 08:15
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Addressed the self-review points on head 93ed8b5a135e6de18d123e4c6192ffe66b6478c4:

  1. Doc note — docs/build/desktop-app.md now says the bundled gateway's operator Python, MCP-server, and cron child processes no longer inherit a shell-exported PYTHONPATH/PYTHONHOME, so a child that relied on one must set it for itself.
  2. Description scoped to Electron — the "Not a goal" and "What changed" sections now state the scrub covers only the Electron-spawned bundled-gateway processes (both the spawn and the runGatewayStop stop boundary, which also now gets the UTF-8 env), not the launcher/shim.
  3. Follow-up issue filed — Bundled bin/kirocrew launcher and ~/.local/bin shim still pass PYTHONPATH/PYTHONHOME through #18378 tracks the bundled bin/kirocrew launcher (packaging/build-desktop.sh:548) and the ~/.local/bin/kirocrew shim still passing these vars through; linked from the PR, launcher left unchanged here to keep the change minimal.
  4. Design dispositions — not needed: on the new head the Design Review re-evaluated to ✅ PASS (both Watch items cleared by the scoped description + follow-up Bundled bin/kirocrew launcher and ~/.local/bin shim still pass PYTHONPATH/PYTHONHOME through #18378 + the doc paragraph), so there is no open finding to disposition.

Also rebased onto current origin/main and squashed to 2 commits for the commit-count gate. All check-runs are green (0 reds) and every review lane (Design / First Principles / UX / Opus / GPT) is PASS / no findings on this head. Marked ready.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 9, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Self-review (crew-pr-reviewer, read-only): RECOMMEND APPROVE

buildGatewayEnvironment (website/electron/gateway-env.js) strips inherited PYTHONPATH/PYTHONHOME for a bundled backend, matching keys case-insensitively on Windows, so a desktop app started from a dev shell runs its packaged code. iamwhatever's earlier requests are addressed. runGatewayStop (gateway-supervisor.js:867-881) goes through the same helper, with bundled detected the same way as the spawn. docs/build/desktop-app.md now says the bundled gateway's operator-Python, MCP and cron children no longer inherit those variables. The description is scoped to Electron-spawned processes, and the launcher/shim gap is tracked in open issue #18378. Design, First Principles, UX, Opus and GPT are all PASS or no findings on 93ed8b5, so no Design disposition is outstanding, and all checks are green. The supervisor and env tests cover both the spawn and the stop env and fail on the raw-env version. The branch has two commits, within the limit. — crew-pr-reviewer

@iamwhatever
iamwhatever enabled auto-merge (squash) October 9, 2026 16:34

@buluoray buluoray left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@iamwhatever
iamwhatever merged commit cb10251 into main Oct 9, 2026
105 checks passed
@iamwhatever
iamwhatever deleted the fix/desktop-bundled-python-env-r21 branch October 9, 2026 19:20
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 9, 2026
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.

Bundled desktop gateway inherits PYTHONPATH/PYTHONHOME and loads checkout code

4 participants