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
feat(windows): background-mode setting and hide-to-tray close policy
review3819a6ce65bc
diff --git a/src/core/settings-store.test.ts b/src/core/settings-store.test.tsindex 7b0f6856f..d6a783145 100644--- a/src/core/settings-store.test.ts+++ b/src/core/settings-store.test.ts@@ -194,6 +194,29 @@ describe('SettingsStore nested-default merge', () => {})})+ describe('runInBackgroundOnClose', () => {+ const load = (saved: Record<string, unknown>): Settings => {+ writeFileSync(path.join(dir, 'settings.json'), JSON.stringify(saved), 'utf-8')+ const store = new SettingsStore()+ store.init()+ return store.get()+ }++ it("defaults to 'auto' for a settings.json that predates the key", () => {+ expect(load({ fontSize: 13 }).runInBackgroundOnClose).toBe('auto')+ })++ it('keeps the three known values', () => {+ for (const v of ['auto', 'on', 'off']) expect(load({ runInBackgroundOnClose: v }).runInBackgroundOnClose).toBe(v)+ })++ it("normalizes a hand-edited garbage value to 'auto'", () => {+ expect(load({ runInBackgroundOnClose: true }).runInBackgroundOnClose).toBe('auto')+ expect(load({ runInBackgroundOnClose: 'tray' }).runInBackgroundOnClose).toBe('auto')+ expect(load({ runInBackgroundOnClose: null }).runInBackgroundOnClose).toBe('auto')+ })+ })+describe('agent launch mode migration', () => {const loadWith = (saved: Record<string, unknown>): Settings => {writeFileSync(path.join(dir, 'settings.json'), JSON.stringify(saved), 'utf-8')diff --git a/src/core/settings-store.ts b/src/core/settings-store.tsindex 7aea5bf79..f68d6a5f1 100644--- a/src/core/settings-store.ts+++ b/src/core/settings-store.ts@@ -91,6 +91,10 @@ function mergeSettings(saved: Partial<Settings> | null | undefined): Settings {}// Keep the mirror in lockstep with the resolved mode so an older build still honors the choice.merged.vanillaLaunchDefault = merged.agentLaunchMode === "subscription";+ // Background mode is hand-editable too: anything but the three known values is the default.+ const bg = merged.runInBackgroundOnClose as unknown;+ if (bg !== "auto" && bg !== "on" && bg !== "off")+ merged.runInBackgroundOnClose = DEFAULT_SETTINGS.runInBackgroundOnClose;// Pre-release switch that became the "Liquid Glass" appearance; honoured once so a tester's// choice carries over, and only where the appearance still followed the terminal.const legacyGlass = (saved as { glassTerminals?: unknown } | null | undefined)?.glassTerminals;diff --git a/src/main/background-mode.test.ts b/src/main/background-mode.test.tsnew file mode 100644index 000000000..e49ed17c8--- /dev/null+++ b/src/main/background-mode.test.ts@@ -0,0 +1,50 @@+import { describe, expect, it } from 'vitest'+import { readFileSync } from 'fs'+import { join } from 'path'+import { resolveBackgroundOnClose, shouldShowBackgroundHint } from './background-mode'++describe('resolveBackgroundOnClose', () => {+ it("'auto' is on for Windows and off for Linux", () => {+ expect(resolveBackgroundOnClose('auto', 'win32')).toBe(true)+ expect(resolveBackgroundOnClose('auto', 'linux')).toBe(false)+ })+ it('honors an explicit on/off on Windows and Linux', () => {+ for (const p of ['win32', 'linux']) {+ expect(resolveBackgroundOnClose('on', p)).toBe(true)+ expect(resolveBackgroundOnClose('off', p)).toBe(false)+ }+ })+ it('is always false on macOS (it hides on close anyway; no tray)', () => {+ for (const v of ['auto', 'on', 'off']) expect(resolveBackgroundOnClose(v, 'darwin')).toBe(false)+ })+ it("reads an unknown value as 'auto'", () => {+ expect(resolveBackgroundOnClose('tray', 'win32')).toBe(true)+ expect(resolveBackgroundOnClose(undefined, 'linux')).toBe(false)+ expect(resolveBackgroundOnClose(true, 'linux')).toBe(false)+ })+})++describe('shouldShowBackgroundHint', () => {+ it('shows once, only for a background-mode hide off macOS', () => {+ expect(shouldShowBackgroundHint({ platform: 'win32', backgroundOnClose: true, alreadyShown: false })).toBe(true)+ expect(shouldShowBackgroundHint({ platform: 'win32', backgroundOnClose: true, alreadyShown: true })).toBe(false)+ expect(shouldShowBackgroundHint({ platform: 'win32', backgroundOnClose: false, alreadyShown: false })).toBe(false)+ expect(shouldShowBackgroundHint({ platform: 'darwin', backgroundOnClose: true, alreadyShown: false })).toBe(false)+ })+})++describe('main/index.ts background-mode wiring (source guard)', () => {+ const src = readFileSync(join(__dirname, 'index.ts'), 'utf-8')+ it('passes the live background flag into closeAction', () => {+ expect(src).toContain('closeAction(process.platform, quitting, win.isFullScreen(), backgroundOnCloseActive())')+ })+ it('tears the tray down in before-quit, right after the quitting flag flips', () => {+ expect(src).toMatch(/quitting = true \/\/ from here on[^\n]*\n\s*destroyNotchHud\(\)\n\s*backgroundTray\?\.destroy\(\)/)+ })+ it('keeps the updater restart flipping `quitting` so a hidden window really closes', () => {+ expect(src).toMatch(/initUpdater\(\(\) => \{\s*quitting = true/)+ })+ it('tray Quit goes through app.quit() (before-quit + confirm), not app.exit()', () => {+ expect(src).toMatch(/onAction: \(action\) => \(action === 'open' \? showMainWindowFromBackground\(\) : app\.quit\(\)\)/)+ })+})diff --git a/src/main/background-mode.ts b/src/main/background-mode.tsnew file mode 100644index 000000000..37bb4b136--- /dev/null+++ b/src/main/background-mode.ts@@ -0,0 +1,53 @@+// Windows/Linux "background mode" — closing the window hides it to the notification-area tray+// instead of quitting (the analogue of macOS keeping the app alive in the Dock), so the phone relay+// host, hook server, agent-status notifications and the updater outlive the window.+//+// Pure + Electron-free so the policy is pressable on any CI box. The controller is ./tray.ts; the+// close-event decision is `closeAction` in ./main-window.ts, which takes the resolved flag.++import type { BackgroundOnCloseSetting } from '../shared/types'++/**+ * Whether a window close should hide to the tray on this platform.+ *+ * - macOS: always `false` — it hides on close regardless (main-window.ts), and has no tray to add.+ * - `'on'` / `'off'`: the user's explicit choice.+ * - `'auto'`: on for Windows, where the notification area always exists and a running background+ * app there is the norm; OFF for Linux, whose tray depends on the desktop environment (stock+ * GNOME has none without an extension) — hiding a window into a tray the user cannot see would+ * look like a quit that did not happen. A Linux user who has a tray opts in with `'on'`.+ *+ * Any value that is not one of the three reads as `'auto'` (settings.json is hand-editable; the+ * store already normalizes, this is the interpolation-site re-check).+ */+export function resolveBackgroundOnClose(+ setting: BackgroundOnCloseSetting | unknown,+ platform: NodeJS.Platform | string+): boolean {+ if (platform === 'darwin') return false+ if (setting === 'on') return true+ if (setting === 'off') return false+ return platform === 'win32'+}++/** Marker file (under userData) recording that the one-time "still running in the tray" notice was+ * shown. A file rather than a settings key: the renderer saves FULL settings snapshots from its own+ * copy, so a main-side settings write would be overwritten by the next renderer save. */+export const BACKGROUND_HINT_MARKER = 'background-close-hint-shown'++export const BACKGROUND_HINT = {+ title: 'nodeterm is still running',+ body: 'Closing the window keeps nodeterm in the notification area so your phone and agent notifications stay connected. Quit from the tray icon.'+} as const++/**+ * Should the first-hide notice show now? Only on an actual background-mode hide (never on macOS,+ * whose Dock already says the app is running), and only once per install.+ */+export function shouldShowBackgroundHint(opts: {+ platform: NodeJS.Platform | string+ backgroundOnClose: boolean+ alreadyShown: boolean+}): boolean {+ return opts.platform !== 'darwin' && opts.backgroundOnClose && !opts.alreadyShown+}diff --git a/src/main/main-window.test.ts b/src/main/main-window.test.tsindex 80027ba43..a7f786b5e 100644--- a/src/main/main-window.test.ts+++ b/src/main/main-window.test.ts@@ -158,6 +158,12 @@ describe('shouldHideOnClose', () => {expect(shouldHideOnClose('win32', false)).toBe(false)expect(shouldHideOnClose('linux', false)).toBe(false)})+ it('hides off macOS only in background mode, and never while quitting', () => {+ expect(shouldHideOnClose('win32', false, true)).toBe(true)+ expect(shouldHideOnClose('linux', false, true)).toBe(true)+ expect(shouldHideOnClose('win32', false, false)).toBe(false)+ expect(shouldHideOnClose('win32', true, true)).toBe(false)+ })})describe('closeAction', () => {@@ -175,4 +181,20 @@ describe('closeAction', () => {expect(closeAction('linux', false, true)).toBe('default')expect(closeAction('win32', false, true)).toBe('default')})+ it('hides to the tray off macOS when background mode is on — plain hide, no Space dance', () => {+ expect(closeAction('win32', false, false, true)).toBe('hide')+ expect(closeAction('win32', false, true, true)).toBe('hide')+ expect(closeAction('linux', false, true, true)).toBe('hide')+ })+ it('lets the close through when quitting, background mode or not', () => {+ expect(closeAction('win32', true, false, true)).toBe('default')+ expect(closeAction('linux', true, true, true)).toBe('default')+ })+ it('macOS is unchanged by the background flag (it always hides)', () => {+ for (const bg of [false, true]) {+ expect(closeAction('darwin', false, false, bg)).toBe('hide')+ expect(closeAction('darwin', false, true, bg)).toBe('leave-fullscreen-then-hide')+ expect(closeAction('darwin', true, true, bg)).toBe('default')+ }+ })})diff --git a/src/main/main-window.ts b/src/main/main-window.tsindex 8988ae837..d65586cc9 100644--- a/src/main/main-window.ts+++ b/src/main/main-window.ts@@ -69,9 +69,16 @@ export function createCrashReloadPolicy(// macOS convention: closing the window hides it (the app — and its tmux sessions,// hook server, updater, license watchers — keeps running); a real close only happens-// on quit. Other platforms quit on window close, so never intercept there.-export function shouldHideOnClose(platform: NodeJS.Platform | string, quitting: boolean): boolean {- return platform === 'darwin' && !quitting+// on quit. On Windows/Linux the same hide is opt-in "background mode"+// (`settings.runInBackgroundOnClose`, resolved by `resolveBackgroundOnClose` in+// ./background-mode): the window hides to the notification-area tray so the phone relay+// host, hook server and notifications outlive it. Off ⇒ close quits, as it always did.+export function shouldHideOnClose(+ platform: NodeJS.Platform | string,+ quitting: boolean,+ backgroundOnClose = false+): boolean {+ return !quitting && (platform === 'darwin' || backgroundOnClose)}export type CloseAction = 'default' | 'hide' | 'leave-fullscreen-then-hide'@@ -82,12 +89,14 @@ export type CloseAction = 'default' | 'hide' | 'leave-fullscreen-then-hide'* known Electron behavior electron/electron#20263) — so fullscreen must be exited, the async* `leave-full-screen` transition awaited, and only THEN the window hidden. The quit path is not* affected: there the window really closes and the app (and its Space) goes away with it.+ * Spaces are a macOS concept, so a background-mode hide elsewhere is a plain hide.*/export function closeAction(platform: NodeJS.Platform | string,quitting: boolean,- isFullScreen: boolean+ isFullScreen: boolean,+ backgroundOnClose = false): CloseAction {- if (!shouldHideOnClose(platform, quitting)) return 'default'- return isFullScreen ? 'leave-fullscreen-then-hide' : 'hide'+ if (!shouldHideOnClose(platform, quitting, backgroundOnClose)) return 'default'+ return platform === 'darwin' && isFullScreen ? 'leave-fullscreen-then-hide' : 'hide'}diff --git a/src/renderer/components/settings/sections/BehaviorSection.tsx b/src/renderer/components/settings/sections/BehaviorSection.tsxindex 93462c681..5fee12b7a 100644--- a/src/renderer/components/settings/sections/BehaviorSection.tsx+++ b/src/renderer/components/settings/sections/BehaviorSection.tsx@@ -7,7 +7,10 @@ import { NumberField } from '@renderer/ui/NumberField'import { Select } from '@renderer/ui/Select'import { SegmentedPill } from '@renderer/ui/SegmentedPill'import { Input } from '@renderer/ui/Input'-import { hintLabel } from '@shared/platform-utils'+import { hintLabel, isMacPlatform, isWindowsPlatform } from '@shared/platform-utils'+import { isBrowserRuntime } from '@renderer/bridge/runtime'+import { backgroundCloseDescription, backgroundCloseRowVisible } from '@renderer/lib/backgroundClose'+import type { BackgroundOnCloseSetting } from '@shared/types'import { clampWheelZoomSpeed } from '@renderer/canvas/wheel-zoom'import { DEFAULT_WORKTREE_PATH_TEMPLATE } from '@shared/worktree'@@ -92,9 +95,16 @@ const ROWS = {confirmQuit: {title: 'Confirm before quitting',keywords: ['quit', 'exit', 'close', 'confirm', 'dialog', 'ask']+ },+ backgroundClose: {+ title: 'Keep running when the window closes',+ keywords: ['tray', 'background', 'close', 'minimize', 'notification area', 'system tray', 'quit', 'phone']}}-const ENTRIES = Object.values(ROWS)+// The background-close row only exists for a desktop window off macOS, so search must not offer+// it anywhere else. Decided once: neither the platform nor the runtime changes under a live page.+const SHOW_BACKGROUND_CLOSE = backgroundCloseRowVisible(isMacPlatform(), isBrowserRuntime())+const ENTRIES = Object.values(ROWS).filter((r) => SHOW_BACKGROUND_CLOSE || r !== ROWS.backgroundClose)export function BehaviorSection({ isActive }: { isActive: boolean }): React.JSX.Element {const settings = useSettings((s) => s.settings)@@ -467,6 +477,25 @@ export function BehaviorSection({ isActive }: { isActive: boolean }): React.JSX.}/></SearchableRow>+ {SHOW_BACKGROUND_CLOSE && (+ <SearchableRow {...ROWS.backgroundClose}>+ <FieldRow+ label="Keep running when the window closes"+ description={backgroundCloseDescription(isWindowsPlatform())}+ control={+ <Select+ aria-label="Keep running when the window closes"+ value={settings.runInBackgroundOnClose}+ onChange={(e) => update({ runInBackgroundOnClose: e.target.value as BackgroundOnCloseSetting })}+ >+ <option value="auto">Automatic</option>+ <option value="on">Always</option>+ <option value="off">Never (closing quits)</option>+ </Select>+ }+ />+ </SearchableRow>+ )}</SettingsSection>)}diff --git a/src/renderer/lib/backgroundClose.test.ts b/src/renderer/lib/backgroundClose.test.tsnew file mode 100644index 000000000..56945970a--- /dev/null+++ b/src/renderer/lib/backgroundClose.test.ts@@ -0,0 +1,24 @@+import { describe, expect, it } from 'vitest'+import { backgroundCloseDescription, backgroundCloseRowVisible } from './backgroundClose'++describe('backgroundCloseRowVisible', () => {+ it('shows only for a desktop window off macOS', () => {+ expect(backgroundCloseRowVisible(false, false)).toBe(true)+ expect(backgroundCloseRowVisible(true, false)).toBe(false)+ expect(backgroundCloseRowVisible(false, true)).toBe(false)+ expect(backgroundCloseRowVisible(true, true)).toBe(false)+ })+})++describe('backgroundCloseDescription', () => {+ it('names the Windows notification area and its automatic default', () => {+ const d = backgroundCloseDescription(true)+ expect(d).toContain('notification area')+ expect(d).toContain('Automatic keeps it running on Windows')+ })+ it('says Automatic quits on Linux (matches resolveBackgroundOnClose)', () => {+ const d = backgroundCloseDescription(false)+ expect(d).toContain('system tray')+ expect(d).toContain('Automatic quits on Linux')+ })+})diff --git a/src/renderer/lib/backgroundClose.ts b/src/renderer/lib/backgroundClose.tsnew file mode 100644index 000000000..39a44f527--- /dev/null+++ b/src/renderer/lib/backgroundClose.ts@@ -0,0 +1,15 @@+// Settings → Behavior "Keep running when the window closes" (settings.runInBackgroundOnClose).+// Pure so the visibility + copy decisions are testable without a DOM. The policy itself is+// `resolveBackgroundOnClose` in src/main/background-mode.ts — the copy here must describe it.++/** Only a desktop window off macOS has the choice: macOS always keeps running in the Dock, and+ * the Server Edition has no window to close (its browser tab is not the app). */+export function backgroundCloseRowVisible(isMac: boolean, isBrowser: boolean): boolean {+ return !isMac && !isBrowser+}++export function backgroundCloseDescription(isWindows: boolean): string {+ const where = isWindows ? 'notification area' : 'system tray'+ const auto = isWindows ? 'Automatic keeps it running on Windows.' : 'Automatic quits on Linux, where a tray icon depends on your desktop.'+ return `Closing the window hides nodeterm to the ${where} so phone access, agent notifications and updates keep working. Quit from the tray icon or Ctrl+Q. ${auto}`+}diff --git a/src/shared/types.ts b/src/shared/types.tsindex 679d2e87a..91acbbb75 100644--- a/src/shared/types.ts+++ b/src/shared/types.ts@@ -1750,6 +1750,9 @@ export interface ZoomActualSizeModifiers {}/** User-configurable application settings (settings.json). */+/** `settings.runInBackgroundOnClose` — see the field's doc. */+export type BackgroundOnCloseSetting = 'auto' | 'on' | 'off'+export interface Settings {fontSize: numberfontFamily: string@@ -2222,6 +2225,14 @@ export interface Settings {* The auto-update "Restart to update" flow never asks — that decision was already made.* Settings → Behavior. */confirmBeforeQuit: boolean+ /** Windows/Linux "background mode": closing the window hides it to the notification-area tray+ * instead of quitting, so the phone relay host, hook server, notifications and updater keep+ * running — the analogue of macOS keeping the app in the Dock. `'auto'` (default) = on for+ * Windows, off for Linux (whose tray support depends on the desktop environment). Resolved by+ * `resolveBackgroundOnClose` (src/main/background-mode.ts); ignored on macOS (always hides) and+ * on the Server Edition (no window). Hand-editable: an unknown value reads as `'auto'`.+ * Settings → Behavior (Windows/Linux only). */+ runInBackgroundOnClose: BackgroundOnCloseSetting/** macOS Notch HUD (docs/notch-hud.md): a transparent always-on-top strip by the notch showing* walking agent mascots while agents work, expanding into a mini session panel. Default on;* macOS + desktop only (ignored on other platforms / Server Edition). */@@ -2434,6 +2445,8 @@ export const DEFAULT_SETTINGS: Settings = {// Confirm-before-quit default ON: sessions survive a quit anyway, but an accidental ⌘Q// tears down every window at once; the toggle is one switch away for who finds it noisy.confirmBeforeQuit: true,+ // Background mode 'auto' = on for Windows (the tray is always there), off for Linux.+ runInBackgroundOnClose: 'auto',// macOS Notch HUD default ON (guarded to darwin at runtime; a no-op elsewhere).notchHud: true,notchWidth: 168,