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(main): show the window on first paint only — never on a background reload

enesb71fc5f95e9d
diff --git a/CLAUDE.md b/CLAUDE.md
index 3b2337c04..5ccce90e0 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -3516,6 +3516,30 @@ the Settings section and ShortcutsPanel start disagreeing about what a chord mea
- **Shortcuts** (`ShortcutsPanel.tsx`, ? / ⌘/): shown once on first launch (`seenShortcuts`).
**Derived from the registry, never hand-listed** — see the Keybindings invariant below.
- **Welcome** (`WelcomeScreen.tsx`): shown when no projects exist.
+- **Nothing raises the window without a user action** (issue #737, the THIRD in this family —
+ #665 and #702 were canvas-control moving the user's VIEW; this one is the OS window activating
+ over another app). The cause was `win.on('ready-to-show', () => win.show())`: `ready-to-show`
+ fires on the first paint of EVERY main-frame navigation, not once per window (MEASURED on
+ Electron 42.9.1 — a `webContents.reload()` on a VISIBLE window emits it again with `isVisible()`
+ already true), and the crash auto-reload (`render-process-gone` → `webContents.reload()`) is an
+ unattended navigation. So a backgrounded renderer being killed — macOS jetsam on a machine
+ running several agent CLIs at 335 MB–1.2 GB each — silently raised nodeterm over whatever the
+ user had ⌘Tabbed to. It is `win.once` now. **The gate must be FIRST PAINT, not `isVisible()`**:
+ after macOS hide-on-close the window is hidden but alive, and an `isVisible()` gate would `show()`
+ it on a background reload — the same bug inverted.
+ The permitted raises are all a CLICK, and they are enumerated with their triggering action in
+ **`src/main/window-raise.guard.test.ts`**, an allowlist-with-reasons in the shape of
+ `fs-atomic.guard.test.ts`: a notification tap (the one exception the rule names), a Notch HUD
+ row, a Dock activate, a second launch, and a file dropped onto a terminal. Nothing an AGENT can
+ do reaches any of them — canvas control, trigger nodes, hook POSTs, relay/pairing/push and
+ browser-drive contain no show/focus/dialog call, and agent confirms are in-renderer
+ `ConfirmDialog`s, never native. The drop IPC's `app.focus({steal:true})` is the only
+ renderer-reachable cross-app activation and now carries the same sender guard its two neighbours
+ (`uiShortcutRecording`, `uiTerminalFocus`) already had — a `<webview>` guest is a webContents in
+ this process. **KNOWN GAP, listed in the guard rather than fixed**: `standing-host.ts`'s
+ `dialog.showErrorBox` for a locked keyring is app-modal, unparented, and raised from the relay
+ RECONNECT TIMER; the honest fix routes it to a non-modal in-app surface and owes a macOS check
+ that a sheet on a background window does not activate.
- **Window chrome**: macOS integrated title bar (`titleBarStyle: 'hiddenInset'`); the tab
bar (`TabBar.tsx`) is the drag region with the `nodeterm` logo + a rounded pill of project
tabs. The New-project `+` is a **sibling** of `.tabbar__tabs`, not its last child — inside
diff --git a/src/main/index.ts b/src/main/index.ts
index 10224cf69..be2062224 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -1078,7 +1078,23 @@ function createWindow(): BrowserWindow {
}
})
- win.on('ready-to-show', () => win.show())
+ // FIRST PAINT ONLY — `once`, never `on` (issue #737).
+ //
+ // `ready-to-show` fires on the first paint of EVERY main-frame navigation, not once per window.
+ // MEASURED on Electron 42.9.1 (the reporter ran 42.10.0): a `webContents.reload()` on a VISIBLE
+ // window emits it a second time, with `isVisible()` already true. The crash auto-reload above is
+ // an unattended background navigation, so a persistent listener called `win.show()` on a window
+ // that was already showing — and on macOS `show()` activates the app. That is nodeterm raising
+ // itself over whatever the user had just ⌘Tabbed to, with no user action anywhere in the chain.
+ //
+ // Nothing may bring the window forward without a user action. The exceptions are enumerated in
+ // `window-raise.guard.test.ts`, and all of them are a click: a notification tap, a HUD row, a
+ // Dock activate, a second launch, a file dropped onto a terminal.
+ //
+ // The gate is FIRST PAINT, not `isVisible()`. After macOS hide-on-close the window is hidden but
+ // alive, and an `isVisible()` gate would then `show()` it on a background reload — the same bug
+ // inverted, raising a window the user had deliberately put away.
+ win.once('ready-to-show', () => win.show())
// The main window is a regular app window; establishing its Dock presence explicitly means the
// later focusable:false Notch HUD panel can never leave the app looking like an accessory.
win.on('show', () => assertRegularDockPresence())
@@ -1460,9 +1476,15 @@ app.whenReady().then(async () => {
// another app does NOT activate the destination app, so without this the drag-source keeps OS
// keyboard focus and the user types into the wrong application. `getMainWindow()` (not the
// focused window — there may be none) restores + shows + focuses.
- ipcMain.on(IPC.appFocusWindow, () => {
+ ipcMain.on(IPC.appFocusWindow, (event) => {
const w = getMainWindow()
if (!w) return
+ // The SAME sender guard as `uiShortcutRecording` / `uiTerminalFocus` above, and for the same
+ // reason: a <webview> guest — a browser node showing an arbitrary page — is a webContents in
+ // this process, and this is the one renderer-reachable `app.focus({steal:true})` in the app.
+ // Without the guard a page could activate nodeterm over whatever the user was doing (the
+ // no-unconsented-raise rule of issue #737). Its two neighbours were guarded; this was not.
+ if (w.webContents.id !== event.sender.id) return
if (w.isMinimized()) w.restore()
w.show()
// On macOS `win.focus()` alone won't pull us in front of the still-active drag-source app —
diff --git a/src/main/window-raise.guard.test.ts b/src/main/window-raise.guard.test.ts
new file mode 100644
index 000000000..9467b8374
--- /dev/null
+++ b/src/main/window-raise.guard.test.ts
@@ -0,0 +1,185 @@
+import { readFileSync, readdirSync, statSync } from 'fs'
+import { join, relative } from 'path'
+import { describe, expect, it } from 'vitest'
+
+/**
+ * Nothing may bring the window forward without a user action.
+ *
+ * Issue #737 was the THIRD report in this family. The first two (#665, #702) were canvas-control
+ * moving the user's VIEW — the project tab switched, the camera flew — and both were closed by
+ * making display verbs write off-canvas instead of travelling. #737 is a layer below: the OS
+ * window itself activated over another application while the user was in it, which no in-app
+ * routing rule can reach.
+ *
+ * The cause was `win.on('ready-to-show', () => win.show())`. `ready-to-show` fires on the first
+ * paint of EVERY main-frame navigation, and the crash auto-reload (`render-process-gone` →
+ * `webContents.reload()`, shipped 2026-08-10, an ancestor of the reporter's v0.3.4) is an
+ * unattended one — so a background renderer death raised the app. MEASURED on Electron 42.9.1: a
+ * reload on a visible window emits `ready-to-show` a second time with `isVisible()` already true.
+ *
+ * What was missing was not the fix but the FENCE. There was no test anywhere pinning where the app
+ * is allowed to raise itself, so each instance had to be re-discovered by a user. This is that
+ * fence, in the shape this repo already uses for the same class of invisible-to-the-toolchain rule
+ * (`fs-atomic.guard.test.ts`, `info-plist.test.ts`, `keydown-intercept.test.ts`): an
+ * allowlist-with-reasons that fails when it GROWS, so a new raise is a decision somebody signs for.
+ *
+ * It counts rather than inspects, deliberately. A count survives every edit that does not add a
+ * raise, and it cannot be satisfied by renaming a variable — which a pattern match on `w.show()`
+ * could be.
+ */
+const MAIN_ROOT = __dirname
+
+/** Guard comparisons use one separator regardless of the host running Vitest (issue #746). */
+function normalizedSourcePath(value: string): string {
+ return value.replace(/\\/g, '/')
+}
+
+/**
+ * Calls that put a window in front of the user, or put the app in front of another app.
+ *
+ * `showInactive` is deliberately NOT here: it is the opposite of a raise (the Notch HUD's whole
+ * point is appearing without taking focus), and listing it would train the next reader to treat
+ * the two as the same thing.
+ */
+const RAISE_CALL =
+ /\.(show|focus|restore|moveTop|flashFrame)\(\s*\)|app\.focus\(|setAlwaysOnTop\(|showErrorBox\(/g
+
+/**
+ * Every file that may raise, how many raise-shaped calls it holds, and WHY each is allowed.
+ *
+ * The reason column is the point of the file. A number with no sentence beside it is a budget; a
+ * number with one is a contract about what the app is permitted to do to someone's screen.
+ */
+const ALLOWED = new Map<string, { calls: number; why: string }>([
+ [
+ 'index.ts',
+ {
+ calls: 14,
+ why:
+ '3 second-instance restore/show/focus (the user launched the app again); 1 first-paint ' +
+ 'show (once, never on — #737); 4 file-drop IPC restore/show/app.focus(steal)/focus, now ' +
+ 'sender-guarded (a real drop, and macOS does not activate a drop destination by itself); ' +
+ '3 notification-CLICK restore/show/focus — the one legitimate exception, a tap; 1 ' +
+ "Notification.show() posting it; 2 app.on('activate') show/focus (Dock click)"
+ }
+ ],
+ [
+ 'updater.ts',
+ {
+ calls: 4,
+ why:
+ 'the update-ready notification: Notification.show() to post it, then restore/show/focus ' +
+ 'inside its own click handler — a tap, the same exception as above'
+ }
+ ],
+ [
+ 'notch-hud.ts',
+ {
+ calls: 5,
+ why:
+ 'app.dock.show() (Dock PRESENCE, not a raise — it keeps the focusable:false HUD from ' +
+ 'making the app look like an accessory); setAlwaysOnTop for the HUD panel itself, which ' +
+ 'is shown with showInactive and never takes focus; and restore/show/focus in the HUD ' +
+ "row's own click handler — a click on a nodeterm surface"
+ }
+ ],
+ [
+ 'remote/standing-host.ts',
+ {
+ calls: 1,
+ why:
+ 'KNOWN GAP, reported not fixed: an app-modal dialog.showErrorBox raised from the relay ' +
+ 'RECONNECT TIMER when the OS keyring is locked — no window parent, no user action. It is ' +
+ 'a real instance of this rule and a different symptom from #737 (the user sees a dialog, ' +
+ 'not a silent raise); the honest fix routes it to a non-modal in-app surface and needs a ' +
+ 'macOS check that a sheet on a background window does not activate. Listed so it cannot ' +
+ 'be forgotten, and so the count still fails if a SECOND one appears here'
+ }
+ ]
+])
+
+function sourceFiles(dir: string, out: string[] = []): string[] {
+ for (const entry of readdirSync(dir)) {
+ const full = join(dir, entry)
+ if (statSync(full).isDirectory()) {
+ if (entry !== 'node_modules') sourceFiles(full, out)
+ continue
+ }
+ if (!/\.ts$/.test(entry) || /\.test\.ts$/.test(entry)) continue
+ out.push(full)
+ }
+ return out
+}
+
+/** Comments quote these calls constantly (this file most of all) — only real code counts. */
+function isComment(line: string): boolean {
+ const t = line.trimStart()
+ return t.startsWith('//') || t.startsWith('*') || t.startsWith('/*')
+}
+
+function raiseCallCount(source: string): number {
+ return source
+ .split('\n')
+ .filter((line) => !isComment(line))
+ .reduce((n, line) => n + (line.match(RAISE_CALL)?.length ?? 0), 0)
+}
+
+describe('nothing raises the window without a user action', () => {
+ const files = sourceFiles(MAIN_ROOT)
+
+ it('the window is shown on FIRST PAINT only — once, never on', () => {
+ // The whole of #737 in one line. `on` re-fires for the crash auto-reload's navigation, which
+ // no user asked for; `once` cannot. An `isVisible()` gate is NOT an acceptable substitute —
+ // after macOS hide-on-close the window is hidden, and that gate would show it on a background
+ // reload, raising a window the user deliberately put away.
+ const src = readFileSync(join(MAIN_ROOT, 'index.ts'), 'utf8')
+ expect(src).toContain("win.once('ready-to-show'")
+ expect(src).not.toContain("win.on('ready-to-show'")
+ })
+
+ it('the one renderer-reachable cross-app activation is sender-guarded', () => {
+ // A <webview> guest — a browser node showing an arbitrary page — is a webContents in this
+ // process. `app.focus({ steal: true })` reached from an unguarded IPC is a page activating the
+ // app over whatever the user was doing. Its two neighbours (uiShortcutRecording,
+ // uiTerminalFocus) carry this guard; this handler did not.
+ const src = readFileSync(join(MAIN_ROOT, 'index.ts'), 'utf8')
+ const handler = src.slice(
+ src.indexOf('ipcMain.on(IPC.appFocusWindow'),
+ src.indexOf('ipcMain.on(IPC.appFocusWindow') + 1200
+ )
+ expect(handler.length).toBeGreaterThan(0)
+ expect(handler).toContain('app.focus({ steal: true })')
+ expect(handler).toContain('w.webContents.id !== event.sender.id')
+ // The guard must come BEFORE the raise, or it guards nothing.
+ expect(handler.indexOf('event.sender.id')).toBeLessThan(handler.indexOf('w.show()'))
+ })
+
+ it('no file outside the documented allowlist raises at all', () => {
+ const offenders: string[] = []
+ for (const file of files) {
+ const rel = normalizedSourcePath(relative(MAIN_ROOT, file))
+ if (ALLOWED.has(rel)) continue
+ const count = raiseCallCount(readFileSync(file, 'utf8'))
+ if (count > 0) offenders.push(`${rel}: ${count}`)
+ }
+ expect(
+ offenders,
+ 'a new window raise needs an entry in ALLOWED saying which USER ACTION triggers it — see #737'
+ ).toEqual([])
+ })
+
+ it('the allowlisted counts do not silently grow', () => {
+ const seen = new Map(
+ files.map((f) => [
+ normalizedSourcePath(relative(MAIN_ROOT, f)),
+ raiseCallCount(readFileSync(f, 'utf8'))
+ ])
+ )
+ for (const [rel, { calls, why }] of ALLOWED) {
+ expect(seen.has(rel), `${rel} is allowlisted but no longer exists`).toBe(true)
+ expect(seen.get(rel), `${rel} changed its raise count — is the new one user-triggered? (${why})`).toBe(
+ calls
+ )
+ }
+ })
+})