fix: backport desktop Gateway UTF-8 restarts to 0.4.0

[bolichen97]

Problem / Motivation

Backport the merged UTF-8 Gateway restart hardening from #5919 to the 0.4.0 Insider release line.

A hostile or incorrectly inherited Python stream encoding can make an Electron-managed Gateway crash when it emits Unicode during an in-app restart. This affects restart paths shared by Tailnet, MCP, updates, and liveness recovery.

What changed

• Force PYTHONUTF8=1 and PYTHONIOENCODING=utf-8:backslashreplace at the Electron Gateway spawn boundary on Windows, macOS, and Linux.
• Preserve those settings across Python module re-exec.
• Keep Windows stream reconfiguration while publishing the safe environment on every platform.
• Add hostile-environment tests for Electron spawn construction and Python re-exec.
• Document the Gateway encoding contract.

This is a minimal cherry-pick of merge commit 7828513. The only conflict was resolved by excluding unrelated main-only count_open_fds code so release-specific behavior remains unchanged.

Testing

• pytest test/test_platform_compat.py -q (226 passed, 38 skipped)
• Focused re-exec/UTF-8 tests (8 passed, 5 platform-inapplicable skipped)
• Real Windows native re-exec probe from a hostile cp1252 parent
• npm test --prefix website/electron (1327 passed, 2 skipped)
• node --test website/electron/test/gateway-env.test.js website/electron/test/shell-contract.test.js (10 passed)
• isort --check-only and flake8 on changed Python files
• scripts/check_subprocess_encoding.py --test and the actual gate
• scripts/check_black_formatting.py
• scripts/docs_lint.py --test and the actual docs lint

Related

Backport of #5919.

Checklist

• Backport contains only the intended fix
• Release-specific behavior is preserved
• Relevant Python and Electron tests pass
• No UI changes

[github-actions]

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 4070e32c105c9bfb8e79b273ed0f0eefd4d4379e and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 4070e32

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

[github-actions]

Design Review (Fable 5) — 🟡 CONCERNS

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

Design-Verdict: CONCERNS

The identical commit already sits on release/0.4.0 — this PR's diff against its base is empty, so merging it ships nothing.

Watch

• Duplicate backport. PR head 4070e32c1 and the base-branch tip 2d89a2e56 have the same tree (1907818a7) and same parent (74b98eb72): the backport was already committed directly to release/0.4.0. git diff 2d89a2e56...HEAD is empty, so every claim in the description ("Force PYTHONUTF8=1…", tests, docs) is already on the base and this merge adds only a content-free merge commit. Close the PR, or rebase and confirm nothing further was intended — and reconcile why the release branch took a direct push alongside an open backport PR.

On the substance (judged from 74b98eb72..HEAD, the change as authored): sound. It fixes the root cause — CPython binds redirected-stream encodings before any Kiro Crew code runs, so pinning PYTHONUTF8/PYTHONIOENCODING at the Electron spawn boundary and republishing before os.execv is the only layer that can work; gateway-env.js and platform_compat.py are the right owners, and the cherry-pick is minimal with the main-only count_open_fds conflict correctly excluded.

[DESIGN-REVIEWED] 4070e32

[github-actions]

Opus 4.8 Review — ✅ no blocking findings

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

Review details

The discovery pass produced no candidates, and my independent verification confirms the analysis. I checked the one genuine risk — the global os.environ mutation of PYTHONIOENCODING corrupting byte-exact stdio round-trips. The round-trip sites documented in subprocess_utf8.py pin errors="surrogateescape" on the parent decode/encode side and spawn git (not Python), so the inherited PYTHONIOENCODING never reaches them. backslashreplace never substitutes for UTF-8-encodable content, and it is a valid decode/encode handler on Python ≥3.10. No grounded (a)/(b)/(c) chain exists in the changed lines.

No findings.

[OPUS-REVIEWED] 4070e32

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

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