fix(#2947): preserve TERM_PROGRAM for claude-teams across Go + Swift surfaces
Summary
Fixes #2947 — cmux claude-teams crashes during teammate→team-lead permission escalation on Claude Code v2.1.112+. Root cause: cmux's agent-launch shims unconditionally unsetenv("TERM_PROGRAM") for every agent type, but Claude Code's new permission flow requires TERM_PROGRAM to be set or its cli.js crashes mid-prompt.
This PR fixes both surfaces — the Go remote daemon (cmuxd-remote) and the Swift local CLI — and adds the test coverage that was missing from the original report.
Why this supersedes #2960
PR #2960 (by @bobo-xxx) correctly identified the bug and patched the Go daemon. However, the original repro in #2947 is local-Mac (cmux claude-teams typed directly into a terminal pane), which goes through CLI/cmux.swift, not cmuxd-remote. So #2960 alone doesn't reach the reporter's crash path.
Rather than open a Swift-only companion PR (and leave maintainers to coordinate two reviews / two test plans), this PR includes:
- @bobo-xxx's Go commit cherry-picked unmodified (attribution preserved on commit
39527116) - The matching Swift fix
- Adversarial-review polish that was raised on #2960 (CodeRabbit + manual review)
- Comprehensive test coverage on both surfaces
Happy to defer to whatever the maintainers prefer — see the comment I'll leave on #2960.
What's in this PR
Bug fix (verified end-to-end)
- Go (
daemon/remote/cmd/cmuxd-remote/agent_launch.go) — gatesos.Unsetenv("TERM_PROGRAM")on a per-agent flag. claude-teams preserves; opencode-family (omo/omx/omc) unsets. - Swift (
CLI/cmux.swift) — same asymmetry on the local CLI path. Without this, the original reporter's local-Mac crash still reproduces.
Adversarial-review improvements
-
preserveTermProgram(zero-value-safe naming) — CodeRabbit flagged the originalunsetTermProgramfield as having an unsafe zero value (false= preserve = the rare exception, not the historical default). Renamed across both surfaces; the zero value now matches the legacy "unset" behavior, so any new agent type defaults to the safe choice and only claude-teams opts in. -
infocmp xterm-ghosttyprobe — defaultingTERMtoxterm-ghosttyis the right call, but cmux's terminfo overlay installs asynchronously during shell bootstrap on remote SSH hosts (seetests_v2/test_ssh_remote_shell_integration.py:536-615which documents that fresh containers don't have the entry preinstalled). If an agent process exec's before that install completes, it inheritsTERM=xterm-ghosttywithout the matching terminfo entry → ncurses falls back to a dumb terminal. Both surfaces now probeinfocmp xterm-ghosttyand fall back toxterm-256color(universally supported). -
COLORTERMread alignment — the Swift implementation read from aprocessEnvironmentsnapshot taken before any env mutations; Go readsos.Getenv(live). Functionally equivalent today but fragile to re-orderings. Both surfaces now read live for parity. -
Comment accuracy — opencode reacts to any non-empty
TERM_PROGRAM(treats it as an outer-host marker), not specifically=ghosttyas the original comment implied. Updated in both files.
Tests
| File | What it covers |
|---|---|
tests/test_cli_claude_teams_env.py | Asserts the new TERM=xterm-ghostty + preserved TERM_PROGRAM contract for claude-teams (was: asserted the old contract; would have broken on this PR). Updated, not new. |
tests/test_cli_omo_env.py | New. Sibling test for cmux omo asserting TERM_PROGRAM is unset (regression guard for #2516 — opencode's light-theme switch on any non-empty TERM_PROGRAM), TERM=xterm-ghostty, and COLORTERM=truecolor fallback. |
daemon/remote/cmd/cmuxd-remote/agent_launch_test.go | New. 7 Go unit tests covering the full configureAgentEnvironment matrix (preserve / unset / TERM override / COLORTERM preservation / extraEnv) plus 2 tests for resolveDefaultTerm (terminfo race success + fallback). |
daemon/remote/cmd/cmuxd-remote/tmux_compat_test.go | Added a TERM_PROGRAM unset assertion to the existing TestConfigureAgentEnvironment (the test set TERM_PROGRAM=should-be-removed but never asserted the result). |
Per CLAUDE.md's regression-test policy, the original test/fix pair (commits 8369e3c2 → 3b2b37b2) is a two-commit failing-test-then-fix sequence so CI on the test commit alone goes red — proving the test catches the bug.
Test plan
# Go matrix (8 tests, all green)
cd daemon/remote && go test ./cmd/cmuxd-remote/
# Python: claude-teams contract (phase 1 covers our changes; phase 2 has a
# pre-existing Node-24 incompatibility flagged below)
python3 tests/test_cli_claude_teams_env.py
# Python: OMO regression (#2516 guard)
python3 tests/test_cli_omo_env.py
# Manual GUI repro of #2947
./scripts/reload.sh --tag fix-2960-supersede --launch
# In the launched DEV app: cmux claude-teams → teamCreate → teammate triggers
# permission escalation. Should NOT crash (was: cli.js stack trace ending in
# `ov (/$bunfs/root/src/entrypoints/cli.js:477:76101)`).
# Manual GUI sanity for opencode-family theme:
# cmux omo → confirm dark theme intact (regression #2516 guard)
I've verified the GUI repro locally on macOS 26.4.1 / Apple Silicon. The original crash is gone; opencode's dark theme is intact.
Out of scope (flagged for follow-up)
- Phase 2 of
tests/test_cli_claude_teams_env.py(the--max-old-space-size 2048 --trace-warningsheap-flag scenario) fails on Node 24 because Node 24 rejects the space-separated form (--max-old-space-size 2048) and now requires--max-old-space-size=2048. Pre-existing; unrelated to this PR. CI's macOS VM probably runs an older Node where it still passes.
Related
🤖 Generated with Claude Code
Summary by cubic
Preserves TERM_PROGRAM for claude-teams across the Go daemon and Swift CLI to fix the permission-escalation crash in Claude Code v2.1.112+ (Fixes #2947). Also hardens terminal env defaults and adds coverage to prevent regressions.
-
Bug Fixes
- Go daemon: add per‑agent
preserveTermProgram;claude-teamspreserves, opencode‑family (omo/omx/omc) unsets. - Swift CLI: mirror the preserve/unset behavior on the local path used by
cmux claude-teams. - Default TERM via probe: use
xterm-ghosttywheninfocmp xterm-ghosttysucceeds, else fall back toxterm-256color. - Set
COLORTERM=truecolorwhen absent to ensure truecolor rendering. - Tests: new Go unit tests for env matrix and terminfo probe; new
tests/test_cli_omo_env.py; updatedtests/test_cli_claude_teams_env.py.
- Go daemon: add per‑agent
-
Refactors
- Rename flag to
preserveTermProgram(safe default: unset); readCOLORTERMfrom live env; clarify comments about opencode reacting to any non‑empty TERM_PROGRAM.
- Rename flag to
Summary by CodeRabbit
-
Bug Fixes
- Improved terminal detection to dynamically resolve terminal type at runtime instead of using fixed defaults
- Fixed terminal program preservation for Claude Teams
- Enhanced color terminal support by automatically detecting and setting truecolor when appropriate
-
Tests
- Added tests for terminal environment configuration
- Added tests for OpenCode family integration with terminal settings