fix(core): wrap kitty graphics query in tmux DCS passthrough

[edlsh]

Fixes #334

Summary

• Re-enable kitty graphics query (was disabled due to tmux pane title corruption)
• Wrap query in tmux DCS passthrough when TMUX env var is present
• Skip query entirely for TERM=screen*/tmux* without TMUX (could be GNU Screen)
• Add OPENTUI_NO_GRAPHICS env var to disable query manually

Technical Details

The kitty graphics protocol uses APC sequences (\x1b_G...) which tmux intercepts and leaks into pane titles. The fix wraps the query in tmux's DCS passthrough format (\x1bPtmux;...\x1b\\) with ESC chars doubled per the protocol spec.

References:

• Kitty Graphics Protocol - Querying Support
• tmux DCS Passthrough

Testing

# Native tests
cd packages/core/src/zig && zig build test --summary all
# 1241/1242 tests passed

Manual verification in tmux - pane title no longer shows Gi=31337...

[edlsh]

I can also update so:

1. TMUX env → use passthrough.
2. TERM=tmux* (without TMUX) → also use passthrough (likely still tmux)
3. TERM=screen* (without TMUX) → skip (could be GNU Screen)

This way we try passthrough for anything tmux-like, only skip for ambiguous screen* cases.

[kommander]

I tried playing with passthrough as well, the issue is opentui applications running remote, where the env will say "no tmux" and only delayed when maybe receiving an xtversion response will it know about tmux, but at that point will already have sent without DCS and mess up the window title.

[edlsh]

Could we restructure the query sequence so queryTerminalSend emits the graphics query only after parsing xtversion reveals the terminal type?

[kommander]

Yeah, that would work. Sorry for the late answer. The xtversion query should be sent as very first query. Some caveat: the xtversion query may never get a response, as for example xterm.js (VSCode) does not send any. Maybe there are better ways to detect it remotely. So the tricky part would be to figure out a timeout that makes sense.

[edlsh]

hey @kommander — tweaked the deferred flow so tmux still gets the DCS-wrapped kitty query even if xtversion never responds (TMUX env). also added send/flush error logs. let me know if you want a timeout-based fallback for non-tmux terminals.

[kommander]

Could work better, yeah. I think it's fine if it only works for local tmux to start with, as long as it doesn't send the escaped query for non-tmux.

A little nitpick: We have capabilities.terminal.name, could we just use that and set it when detected via env for tmux for example, instead of having an additional in_tmux flag? Then it can just always check capabilities.terminal.name compared to checking both. Then it also wouldn't matter if the name is from xtversion or not. If it is coming from env we can be pretty sure and from xtversion it then just came later.

One other thing, /scripts is meant for things executed regularly, manually or automated. I would put the test-tmux-graphics-334.sh in core/dev if you want to keep that.

[edlsh]

Hey, quick note on the tmux detection nit: if we drop and rely only on , xtversion from the inner terminal (e.g. kitty) can overwrite it and we’ll stop wrapping the kitty graphics query, which can reintroduce the pane-title corruption in tmux. The current code keeps from TMUX/TERM and uses that in sendPendingGraphicsQuery, so it stays safe even if xtversion later reports kitty. If we want to avoid the extra flag, we’d need to persist the tmux env in the name and avoid later overwrite, or keep a separate tmux-env flag.