Investigate tmux focus-events and its implications for the in-browser terminal #187

Open
opened 2026-09-21 18:00:42 +02:00 by lz · 0 comments
Owner

Context

The in-browser session terminal (AGENTS.md fact #14) bridges xterm.js in the
operator's browser to a docker exec PTY attached to a grouped tmux session
(-t nexus, group member with its own active-window pointer). Neither
worker/entrypoint.sh nor the tmux invocation in terminal/upgrade.ts has
been reviewed for what focus-events (set-option -g focus-events on|off,
tmux default: off) is set to, or what changing it would mean for this
pipeline. This issue tracks investigating that, not a known bug report.

What focus-events does

When on, tmux both (a) tracks whether its own client has terminal focus, and
(b) forwards the outer terminal's focus in/out escape sequences (\x1b[I /
\x1b[O) through to whatever program is running in the active pane. Off
(the default), those sequences are not forwarded, so any pane program that
wants focus changes — an editor with a focus-lost autosave, some REPLs, and
potentially claude-code's own TUI — never learns about them.

Why this might matter here

  • xterm.js can itself track browser tab/element focus and emit the same
    escape sequences into the PTY. Whether that ever reaches the pane
    application depends on tmux's focus-events setting somewhere on the path
    in between.
  • If xterm.js sends focus sequences that tmux isn't configured to forward (or
    the reverse — something downstream expects them and never gets them), the
    likely failure shape is the same class of bug as the xterm/IME composition
    issue already found in this codebase's terminal stack: stray escape bytes
    rendered as literal text, or a session silently never learning it
    gained/lost focus.
  • claude-code's hook surface includes attention-adjacent Notification types
    (idle_prompt, agent_needs_input, etc. — AGENTS.md fact #26). If any of
    claude-code's own behavior is sensitive to terminal focus state, and that
    state never correctly reaches it through this bridge, that's worth knowing
    either way — whether or not it's currently causing a visible symptom.

What to investigate

  1. What the current tmux config (baked by worker/entrypoint.sh, or
    whatever sets up the nexus session) sets focus-events to today — most
    likely unset, i.e. tmux's default off — and whether xterm.js's terminal
    instance on the frontend has focus reporting enabled.
  2. Whether turning focus-events on server-side changes anything observable
    in a real session (rendering artifacts, claude-code behavior change, or
    nothing at all).
  3. Whether there's a concrete, reproducible bug today (stray escape
    sequences visible in the terminal on a focus change) or this is a latent
    gap with no current symptom.

No fix is proposed here — this is scoped as an investigation.

## Context The in-browser session terminal (AGENTS.md fact #14) bridges xterm.js in the operator's browser to a `docker exec` PTY attached to a grouped tmux session (`-t nexus`, group member with its own active-window pointer). Neither `worker/entrypoint.sh` nor the tmux invocation in `terminal/upgrade.ts` has been reviewed for what `focus-events` (`set-option -g focus-events on|off`, tmux default: **off**) is set to, or what changing it would mean for this pipeline. This issue tracks investigating that, not a known bug report. ## What focus-events does When on, tmux both (a) tracks whether its own client has terminal focus, and (b) forwards the outer terminal's focus in/out escape sequences (`\x1b[I` / `\x1b[O`) through to whatever program is running in the active pane. Off (the default), those sequences are not forwarded, so any pane program that wants focus changes — an editor with a focus-lost autosave, some REPLs, and potentially claude-code's own TUI — never learns about them. ## Why this might matter here - xterm.js can itself track browser tab/element focus and emit the same escape sequences into the PTY. Whether that ever reaches the pane application depends on tmux's `focus-events` setting somewhere on the path in between. - If xterm.js sends focus sequences that tmux isn't configured to forward (or the reverse — something downstream expects them and never gets them), the likely failure shape is the same class of bug as the xterm/IME composition issue already found in this codebase's terminal stack: stray escape bytes rendered as literal text, or a session silently never learning it gained/lost focus. - claude-code's hook surface includes attention-adjacent Notification types (`idle_prompt`, `agent_needs_input`, etc. — AGENTS.md fact #26). If any of claude-code's own behavior is sensitive to terminal focus state, and that state never correctly reaches it through this bridge, that's worth knowing either way — whether or not it's currently causing a visible symptom. ## What to investigate 1. What the current tmux config (baked by `worker/entrypoint.sh`, or whatever sets up the `nexus` session) sets `focus-events` to today — most likely unset, i.e. tmux's default off — and whether xterm.js's terminal instance on the frontend has focus reporting enabled. 2. Whether turning `focus-events on` server-side changes anything observable in a real session (rendering artifacts, claude-code behavior change, or nothing at all). 3. Whether there's a concrete, reproducible bug today (stray escape sequences visible in the terminal on a focus change) or this is a latent gap with no current symptom. No fix is proposed here — this is scoped as an investigation.
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
lz/agent-nexus#187
No description provided.