Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

fix(window): ignore macOS occlusion hides; a focused window is never backgrounded

review01e45ab8ebb5
diff --git a/CLAUDE.md b/CLAUDE.md
index 6613514f0..d6a0aa9ab 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -648,7 +648,11 @@ Lifecycle, by intent:
all read hidden. Show cancels the dwell and revives warm. It feeds existing levers — it is not a
new one — and an occluded window or a Server Edition tab switch never triggers it (explicit IPC,
not `visibilitychange`; the bridge declares it a no-op). Eco and the liveness poll see a hidden
- window as "nobody watching" too.
+ window as "nobody watching" too. **A raw Electron `hide` is NOT the signal**: on macOS
+ `BrowserWindow` emits `hide`/`show` from occlusion changes (a window merely covered by another
+ app, another Space, ⌘H), so main forwards `hide` only when the close branch set
+ `windowHiddenByApp` before its own `win.hide()`; `minimize` always counts. A focused renderer
+ clears the flag (fail-safe for a WM that restores without a `restore` event).
- **Every memory lever must ask whether the kill ends live work** (`terminal/live-work.ts`). The
renderer reclaims terminal memory in FOUR places — park window expiry, the park's LRU cap, the
memory-pressure drop (all three in `park-budget.ts`) and the offscreen viewer release
diff --git a/src/main/index.ts b/src/main/index.ts
index cc0e4b420..714935276 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -1369,9 +1369,14 @@ function createWindow(): BrowserWindow {
// default), hide-on-close (macOS) or minimized window lets its terminals count as offscreen and
// the existing reclaim levers give memory back (renderer/terminal/window-backgrounded.ts). Every
// platform; the mapping is the pure main/window-visibility.ts.
+ let windowHiddenByApp = false
+ // `hiddenByApp` is set right before the close branch's own `win.hide()`: on macOS Electron also
+ // emits `hide` for a window that is merely OCCLUDED (or ⌘H-hidden), and that must not count.
for (const ev of WINDOW_VISIBILITY_EVENTS) {
win.on(ev as 'hide', () => {
- if (!win.isDestroyed()) win.webContents.send(IPC.appWindowVisibility, windowVisibilitySignal(ev))
+ const signal = windowVisibilitySignal(ev, { hiddenByApp: windowHiddenByApp })
+ if (ev === 'show' || ev === 'restore') windowHiddenByApp = false
+ if (signal && !win.isDestroyed()) win.webContents.send(IPC.appWindowVisibility, signal)
})
}
// Windows: the taskbar flash raised by an unread rise (appSetBadge) ends when the user comes back.
@@ -1390,6 +1395,7 @@ function createWindow(): BrowserWindow {
const action = closeAction(process.platform, quitting, win.isFullScreen(), backgroundOnCloseActive())
if (action === 'hide') {
e.preventDefault()
+ windowHiddenByApp = true
win.hide()
// Off macOS this is a background-mode hide (nothing is quitting, so no confirm gate either).
if (process.platform !== 'darwin') noteBackgroundHide()
@@ -1401,7 +1407,10 @@ function createWindow(): BrowserWindow {
leavingFullScreen = true
win.once('leave-full-screen', () => {
leavingFullScreen = false
- if (!win.isDestroyed() && !quitting) win.hide()
+ if (!win.isDestroyed() && !quitting) {
+ windowHiddenByApp = true
+ win.hide()
+ }
})
win.setFullScreen(false)
}
diff --git a/src/main/window-visibility.test.ts b/src/main/window-visibility.test.ts
index 24d35ac1e..d223dbe5f 100644
--- a/src/main/window-visibility.test.ts
+++ b/src/main/window-visibility.test.ts
@@ -2,11 +2,15 @@ import { describe, expect, it } from 'vitest'
import { WINDOW_VISIBILITY_EVENTS, windowVisibilitySignal } from './window-visibility'
describe('windowVisibilitySignal', () => {
- it('maps hide and minimize to hidden, show and restore to shown', () => {
- expect(windowVisibilitySignal('hide')).toBe('hidden')
- expect(windowVisibilitySignal('minimize')).toBe('hidden')
- expect(windowVisibilitySignal('show')).toBe('shown')
- expect(windowVisibilitySignal('restore')).toBe('shown')
+ it('maps an app-initiated hide and a minimize to hidden, show and restore to shown', () => {
+ expect(windowVisibilitySignal('hide', { hiddenByApp: true })).toBe('hidden')
+ expect(windowVisibilitySignal('minimize', { hiddenByApp: false })).toBe('hidden')
+ expect(windowVisibilitySignal('show', { hiddenByApp: false })).toBe('shown')
+ expect(windowVisibilitySignal('restore', { hiddenByApp: false })).toBe('shown')
+ })
+
+ it('ignores a hide the app did not ask for (macOS occlusion, Cmd+H): a covered window stays warm', () => {
+ expect(windowVisibilitySignal('hide', { hiddenByApp: false })).toBeNull()
})
it('covers exactly the four window events the shell subscribes to', () => {
diff --git a/src/main/window-visibility.ts b/src/main/window-visibility.ts
index e6f524ed6..eb7406ff7 100644
--- a/src/main/window-visibility.ts
+++ b/src/main/window-visibility.ts
@@ -5,6 +5,15 @@
// flips that to `hidden` for a window that is merely COVERED by another app, and a covered window
// must keep its terminals warm — the user is one ⌘Tab away. Only a window the user actually put
// away (close-to-tray / macOS hide-on-close / minimize) is backgrounded.
+//
+// The same trap exists one layer down, in Electron itself: on macOS `BrowserWindow` emits `hide`
+// and `show` from `windowDidChangeOcclusionState:` — i.e. for a window that is merely fully
+// covered by another app, switched away from on another Space, or hidden with ⌘H. Forwarding a
+// raw `hide` would therefore release every terminal of a Mac user who had a browser maximized over
+// nodeterm for two minutes. So `hide` counts ONLY when the app itself put the window away (the
+// close-to-tray / hide-on-close branch sets `hiddenByApp` right before its `win.hide()`).
+// `minimize` is unambiguous on every platform. `show` / `restore` always map to `'shown'`, which
+// the renderer treats idempotently.
/** The BrowserWindow events that change whether the user can see the window at all. */
export type WindowVisibilityEvent = 'hide' | 'show' | 'minimize' | 'restore'
@@ -18,11 +27,22 @@ export const WINDOW_VISIBILITY_EVENTS: readonly WindowVisibilityEvent[] = [
'restore'
]
+export interface WindowVisibilityContext {
+ /** True while the window is hidden because the APP hid it (close-to-tray / hide-on-close). */
+ hiddenByApp: boolean
+}
+
/**
- * Map one window event to the signal the renderer gets. `restore` can also arrive for a window
- * that was never minimized (some Linux window managers emit it on un-maximize); that maps to
- * `'shown'`, which the renderer treats idempotently — "shown" while shown changes nothing.
+ * Map one window event to the signal the renderer gets, or `null` for "say nothing". `restore` can
+ * also arrive for a window that was never minimized (some Linux window managers emit it on
+ * un-maximize); that maps to `'shown'`, which the renderer treats idempotently. A `hide` the app
+ * did not ask for (macOS occlusion, ⌘H) is `null`: the fail-safe direction is "keep everything".
*/
-export function windowVisibilitySignal(event: WindowVisibilityEvent): WindowVisibilitySignal {
- return event === 'hide' || event === 'minimize' ? 'hidden' : 'shown'
+export function windowVisibilitySignal(
+ event: WindowVisibilityEvent,
+ ctx: WindowVisibilityContext
+): WindowVisibilitySignal | null {
+ if (event === 'minimize') return 'hidden'
+ if (event === 'hide') return ctx.hiddenByApp ? 'hidden' : null
+ return 'shown'
}
diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsx
index 7e832c48e..00f443258 100644
--- a/src/renderer/canvas/Canvas.tsx
+++ b/src/renderer/canvas/Canvas.tsx
@@ -17747,7 +17747,7 @@ export function Canvas() {
if (dwell) clearTimeout(dwell)
dwell = null
}
- const off = window.nodeTerminal.onWindowVisibility?.((state) => {
+ const onSignal = (state: 'hidden' | 'shown'): void => {
const hidden = state === 'hidden'
setWindowBackgrounded(hidden)
if (!hidden) return clearDwell()
@@ -17756,9 +17756,18 @@ export function Canvas() {
dwell = null
if (isWindowBackgrounded()) runReclaimLevers()
}, BACKGROUND_RELEASE_DWELL_MS)
- })
+ }
+ const off = window.nodeTerminal.onWindowVisibility?.(onSignal)
+ // Fail-safe for a missed `'shown'` (a window manager that restores without a `restore` event):
+ // a document that has FOCUS is being looked at, so it can never stay backgrounded — otherwise
+ // the user would sit in front of released plates until the next hide/show cycle.
+ const onFocus = (): void => {
+ if (isWindowBackgrounded()) onSignal('shown')
+ }
+ window.addEventListener('focus', onFocus)
return () => {
off?.()
+ window.removeEventListener('focus', onFocus)
clearDwell()
setWindowBackgrounded(false)
}
diff --git a/src/renderer/terminal/window-backgrounded.wiring.test.ts b/src/renderer/terminal/window-backgrounded.wiring.test.ts
index 54b3a3911..694bf087e 100644
--- a/src/renderer/terminal/window-backgrounded.wiring.test.ts
+++ b/src/renderer/terminal/window-backgrounded.wiring.test.ts
@@ -14,7 +14,14 @@ describe('hidden-window reclaim wiring', () => {
it('main sends the signal for every window visibility event', () => {
const main = read('../../main/index.ts')
expect(main).toMatch(/for \(const ev of WINDOW_VISIBILITY_EVENTS\)/)
- expect(main).toContain('win.webContents.send(IPC.appWindowVisibility, windowVisibilitySignal(ev))')
+ expect(main).toContain('windowVisibilitySignal(ev, { hiddenByApp: windowHiddenByApp })')
+ expect(main).toContain('win.webContents.send(IPC.appWindowVisibility, signal)')
+ // Only the app's OWN hide counts (macOS emits `hide` on mere occlusion): every `win.hide()` in
+ // main is the close branch's, and each one is preceded by the flag.
+ const hides = (main.match(/^\s*win\.hide\(\)\s*$/gm) ?? []).length
+ const flagged = main.split('windowHiddenByApp = true\n').length - 1
+ expect(hides).toBeGreaterThan(0)
+ expect(flagged).toBe(hides)
})
it('the preload forwards it and the Server Edition declares it a no-op', () => {
@@ -24,12 +31,14 @@ describe('hidden-window reclaim wiring', () => {
it('Canvas sets the flag and runs the shared reclaim pair after the dwell', () => {
const canvas = read('../canvas/Canvas.tsx')
- const at = canvas.indexOf('window.nodeTerminal.onWindowVisibility?.(')
+ const at = canvas.indexOf('const onSignal = (state:')
expect(at).toBeGreaterThan(-1)
const effect = canvas.slice(at, canvas.indexOf('}, [])', at))
expect(effect).toContain('setWindowBackgrounded(hidden)')
expect(effect).toContain('BACKGROUND_RELEASE_DWELL_MS')
expect(effect).toContain('runReclaimLevers()')
+ // A focused document is being looked at: it clears a missed 'shown'.
+ expect(effect).toContain("window.addEventListener('focus', onFocus)")
// Memory pressure shares the same pair rather than a second copy of it.
expect(canvas).toContain('onMemoryPressure?.(() => runReclaimLevers())')
})