Environment

• agent-deck v0.26.2 and v0.26.3
• macOS Darwin 25.3.0 (Apple Silicon)
• iTerm2
• tmux with set -g mouse on
• zsh

Problem

Ctrl+Q does not detach from an attached session. The keypress is swallowed before agent-deck can process it. Ctrl+B d (native tmux detach) works fine as a workaround.

Diagnosis

1. cat -v in a fresh terminal does not print ^Q — confirms the key is intercepted at the TTY level (XON/XOFF flow control)
2. Running stty -ixon fixes cat -v (^Q appears), but Ctrl+Q still does not work inside agent-deck sessions
3. stty -ixon added to both .zshrc and .zshenv (which agent-deck sources via shell.init_script) — no effect inside sessions
4. No Ctrl+Q binding in iTerm2 (checked global and profile key bindings)
5. No Ctrl+Q binding in tmux (tmux list-keys shows no C-q)

Attempted fix (did not work)

Added explicit IXON/IXOFF clearing via unix.IoctlGetTermios/IoctlSetTermios on os.Stdin.Fd() right after term.MakeRaw() in internal/tmux/pty.go. Built locally and tested — Ctrl+Q still not intercepted.

This suggests the issue is not a simple IXON race. The PTY layer created by pty.Start() may be re-establishing flow control on the slave side, or Bubble Tea's terminal restore/raw cycle around tea.Exec is interfering in a way that persists past MakeRaw.

Related issues

• Ability to change keybindings as CTRL+Q (detach) doesn't work for Zellij terminal #235 — Same symptom (Ctrl+Q not working) in Zellij, closed with configurable hotkeys (PR feat(ui): add Pi support, configurable hotkeys, and preview notes #285), but detach is not configurable via [hotkeys] in config.toml
• Shift+Enter does not work #342 / Fix #342: enable extended-keys for Shift+Enter in tmux sessions #343 — Similar class of issue (tmux swallowing modified key sequences), fixed with extended-keys on
• Multi-line prompt does not work #359 — Multi-line prompt (Shift+Enter) still broken for some users despite Fix #342: enable extended-keys for Shift+Enter in tmux sessions #343 fix

Suggested fixes (any of these would resolve it)

1. Bind Ctrl+Q as a tmux key — bind-key -n C-q detach-client on agent-deck managed sessions, bypassing the PTY stdin interception entirely
2. Make detach key configurable — the [hotkeys] config from PR feat(ui): add Pi support, configurable hotkeys, and preview notes #285 does not include detach; adding it would let users remap to a key that passes through their terminal
3. Investigate the PTY stdin path — pty.go:Attach() reads os.Stdin and checks for ASCII 17, but the byte may never arrive despite MakeRaw clearing IXON

Workaround

Ctrl+B d (standard tmux detach) works reliably.