fix(terminal): let Claude use truecolor so its themed backgrounds render

[irisitymichaelgrundberg]

Summary

Claude draws the user's own messages as a block of background color. Inside a Codeman pane that block is invisible, and no Claude theme can change that. This exports COLORTERM=truecolor for Claude, which is what the other seven CLIs already do.

The problem

Two things combine. tmux hands each pane TERM=screen, which supports-color reads as 16 colors, and Claude's registry entry deleted COLORTERM on top of that. Claude then quantizes every RGB color its theme asks for down to the basic palette.

Measured with the chalk version Claude bundles, at 16 colors:

theme color	16-color output	result
rgb(55, 55, 55) (built-in dark)	ESC[40m	the terminal's own black
rgb(28, 48, 84) (a custom theme)	ESC[40m	the terminal's own black
rgb(240, 240, 240) (built-in light)	ESC[47m	white

Every dark background lands on ESC[40m, so the block is emitted and paints the terminal's background over itself. Claude's *-ansi themes work, because they name colors like ansi:blackBright and skip the conversion entirely.

Detected levels, same library:

TERM	COLORTERM	level
screen	unset	1 — 16 colors
screen	truecolor	3 — 24-bit

Why this reverses #3

#3 added unset COLORTERM in February, reporting that truecolor caused "gray/white backgrounds appearing where they shouldn't" in xterm.js, and citing xtermjs/xterm.js#484. Three things have changed or were already true:

• xterm.js closed #484 on 2019-04-07, seven years before fix: unset COLORTERM to fix xterm.js rendering issues #3 cited it.
• Codeman now depends on @xterm/xterm ^6.0.0, which renders 24-bit color.
• TmuxManager sets terminal-overrides ",*:Tc" on its own tmux server (src/tmux-manager.ts), so 24-bit color already reaches the browser for the CLIs that ask for it.

I want to flag one reading honestly, because I cannot prove it. Suppressing truecolor makes Claude's dark block collapse into the terminal background and disappear. If that is what the reporter saw go away, then the symptom was Claude's user-message block working as designed, not an xterm.js defect.

Changes

• src/config/cli-registry/stock.ts — Claude's entry exports COLORTERM=truecolor. CLAUDECODE stays unset.
• src/session-cli-builder.ts — buildClaudeEnv(), the direct-PTY fallback taken when mux creation fails, now reads the same registry entry as the tmux pane and its attach client. It previously deleted COLORTERM from a hand-maintained list of its own, which would have left the fallback contradicting the entry.
• docs/architecture-invariants.md — a Terminal colour env paragraph under Session launch modes, where a reader looking up Claude will find it. The sentence it replaces sat under a heading listing only the non-Claude CLIs.
• test/tmux-manager.test.ts — pins the new behaviour beside the existing OpenCode assertion.
• A changeset.

Claude does not unset NO_COLOR, unlike the other seven truecolor CLIs. The bug does not need it, and unsetting it would override a preference the user set deliberately. The inconsistency is intentional and the entry's comment says so.

An SSH-remote pane is not covered. buildRemoteLaunchCommand() carries no env exports at all, so a remote Claude session keeps the old rendering. That predates this change, and the invariants doc now states it rather than implying every pane is covered. Docker panes take COLORTERM=truecolor from the hardcoded envCreate/execEnv, which apply to every mode including the two the registry says must unset it — also pre-existing, also now documented.

Verification

• npm test — 6870 passed, 12 skipped, 0 failed.
• npm run typecheck, npm run lint, npm run format:check, npm run check:frontend-syntax all clean.
• The new test bites: reverting the registry entry fails it with expected [...] to include 'export COLORTERM=truecolor'.
• Called buildClaudeEnv() with NO_COLOR=1 and CLAUDECODE=1 in the parent env: returns COLORTERM=truecolor, no CLAUDECODE, and NO_COLOR preserved.
• Called the real buildEnvExports against a build: a Claude pane emits unset CLAUDECODE, export COLORTERM=truecolor. OpenCode still emits unset COLORTERM, unchanged.
• Ran it for a day on a live install, then opened a fresh session on the stock dark theme. The user-message block renders as the intended grey, and nothing shows gray or white where it should not.

🤖 Generated with Claude Code