fix(#2947): preserve TERM_PROGRAM for claude-teams across Go + Swift surfaces

Closed
LU
7mo ago
+478-28

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) — gates os.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

  1. preserveTermProgram (zero-value-safe naming) — CodeRabbit flagged the original unsetTermProgram field 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.

  2. infocmp xterm-ghostty probe — defaulting TERM to xterm-ghostty is the right call, but cmux's terminfo overlay installs asynchronously during shell bootstrap on remote SSH hosts (see tests_v2/test_ssh_remote_shell_integration.py:536-615 which documents that fresh containers don't have the entry preinstalled). If an agent process exec's before that install completes, it inherits TERM=xterm-ghostty without the matching terminfo entry → ncurses falls back to a dumb terminal. Both surfaces now probe infocmp xterm-ghostty and fall back to xterm-256color (universally supported).

  3. COLORTERM read alignment — the Swift implementation read from a processEnvironment snapshot taken before any env mutations; Go reads os.Getenv (live). Functionally equivalent today but fragile to re-orderings. Both surfaces now read live for parity.

  4. Comment accuracy — opencode reacts to any non-empty TERM_PROGRAM (treats it as an outer-host marker), not specifically =ghostty as the original comment implied. Updated in both files.

Tests

FileWhat it covers
tests/test_cli_claude_teams_env.pyAsserts 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.pyNew. 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.goNew. 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.goAdded 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-warnings heap-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

  • Issue: #2947
  • Original PR (now superseded): #2960
  • Regression guard for: #2516

🤖 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-teams preserves, 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-ghostty when infocmp xterm-ghostty succeeds, else fall back to xterm-256color.
    • Set COLORTERM=truecolor when absent to ensure truecolor rendering.
    • Tests: new Go unit tests for env matrix and terminfo probe; new tests/test_cli_omo_env.py; updated tests/test_cli_claude_teams_env.py.
  • Refactors

    • Rename flag to preserveTermProgram (safe default: unset); read COLORTERM from live env; clarify comments about opencode reacting to any non‑empty TERM_PROGRAM.

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