Gate desktop-notify focus tracking on raw interactive terminals

Co-authored-by: Claude Opus 4.7 <anthropic-claude-opus-4-7@pi.local>
Pi-Model: anthropic/claude-opus-4-7

Author: ian-ross

packages/desktop-notify/README.md

@@ -76,7 +76,11 @@ Send a desktop notification.
 
 ### `startFocusTracking()`
 
-Start tracking terminal focus via DECSET 1004. Idempotent — safe to call multiple times. Listens on `process.stdin` for focus in/out escape sequences.
+Start tracking terminal focus via DECSET 1004. Idempotent — safe to call multiple times. No-ops unless stdin/stdout are TTYs and stdin is already in raw mode, to avoid echoed focus escape sequences in non-interactive runs. Listens on `process.stdin` for focus in/out escape sequences.
+
+### `canTrackTerminalFocus()`
+
+Returns `true` when focus tracking can be enabled safely for the current process.
 
 ### `stopFocusTracking()`
 
@@ -96,7 +100,7 @@ Focus the previously captured terminal window. Called automatically on notificat
 
 ## How it works
 
-**Focus tracking** uses the DECSET 1004 terminal escape sequence. When enabled, the terminal sends `\x1b[I` (focus gained) and `\x1b[O` (focus lost). These are intercepted on `process.stdin` before other handlers see them. Works with kitty, wezterm, foot, alacritty, iTerm2, Zed, and most modern terminals. Also works through tmux and abduco.
+**Focus tracking** uses the DECSET 1004 terminal escape sequence. When enabled, the terminal sends `\x1b[I` (focus gained) and `\x1b[O` (focus lost). Tracking is enabled only in raw interactive terminals; in non-raw/non-interactive mode those sequences would be echoed by the terminal and corrupt output. Works with kitty, wezterm, foot, alacritty, iTerm2, Zed, and most modern terminals. Also works through tmux and abduco.
 
 **Click-to-focus** captures the terminal's window ID at initialization, then uses compositor-specific commands to focus it when a notification is clicked:
 

packages/desktop-notify/src/extension.ts

@@ -9,12 +9,14 @@
  */
 
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import { startFocusTracking, stopFocusTracking } from "./focus.js";
+import { canTrackTerminalFocus, startFocusTracking, stopFocusTracking } from "./focus.js";
 import { sendNotification } from "./notify.js";
 import { captureWindowId } from "./window.js";
 
 export default function (pi: ExtensionAPI) {
 	pi.on("session_start", async (_event, _ctx) => {
+		if (!canTrackTerminalFocus()) return;
+
 		startFocusTracking();
 		await captureWindowId();
 	});

packages/desktop-notify/src/focus.ts

@@ -18,11 +18,25 @@ const FOCUS_OUT = "\x1b[O";
 const ENABLE = "\x1b[?1004h";
 const DISABLE = "\x1b[?1004l";
 
+/**
+ * Returns true when DECSET 1004 focus tracking can be enabled safely.
+ *
+ * Focus events are terminal input. In canonical/non-raw mode the terminal line
+ * discipline echoes those escape sequences, which corrupts non-interactive
+ * output. Only enable reporting when Pi's interactive TUI has placed stdin in
+ * raw mode and both stdio streams are attached to a terminal.
+ */
+export function canTrackTerminalFocus(): boolean {
+	return Boolean(process.stdin.isTTY && process.stdout.isTTY && process.stdin.isRaw);
+}
+
 /**
  * Start tracking terminal focus. Idempotent — safe to call multiple times.
+ * No-ops unless the process is attached to an interactive raw terminal.
  */
 export function startFocusTracking(): void {
 	if (stdinListener) return;
+	if (!canTrackTerminalFocus()) return;
 
 	process.stdout.write(ENABLE);
 

packages/desktop-notify/src/index.ts

@@ -1,3 +1,3 @@
 export { sendNotification, type NotifyOptions } from "./notify.js";
-export { startFocusTracking, stopFocusTracking, isTerminalFocused } from "./focus.js";
+export { canTrackTerminalFocus, startFocusTracking, stopFocusTracking, isTerminalFocused } from "./focus.js";
 export { captureWindowId, focusWindow } from "./window.js";