Skip to content

fix(packaging): drop PYTHONPATH/PYTHONHOME in the bundled kirocrew launchers - #19690

Merged
iamwhatever merged 1 commit into
mainfrom
fix/18378-launcher-scrub-python-env
Oct 13, 2026
Merged

iamwhatever merged 1 commit into
mainfrom
fix/18378-launcher-scrub-python-env

Conversation

@CrysisDeu

@CrysisDeu CrysisDeu commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Running the packaged kirocrew CLI from a shell that exports PYTHONPATH or PYTHONHOME always runs the shipped backend, never a checkout mixed into it.

PR #17852 made the desktop shell drop PYTHONPATH/PYTHONHOME for the gateway it spawns. The bundled launchers users run directly were left alone: the POSIX bin/kirocrew script (reached through the ~/.local/bin/kirocrew symlink and named by the AppImage token page) and the Windows bin\kirocrew.cmd shim both forwarded the whole inherited environment to the bundled interpreter. A kirocrew token or kirocrew stop typed in a development shell with PYTHONPATH=<checkout>/src therefore 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 stop against the wrong code can leave a gateway running.

Not a goal

  • Changing how the desktop shell builds the gateway environment (gateway-env.js); its scrub stays as the second guard.
  • Dropping any other PYTHON* variable (PYTHONUTF8, PYTHONIOENCODING, bytecode knobs); the shell relies on handing those down.
  • Source-tree or venv installs, whose console script is not generated by packaging/build-desktop.sh and which keep PYTHONPATH for development by design.

Intended? / Repro

Intended? No. The launcher's only env-related comment on main explains -s/-P (user site and cwd off sys.path); nothing mentions keeping PYTHONPATH. git log -S'-s -P -m kiro_crew' -- packaging/build-desktop.sh finds one commit, #13307, which added -P for 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 honour PYTHONPATH.

Repro on origin/main @ de2d143, no test suite: extract the launcher heredoc from packaging/build-desktop.sh into a temp fake bundle beside a stub python3.12 that prints its environment, plant a ~/.local/bin/kirocrew-style symlink, run with PYTHONPATH=/home/dev/checkout/src PYTHONHOME=/home/dev/other-python PYTHONUTF8=1.

Observed (both the direct launcher and the symlink shim):

PYTHONPATH=/home/dev/checkout/src
PYTHONHOME=/home/dev/other-python
PYTHONUTF8=1
ARGS=-s -P -m kiro_crew token

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 off and the python.exe invocation, with no set in between.

What changed (motivation → approach → change)

Symptom: the bundled interpreter inherited PYTHONPATH/PYTHONHOME when 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/bin symlink, AppImage token page), and it did nothing to its environment.

Approach: scrub at the shared entry point. The POSIX launcher runs unset PYTHONPATH PYTHONHOME before exec; the Windows kirocrew.cmd runs set "PYTHONPATH=" and set "PYTHONHOME=" under setlocal, so cmd's case-insensitive environment loses mixed-case spellings too and an interactive cmd window keeps its own variables after the command returns. -E was rejected because it also discards PYTHONUTF8, PYTHONIOENCODING and 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 of kirocrew.cmd in 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.js only gains a comment: the Windows unwrap bypasses the .cmd, so for that spawn the shell's buildGatewayEnvironment({ bundled: true }) remains the scrub. docs/build/desktop-app.md gains 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/PYTHONHOME stop reaching the bundled interpreter, and docs/build/desktop-app.md already 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_shim runs 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_down pins that PYTHONUTF8 and PYTHONDONTWRITEBYTECODE still reach the interpreter (guards against a future -E).
  • ::test_launcher_keeps_the_python_env_scrub names the unset line and forbids -E on the exec line.
  • New test/test_build_desktop_windows_launcher.py renders the kirocrew.cmd printf format (%%, \\, \r\n) and asserts the two set deletions precede the python.exe line, setlocal precedes the first set, and the interpreter line is still exactly "%~dp0..\python.exe" -s -P -m kiro_crew %*. Red on main (two-line shim, no set).
  • ::test_build_workflow_writes_the_same_cmd_launcher parses the Set-Content -Value @(...) array in .github/workflows/build.yml and asserts it equals the rendered printf lines. 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=1 kept). The printf format was rendered with bash and inspected with cat -A to confirm CRLF line endings and the quoted set lines. bash -n packaging/build-desktop.sh and node --check website/electron/gateway-recovery.js pass. A real cmd.exe run of the new shim happens in this PR's Build Windows Installer (x64) job, which builds the installer from the build.yml copy and boots the bundled backend through it; a PYTHONPATH-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

  • 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

@CrysisDeu
CrysisDeu requested review from a team and KiroCrewCaptain as code owners October 13, 2026 05:32
@CrysisDeu
CrysisDeu requested a review from mbriones98 October 13, 2026 05:32
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 13, 2026
@github-actions

github-actions Bot commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

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

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 .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 13, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of d6d5778690574468c3b4486fa0e85c5b6646c5cc — 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, confirm that this head's Build Windows Installer (x64) job is green. That job is the only real cmd.exe run of the new five-line shim.

What this change ships

Inventory (6 items) — 6 justified

Intent: when someone runs the packaged kirocrew CLI from a dev shell that exports PYTHONPATH/PYTHONHOME, it always runs the shipped backend and never imports checkout code. This is a FIX (#18378, with a repro and tests that fail on base).

  1. The POSIX bin/kirocrew launcher, run directly or through the ~/.local/bin symlink, no longer passes PYTHONPATH/PYTHONHOME to the bundled interpreter — justified
  2. The Windows bin\kirocrew.cmd from build-desktop.sh clears the same two variables under setlocal, so the caller's cmd window keeps its own — justified
  3. The installer workflow's own copy of kirocrew.cmd (the shim the installer smoke boots) ships the same lines — justified
  4. A test now fails if the build.yml copy and the build-desktop.sh copy of the shim drift apart — justified
  5. desktop-app.md documents the scrub at the launcher level — justified
  6. A comment in gateway-recovery.js says the unwrapped Windows spawn still relies on gateway-env.js for the scrub — justified

[FIRST-PRINCIPLES-REVIEWED] d6d5778

Description read

[DESCRIPTION-READ] 93efb76114fe832dd57e088ce0467fe6c4e7b6a8211e39f58d1c03d7a3a9add6

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 13, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Check that this PR's Build Windows Installer (x64) job boots the gateway through the new five-line kirocrew.cmd and passes; no one has run the shim by hand under real cmd.exe.

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

github-actions Bot commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] d6d5778

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

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

@github-actions

github-actions Bot commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] d6d5778

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

@CrysisDeu
CrysisDeu force-pushed the fix/18378-launcher-scrub-python-env branch from a9734d8 to 9797492 Compare October 13, 2026 05:38
@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 13, 2026
@CrysisDeu
CrysisDeu force-pushed the fix/18378-launcher-scrub-python-env branch 2 times, most recently from da37e2b to 9d474b2 Compare October 13, 2026 06:32
@CrysisDeu
CrysisDeu force-pushed the fix/18378-launcher-scrub-python-env branch from 9d474b2 to d6d5778 Compare October 13, 2026 07:16
@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 13, 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.

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 PYTHONHOME runs right before the exec. build_backend writes this heredoc for both Linux and macOS (called at :886-887 and :926), so both platforms get it. No other launcher writer exists in packaging/.
  • Windows: packaging/build-desktop.sh:763 and .github/workflows/build.yml:218 write the same five lines (setlocal, then two set "X=", then the unchanged python.exe -s -P line). setlocal keeps the deletion out of the caller's interactive cmd, and the implicit endlocal keeps the exit code.
  • The Windows gateway spawn skips the .cmd (gateway-recovery.js:567). On that path the scrub is still the existing bundled branch in gateway-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 PYTHONPATH injection I found (apps/bridges.py:581,2348, apps/backend.py:1104, the auto-improvement profile :437) launches sys.executable or an app interpreter directly, never the bundled bin/kirocrew. So no intentional PYTHONPATH gets dropped. PYTHONUTF8 and the bytecode settings still pass through because -E was not used, and test_keeps_the_other_python_knobs_the_shell_hands_down pins that.
  • Docs: docs/build/desktop-app.md is updated. The launcher prose in docs/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 three Build Desktop jobs.

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… and test_launcher_keeps_the_python_env_scrub fail
  • removing the cmd set "PYTHONPATH=" → test_cmd_launcher_clears_pythonpath_and_pythonhome_before_python_runs and the workflow parity test fail
  • removing the cmd setlocal → test_cmd_launcher_scopes_the_deletion_with_setlocal and the parity test fail
  • removing the workflow's PYTHONHOME line → test_build_workflow_writes_the_same_cmd_launcher fails

Blocking

None.

Non-blocking follow-ups

  • None needed. A real cmd.exe run with a poisoned PYTHONPATH would be the end-to-end proof, but the installer smoke only shows that the new shim still boots.

Not verified

  • No cmd.exe or macOS run on my side. Windows setlocal and exit-code behaviour were checked against source and documented cmd semantics only, plus the green Windows installer job.

@iamwhatever iamwhatever 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.

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)

@iamwhatever
iamwhatever merged commit 6dbe710 into main Oct 13, 2026
103 checks passed
@iamwhatever
iamwhatever deleted the fix/18378-launcher-scrub-python-env branch October 13, 2026 17:20
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 13, 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 bin/kirocrew launcher and ~/.local/bin shim still pass PYTHONPATH/PYTHONHOME through

3 participants