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.

Merge remote-tracking branch 'origin/main' into feat/remember-window-size-and-position

Shogun51f6489d44f3
diff --cc CLAUDE.md
index 3d7a28a04,43a4b4aee..c0772937e
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@@ -3112,44 -3557,30 +3557,68 @@@ the Settings section and ShortcutsPane
- **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 geometry is REMEMBERED** (`main/window-state.ts`, `<userData>/window-state.json`) — size,
+ position and maximized state, restored at the next launch. Before this the window opened at a
+ hard-coded 1400x900 every time, on every platform, so a user who works maximized re-maximized it
+ on every launch; Electron persists nothing on its own and no platform does it for us. The module
+ is Electron-free in the `keydown-intercept.ts` shape (pure decisions over plain rectangles,
+ structural window interfaces), so the refusals below can be pressed by a test instead of only by
+ someone with two monitors — `screen.getAllDisplays()` is called at the seam in `index.ts` and its
+ **work areas** (not full display bounds) are passed in. The refusals ARE the feature, because each
+ is a way the naive version is worse than the fixed size it replaces:
+ - **`getNormalBounds()`, never `getBounds()`.** While maximized the latter returns the MAXIMIZED
+ rectangle, so saving it makes the next un-maximize hand back a screen-sized window — state that
+ looks right and behaves wrong, and only for the users who maximize.
+ - **A position that is no longer reachable is DROPPED, not clamped.** A laptop undocked from the
+ monitor its window was on would otherwise reopen the app off-screen: running, focusable from the
+ dock, visible nowhere, with no gesture that rescues it. Reachable means a real overlap with some
+ work area (`MIN_VISIBLE_WIDTH`/`HEIGHT`), judged against the CLAMPED size — a few pixels on
+ screen is not a title bar anyone can grab. Dropping keeps the user's size and lets the platform
+ place a window it knows how to place; inventing a corner for it is the guess.
+ - **No capture while minimized or fullscreen.** `isMaximized()` is FALSE while a macOS window is
+ fullscreen, so capturing there records `maximized: false` and erases exactly the preference this
+ exists to remember. The last non-fullscreen state stands, which also means the app never reopens
+ INTO fullscreen — deliberate: a fullscreen window is usually a temporary mode and is much harder
+ to escape on first launch than a maximized one.
+ - **Maximize before the first paint**, while the window is still `show: false`; maximizing after
+ `show()` is a visible jump from the restored size on every launch.
+ - Every field is **re-validated as a number on read** — the file is hand-editable and its values
+ reach the `BrowserWindow` constructor before there is a window in which to report a failure.
+ - Saves are debounced (`resize`/`move` fire continuously through a drag) and flushed
+ **synchronously** on `close`: that is the only moment guaranteed to see the final state, and an
+ awaited write there races the process exit. Published through `renameAtomicSync` with a
+ per-call unique temp, like every other store.
+ - **NT_MULTI is excluded**: a throwaway dev sandbox may share the real app's userData, and it must
+ not move the window of the app being developed.
+ - Desktop only, and genuinely so — a browser tab's geometry is the browser's, and the mobile
+ companion has no window. Nothing here belongs in `src/core`. **Wayland caveat**: a native-Wayland
+ client cannot set its own position (the compositor owns placement), so x/y is honoured under
+ XWayland and quietly ignored otherwise. Size and maximized restore either way, which is what the
+ drop-don't-clamp rule already degrades to.
- **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