Skip to content

fix(desktop): drop inherited PYTHONPATH/PYTHONHOME for a packaged spawn - #18388

Closed
yiyabo wants to merge 1 commit into
kirodotdev:mainfrom
yiyabo:fix/gateway-strip-pythonpath
Closed

yiyabo wants to merge 1 commit into
kirodotdev:mainfrom
yiyabo:fix/gateway-strip-pythonpath

Conversation

@yiyabo

@yiyabo yiyabo commented Oct 9, 2026

Copy link
Copy Markdown

Problem / Motivation

Goal: A packaged desktop app launched from a development shell runs the backend it shipped, never the checkout that shell happens to point at.

Bug fix (#17850): a desktop app launched from a development shell inherits PYTHONPATH and PYTHONHOME. When the shell spawns the bundled backend, those inherited import roots make Python load checkout code instead of the packaged backend, so after an app update the running gateway no longer matches the shipped backend and the saved-prompt URI fails essential document admission.

Why it matters

Anyone who develops Kiro Crew (or any Python project) and launches the packaged desktop app from the same shell is hit: the app silently runs different code than the version it reports and signed, and the failure only surfaces later, as admission refusals that read like backend bugs. The bundled backend's value is being a known, shipped, updated artifact — inherited import roots void that.

Not a goal

  • Stripping any other inherited Python knob (PYTHONSTARTUP, user site-packages): the issue names PYTHONPATH/PYTHONHOME, and the Windows .cmd-shim spawn already passes -s.
  • Changing source-tree gateway launches: they keep the variables, because there they are how the checkout under test is found at all.
  • Other backend probes (launch-preflight's version checks): outside the issue's scope; only the owned gateway spawn redirects the backend's imports.

What changed (motivation → approach → change)

Observed symptom: a packaged app launched from a dev shell imports the checkout; an update then fails saved-prompt document admission. Root cause: buildGatewayEnvironment() pinned the encoding variables but passed PYTHONPATH/PYTHONHOME straight through from the parent shell. Change: buildGatewayEnvironment takes an isPackaged flag (default false, the pre-flag contract) and, for a packaged spawn, drops both names case-folded, because Windows honors any casing; the one owned spawn boundary in gateway-supervisor.js passes app.isPackaged, covering the first launch and every liveness respawn. The source-reading pin on that boundary moves with it and now requires the flag.

Backwards compatibility

Compatible: the new parameter defaults to the pre-flag behavior, and the only caller (the owned gateway spawn) opts in for packaged builds; source-tree launches are byte-identical.

Removes nothing: a packaged backend never documented or supported operator-supplied import roots — inheriting them was the defect, not a capability.

Tests

  • New node:test cases in website/electron/test/gateway-env.test.js: a packaged spawn drops PYTHONPATH/PYTHONHOME while a source-tree spawn and the omitted-flag shape keep them, without mutating Electron's process.env; the strip folds case, so Windows spellings (PythonPath, pYtHoNhOmE) go too.
  • The spawn-boundary source pin now also requires app.isPackaged as the second argument.
  • Full electron suite on this branch: 2469 passed, 0 failed (4 skipped), node 22.

Manual verification

End-to-end on this branch (PYTHONPATH=/tmp/fake-checkout PYTHONHOME=/tmp/fake-home in the parent):

packaged    -> PYTHONPATH: None PYTHONHOME: None | checkout in sys.path: False
source-tree -> PYTHONPATH: /tmp/fake-checkout    | checkout in sys.path: True

The packaged child boots a clean interpreter with no import roots; the source-tree child still resolves the checkout, which is the development contract the issue asks to keep.

Related Issues

Fixes #17850

Pattern harvest

Rule candidate: review-prompt
Pattern: a spawned runtime inherits environment variables that redirect its module resolution (PYTHONPATH/PYTHONHOME here; the same shape exists for NODE_PATH, RUBYLIB, PERL5LIB) — a packaged spawn should not inherit them.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

A desktop app launched from a development shell inherits PYTHONPATH and
PYTHONHOME, so a packaged backend imports checkout code instead of the
bundle it shipped, and an app update then runs a gateway that no longer
matches its backend (kirodotdev#17850). buildGatewayEnvironment now takes
app.isPackaged and drops both names, case-folded for Windows, on the
one spawn boundary every launch and respawn passes through. Source-tree
launches keep the variables: there they are how the checkout under
test is found at all.
Copilot AI balanced review requested due to automatic review settings October 9, 2026 08:02
@yiyabo
yiyabo requested review from a team and KiroCrewCaptain as code owners October 9, 2026 08:02
@yiyabo
yiyabo requested a review from bolichen97 October 9, 2026 08:02

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

@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 Oct 9, 2026
@github-actions

github-actions Bot commented Oct 9, 2026

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — ✅ PASS

UX-level review of c3df04e3b7ef7280d2fa95f47e219b6b630be7de 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] c3df04e

Description read

[DESCRIPTION-READ] 51f6b640034601d6a05c98baba3a4b828bfeb4d70cce1a0ae9f7dd2714c080e9

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 9, 2026

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

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

Review details

No findings.
[GPT-REVIEWED] c3df04e

@github-actions

github-actions Bot commented Oct 9, 2026

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of c3df04e3b7ef7280d2fa95f47e219b6b630be7de 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

Nothing to check.

[DESIGN-REVIEWED] c3df04e

Description read

[DESCRIPTION-READ] 898d4b347da886cbd40a9a21bf5a6e1fb8938ab47e28ef1f35a3faf06aff7310

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 9, 2026

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — ✅ PASS

Premise-level review of c3df04e3b7ef7280d2fa95f47e219b6b630be7de 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

Check runGatewayStop (gateway-supervisor.js:870). It still runs the packaged kirocrew stop with the inherited PYTHONPATH/PYTHONHOME, which ## Not a goal doesn't cover.

What this change ships

Inventory (4 items) — 4 justified

Intent: a packaged desktop app started from a dev shell runs the backend it shipped, not the checkout the shell points at. This is a FIX for #17850.

  1. A packaged app's gateway spawn, including every liveness respawn, no longer inherits PYTHONPATH/PYTHONHOME — justified
  2. The strip ignores case, so Windows spellings like PythonPath are dropped too — justified
  3. buildGatewayEnvironment takes an isPackaged flag, default false, passed by its one caller as app.isPackaged — justified
  4. The spawn-boundary source-pin test now requires app.isPackaged as the second argument — justified

[FIRST-PRINCIPLES-REVIEWED] c3df04e

Description read

[DESCRIPTION-READ] 8ba2ccae0641a97711833fa783932e1bd933400edccefd2e754db652d1640927

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 9, 2026

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] c3df04e

@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
@yiyabo

yiyabo commented Oct 9, 2026

Copy link
Copy Markdown
Author

On the First Principles note about runGatewayStop (gateway-supervisor.js:870): fair catch, and deliberately deferred rather than absorbed here, since the gateway spawn's import roots are this PR's frozen goal.

Impact analysis for leaving it as-is in this PR: the child is kirocrew stop --port N --expect-pid P, and the --expect-pid contract re-reads the listener and this home's gateway.lock immediately before signaling, refusing unless that pid still holds both — so even a PYTHONPATH-redirected stop binary can only ever signal the pid the app already proved owns this gateway, never a foreign process. If the redirected code fails to parse anything, the stop reports failure and the caller (:932) degrades to re-proving the port (free → spawn, new holder → re-validate, still stuck → stopFailed with the incumbent pids). Worst case is a noisier stuck-gateway recovery, not a wrong kill.

Same class, worth closing: a follow-up PR that routes this child (and sweeps the other short-lived CLI children for the same inherited-env shape) through the same strip. Happy to pick that up once this lands.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 9, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

This stops a packaged desktop app from inheriting PYTHONPATH/PYTHONHOME from a dev shell, so the bundled backend imports its own code and not a checkout (#17850). The fix is at the root: buildGatewayEnvironment in website/electron/gateway-env.js takes an isPackaged flag and drops both names, case-folded so Windows spellings are caught too. The one owned spawn in gateway-supervisor.js passes app.isPackaged, so the first launch and every liveness respawn are covered. Source-tree launches keep the variables. I read the diff and the new node:test cases (packaged strip, source-tree keep, omitted-flag default, no mutation of the input, mixed-case names), and the code looks correct. All lanes PASS. HOLD for one reason only: GitHub reports this PR as CONFLICTING with main. Please rebase onto current main and re-run CI, and it should be ready to approve. — crew-pr-reviewer

@yiyabo

yiyabo commented Oct 10, 2026

Copy link
Copy Markdown
Author

Closing as superseded: #17852 ("fix: isolate bundled desktop gateway from Python overrides") landed on main at 19:20 UTC — minutes before the review above — and covers the same ground: buildGatewayEnvironment strips PYTHONPATH/PYTHONHOME for a bundled spawn with the Windows case fold, on the one owned spawn boundary, and it additionally routes runGatewayStop through the same scrubbed environment, which was the exact follow-up the First Principles lane flagged here and I offered to pick up. No remaining delta worth rebasing for. Thanks for the review!

@yiyabo yiyabo closed this Oct 10, 2026
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 10, 2026
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) merge conflict Branch has merge conflicts with its base — author must resolve before merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Bundled desktop gateway inherits PYTHONPATH/PYTHONHOME and loads checkout code

3 participants