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.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
fix(window): ignore macOS occlusion hides; a focused window is never backgrounded
review01e45ab8ebb5
diff --git a/CLAUDE.md b/CLAUDE.mdindex 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 anew 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`). Therenderer reclaims terminal memory in FOUR places — park window expiry, the park's LRU cap, thememory-pressure drop (all three in `park-budget.ts`) and the offscreen viewer releasediff --git a/src/main/index.ts b/src/main/index.tsindex 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 = truewin.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 = truewin.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.tsindex 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.tsindex 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.tsxindex 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 = nullif (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.tsindex 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())')})