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(main): show the window on first paint only — never on a background reload
enesb71fc5f95e9d
diff --git a/CLAUDE.md b/CLAUDE.mdindex 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 tabbar (`TabBar.tsx`) is the drag region with the `nodeterm` logo + a rounded pill of projecttabs. The New-project `+` is a **sibling** of `.tabbar__tabs`, not its last child — insidediff --git a/src/main/index.ts b/src/main/index.tsindex 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) returnif (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.tsnew file mode 100644index 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+ )+ }+ })+})