Is this a reproducible bug?
Current behavior
With Herdr running inside iTerm2, changing focus produces a deterministic visible-input stall:
- Switching from another macOS application back to iTerm delays keyboard echo for approximately 0.5–1.5 seconds.
- Switching between two iTerm windows running Herdr produces the same delay.
- Switching between Herdr workspaces causes a roughly 0.5–1.0 second visible update delay.
- Immediately after focus returns, native text-selection highlighting can stall for the same interval.
- After the initial interval, keyboard input and rendering are responsive again.
The problem occurs in both a Pi pane and a plain shell pane. It also reproduces in an isolated vanilla Herdr session with one workspace and no plugins or Pi process.
On one occasion, terminal palette-response bytes were injected into a pasted prompt. The intended text contained:
"startup-canary producer"
but the pane received:
startup-ca]4;209;rgb:ffff/8787/5f5f\]4;210;rgb:ffff/8787/8787\]4;211;rgb:ffff/8787/afaf\nary producer
These are damaged OSC 4 palette replies for indexes 209–211, with the ESC introducer/terminators no longer intact. They were inserted in the middle of otherwise correct pasted text, suggesting that asynchronous host-terminal reply bytes leaked into the pane input stream rather than being part of the clipboard.
Disabling the following iTerm advanced preference makes the focus latency substantially better:
Terminal: Apps may turn on Focus Reporting = No
Expected behavior
- Refocusing an iTerm window or Herdr session should not delay keyboard echo, native selection painting, or workspace presentation.
- Host-terminal OSC 4/10/11 query replies must always be consumed by the Herdr client and must never reach a pane as user input, including when focus changes and bracketed paste overlap.
Reproduction
- Herdr client/server: 0.9.0 stable, protocol 22
- iTerm2: reproduced on 3.7.0 and 3.7.1
- macOS: 26.6.2 (build 25G83), Apple Silicon
- TERM:
xterm-256color
- TERM_PROGRAM:
iTerm.app
- Local Herdr server; no tmux
Reproduction: isolated vanilla Herdr
- Start a separate named Herdr session from a plain iTerm tab using isolated XDG config and state directories.
- Use a minimal config that only skips onboarding.
- Leave the session with one workspace and one plain shell; do not start Pi or another agent.
- Switch to another application, return to iTerm, and immediately type.
- Observe that visible echo stalls for approximately 0.5–1.5 seconds.
The isolated instance used a separate server, socket, and runtime state. It did not load the normal Herdr configuration or plugins.
Terminal-mode isolation
A local diagnostic isolated the terminal modes involved without using Herdr. The lag occurred when all of these were active together:
- raw input mode;
- alternate screen (
CSI ? 1049 h);
- focus reporting (
CSI ? 1004 h);
- hidden hardware cursor (
CSI ? 25 l).
The latency disappeared when focus reporting was omitted, when alternate-screen mode was omitted, or when the hardware cursor remained visible. Adding or omitting DEC synchronized-output framing did not uniquely trigger the problem. Mouse reporting was not enabled during this isolation test.
No diagnostic source code is attached.
Additional diagnostics
- A plain shell directly in iTerm does not lag.
- The same Herdr server viewed through Apple Terminal.app does not lag.
- Reducing the iTerm window from approximately 429x100 cells to about one-third of fullscreen does not change the delay.
- Disabling GPU/Metal rendering, fully restarting iTerm, and creating a new session does not change it.
- Increasing iTerm's idle-session threshold from 2 to 3600 seconds does not change it.
ui.redraw_on_focus_gained = false does not change it.ui.mouse_capture = false does not change it; native iTerm selection highlighting still stalls after focus gain.- Herdr workspace-focus API calls complete in approximately 34–42 ms, while the visible transition is delayed much longer.
- During a captured reproduction, iTerm reached approximately 57% CPU and the Herdr client/server also spiked, while Pi remained around 0–0.2% CPU.
- With iTerm's FPS overlay enabled, rapid typing immediately after focus gain stays around 2 FPS for 0.5–1.5 seconds and then rises toward 50 FPS.
Related issues
The earlier OSC reply fixes are present in 0.9.0, so the observed paste corruption may be an uncovered focus/paste interleaving or fragmented-response variant.
Current workaround
Disable iTerm focus reporting globally:
iTerm2 Settings → General → Advanced → Apps may turn on Focus Reporting → No
This improves the latency and likely prevents the focus-triggered palette refresh path, but it also disables legitimate focus events for all terminal applications.
Impact
The latency affects every application/window focus change and makes the first interaction after returning to Herdr feel unresponsive. More importantly, leaked terminal protocol replies can corrupt commands or prompts and may be interpreted as user input by interactive applications.
Environment
- Herdr client/server: 0.9.0 stable, protocol 22
- iTerm2: reproduced on 3.7.0 and 3.7.1
- macOS: 26.6.2 (build 25G83), Apple Silicon
- TERM:
xterm-256color
- TERM_PROGRAM:
iTerm.app
- Local Herdr server; no tmux
Is this a reproducible bug?
Current behavior
With Herdr running inside iTerm2, changing focus produces a deterministic visible-input stall:
The problem occurs in both a Pi pane and a plain shell pane. It also reproduces in an isolated vanilla Herdr session with one workspace and no plugins or Pi process.
On one occasion, terminal palette-response bytes were injected into a pasted prompt. The intended text contained:
but the pane received:
These are damaged OSC 4 palette replies for indexes 209–211, with the ESC introducer/terminators no longer intact. They were inserted in the middle of otherwise correct pasted text, suggesting that asynchronous host-terminal reply bytes leaked into the pane input stream rather than being part of the clipboard.
Disabling the following iTerm advanced preference makes the focus latency substantially better:
Expected behavior
Reproduction
xterm-256coloriTerm.appReproduction: isolated vanilla Herdr
The isolated instance used a separate server, socket, and runtime state. It did not load the normal Herdr configuration or plugins.
Terminal-mode isolation
A local diagnostic isolated the terminal modes involved without using Herdr. The lag occurred when all of these were active together:
CSI ? 1049 h);CSI ? 1004 h);CSI ? 25 l).The latency disappeared when focus reporting was omitted, when alternate-screen mode was omitted, or when the hardware cursor remained visible. Adding or omitting DEC synchronized-output framing did not uniquely trigger the problem. Mouse reporting was not enabled during this isolation test.
No diagnostic source code is attached.
Additional diagnostics
ui.redraw_on_focus_gained = falsedoes not change it.ui.mouse_capture = falsedoes not change it; native iTerm selection highlighting still stalls after focus gain.Related issues
The earlier OSC reply fixes are present in 0.9.0, so the observed paste corruption may be an uncovered focus/paste interleaving or fragmented-response variant.
Current workaround
Disable iTerm focus reporting globally:
This improves the latency and likely prevents the focus-triggered palette refresh path, but it also disables legitimate focus events for all terminal applications.
Impact
The latency affects every application/window focus change and makes the first interaction after returning to Herdr feel unresponsive. More importantly, leaked terminal protocol replies can corrupt commands or prompts and may be interpreted as user input by interactive applications.
Environment
xterm-256coloriTerm.app