Skip to content

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

Closed
pstarkgit wants to merge 1 commit into
kirodotdev:mainfrom
pstarkgit:fix/desktop-bundled-python-env
Closed

pstarkgit wants to merge 1 commit into
kirodotdev:mainfrom
pstarkgit:fix/desktop-bundled-python-env

Conversation

@pstarkgit

@pstarkgit pstarkgit commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: The bundled desktop gateway always runs its own bundled Python code and runtime, whatever Python environment variables the app inherits.

A bundled Kiro Crew gateway can import Python code from a development checkout when the desktop app inherits PYTHONPATH. The saved bundled prompt.md URI then resolves as an external essential source, interrupting member chats with outside the admitted document root. PYTHONHOME can likewise override the bundled runtime.

Why it matters

After an update or restart, the app may appear healthy while member chats fail. On Windows, Python environment keys are case-insensitive, so mixed-case inherited names bypass exact-key deletion.

Not a goal

What changed (motivation → approach → change)

  • Centralize bundled-only Python environment cleanup in website/electron/gateway-env.js, the environment builder used by every owned gateway spawn. Remove inherited PYTHONPATH and PYTHONHOME; on Windows, remove every case variant.
  • website/electron/gateway-supervisor.js supplies the bundled flag and platform; source launches retain their development overrides. The packaged launcher already uses -s for its own user-site isolation, so no inherited user-site setting is changed for child tools.
  • Add regression coverage in website/electron/test/gateway-env.test.js and document the launch behavior in docs/build/desktop-app.md.

Backwards compatibility

Compatible: only bundled gateway launches receive Python import isolation. Source-tree development gateways retain their inherited Python environment. The parent process environment is not modified.

Tests

  • 43 focused gateway environment and supervisor tests passed.
  • The new platform-simulation regressions fail against the original helper and pass with this fix.
  • Documentation checks, syntax, and whitespace checks passed. Native Windows execution remains unverified.

Manual verification

The failure mechanism was reproduced with an installed interpreter and inherited checkout PYTHONPATH; clearing that override restored bundled-package imports. This revised patch has not yet been exercised in a rebuilt signed desktop app, so release validation must include an update/restart with an active session.

Screenshots / video

N/A — the change is in the gateway process environment and has no rendered interface delta.

Related Issues

Related to #13664, which handles stale gateway adoption after a desktop update.

Pattern harvest

Rule candidate: review-prompt
Pattern: packaged Python launchers must exclude inherited import-root and user-site overrides, including case variants on Windows, without changing child-tool user-site settings.

Checklist

  • At most two commits, with a Conventional Commits title
  • Existing focused tests pass and new regression tests cover the behavior
  • Self-review completed; code follows project style guidelines
  • Documentation updated
  • No secrets, credentials, or internal references in the diff

@pstarkgit
pstarkgit requested review from a team and chenmingwei23 September 25, 2026 03:54
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 25, 2026
@github-actions

github-actions Bot commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Fable 5, fork) — ✅ PASS

UX-level review of bbc7d749ffc28578097c692e41b05b0d7d5fd766 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

UX-Verdict: PASS

Nothing to check.

[UX-REVIEWED] bbc7d74

Description read

[DESCRIPTION-READ] e878bf48b8fab8c4fa8ad40e1c27f28f7c861a633a312aa2cbc60ba6dc8885c0

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 Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — ✅ PASS

Design-level review of bbc7d749ffc28578097c692e41b05b0d7d5fd766 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Verify on a rebuilt signed desktop app (update/restart with an active session, Windows included) — the PR itself names this as untested.

[DESIGN-REVIEWED] bbc7d74

Description read

[DESCRIPTION-READ] 3ba6aae6de01482608d7888ecd45fb97fc1ce790533838b0e985194493ca593d

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 Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — ✅ no blocking findings

Reviewed bbc7d749ffc28578097c692e41b05b0d7d5fd766 via the fork AI-review pipeline; updated in place on each push.

Review details

FINDING -- website/electron/gateway-supervisor.js:1353 -- "bundled" is also true for dirname-relative unpackaged development backends, so their PYTHONPATH/PYTHONHOME overrides are removed contrary to the stated scope -> Fix: pass bundled: app.isPackaged && bundled (origin: validation).
[GPT-REVIEWED] bbc7d74

@github-actions

github-actions Bot commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5, fork) — ✅ PASS

Premise-level review of bbc7d749ffc28578097c692e41b05b0d7d5fd766 via the fork AI-review pipeline — 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

Verify on a rebuilt signed app and native Windows — the description itself says both remain unexercised, and the case-insensitive delete only matters there.

What this change ships

Inventory (5 items) — 5 justified

Intent: FIX — a packaged desktop gateway launched from a development shell imports the checkout instead of its bundled code, breaking member chats; strip the inherited Python overrides at spawn.

  1. Bundled gateway spawn drops inherited PYTHONPATH/PYTHONHOME — justified
  2. On Windows, mixed-case spellings of those two keys are dropped too — justified
  3. Source-tree/development gateway launches keep their inherited Python environment (bundled defaults false) — justified
  4. buildGatewayEnvironment gains a {bundled, platform} options parameter — justified
  5. Desktop-build doc gains a paragraph describing the launch isolation, same commit — justified

Evidence checked: defect has provenance (reproduction in description; new tests the description says fail on base). Grep buildGatewayEnvironment: 1 production consumer (gateway-supervisor.js:1332), the pinned single owned spawn boundary, so no sibling spawn is left unfixed. Windows -s -P flags on base do not neutralize PYTHONPATH/PYTHONHOME, and -E would also kill the deliberate PYTHONUTF8/PYTHONPYCACHEPREFIX values, so no existing smaller mechanism does this job. No deleted pins; scope limited to bundled launches as the Goal states.

[FIRST-PRINCIPLES-REVIEWED] bbc7d74

Description read

[DESCRIPTION-READ] f17168304e1dc5e237f528831c68949597b88a8f0644f064dfe78dc2d2bc0748

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 added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 25, 2026
@github-actions

github-actions Bot commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review (fork) — ✅ no blocking findings

Reviewed bbc7d749ffc28578097c692e41b05b0d7d5fd766 via the fork AI-review pipeline; updated in place on each push.

Review details

No blocking defects; one advisory — the new bundled-backend import isolation covers only the gateway spawn.

FINDING — website/electron/gateway-supervisor.js:316 — the two other spawns of the same resolveGatewayBin() bundled backend build their env straight from processObj.env (getEnv: () => { const { KIROCREW_PORT: _unused, ...tunnelEnv } = processObj.env; for tunnel-keeper.js:69's desktop tunnel, and env: { ...cleanEnv, KIROCREW_HOME } at gateway-supervisor.js:871's stop --expect-pid), never through buildGatewayEnvironment, so a packaged app launched from a shell exporting PYTHONPATH runs a foreign checkout's kiro_crew for the tunnel keeper and the stuck-gateway stop while the gateway itself is now isolated — contradicting the unqualified "the shell removes inherited PYTHONPATH and PYTHONHOME before spawning Python" added at docs/build/desktop-app.md:582 → Fix: route both call sites through buildGatewayEnvironment(..., { bundled, platform: processObj.platform }) (edits untouched code in tunnel-keeper.js/runGatewayStop, hence advisory), or scope the doc sentence to the gateway spawn.

[OPUS-REVIEWED] bbc7d74

@pstarkgit
pstarkgit force-pushed the fix/desktop-bundled-python-env branch from 2444ec3 to 1109566 Compare September 25, 2026 04:55
@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 Sep 25, 2026
@pstarkgit
pstarkgit force-pushed the fix/desktop-bundled-python-env branch from 1109566 to edc11b4 Compare September 25, 2026 05:11
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Sep 25, 2026
@pstarkgit
pstarkgit force-pushed the fix/desktop-bundled-python-env branch from edc11b4 to 4d4e82b Compare September 28, 2026 14:03
@pstarkgit
pstarkgit requested a review from a team as a code owner September 28, 2026 14:03
@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 Sep 28, 2026
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Sep 28, 2026
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.
@pstarkgit
pstarkgit force-pushed the fix/desktop-bundled-python-env branch from 4d4e82b to bbc7d74 Compare October 2, 2026 22:41
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 2, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

Thank you for this fix, @pstarkgit! The desktop bundled-gateway Python isolation has been carried into an in-repo replacement PR #17852 (rebased onto current main, with your commit co-authored to you), which is green and ready for review. Closing this one in favor of #17852. Much appreciated!

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

Labels

fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants