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(macos): restore the Dock presence only when it is gone (#1305)

enes8675dd67fb07
diff --git a/src/main/dock-presence.test.ts b/src/main/dock-presence.test.ts
new file mode 100644
index 000000000..71c644ccb
--- /dev/null
+++ b/src/main/dock-presence.test.ts
@@ -0,0 +1,65 @@
+import { describe, expect, it, vi } from 'vitest'
+import { ensureRegularDockPresence, type DockPresenceApp } from './dock-presence'
+
+function fakeApp(visible: boolean | 'throws' | 'no-dock'): DockPresenceApp & {
+ setActivationPolicy: ReturnType<typeof vi.fn>
+ show: ReturnType<typeof vi.fn>
+} {
+ const setActivationPolicy = vi.fn()
+ const show = vi.fn(() => Promise.resolve())
+ const dock =
+ visible === 'no-dock'
+ ? undefined
+ : {
+ isVisible: () => {
+ if (visible === 'throws') throw new Error('boom')
+ return visible
+ },
+ show
+ }
+ return { setActivationPolicy, dock, show }
+}
+
+describe('ensureRegularDockPresence', () => {
+ it('leaves an app that is already in the Dock alone (issue #1305: show() duplicates the tile)', () => {
+ const app = fakeApp(true)
+ expect(ensureRegularDockPresence(app, 'darwin')).toBe(false)
+ expect(app.setActivationPolicy).not.toHaveBeenCalled()
+ expect(app.show).not.toHaveBeenCalled()
+ })
+
+ it('restores the Dock presence when macOS dropped it', () => {
+ const app = fakeApp(false)
+ expect(ensureRegularDockPresence(app, 'darwin')).toBe(true)
+ expect(app.setActivationPolicy).toHaveBeenCalledWith('regular')
+ expect(app.show).toHaveBeenCalledTimes(1)
+ })
+
+ it('restores it when the visibility read fails (a failed read is not evidence of a tile)', () => {
+ const app = fakeApp('throws')
+ expect(ensureRegularDockPresence(app, 'darwin')).toBe(true)
+ expect(app.show).toHaveBeenCalledTimes(1)
+ })
+
+ it('still asserts the policy when there is no dock API', () => {
+ const app = fakeApp('no-dock')
+ expect(ensureRegularDockPresence(app, 'darwin')).toBe(true)
+ expect(app.setActivationPolicy).toHaveBeenCalledWith('regular')
+ })
+
+ it('does nothing off macOS', () => {
+ for (const platform of ['linux', 'win32'] as const) {
+ const app = fakeApp(false)
+ expect(ensureRegularDockPresence(app, platform)).toBe(false)
+ expect(app.setActivationPolicy).not.toHaveBeenCalled()
+ expect(app.show).not.toHaveBeenCalled()
+ }
+ })
+
+ it('swallows a rejected show()', async () => {
+ const app = fakeApp(false)
+ app.show.mockImplementation(() => Promise.reject(new Error('no')))
+ expect(ensureRegularDockPresence(app, 'darwin')).toBe(true)
+ await Promise.resolve()
+ })
+})
diff --git a/src/main/dock-presence.ts b/src/main/dock-presence.ts
new file mode 100644
index 000000000..76b66539a
--- /dev/null
+++ b/src/main/dock-presence.ts
@@ -0,0 +1,52 @@
+// Keeping nodeterm a REGULAR Dock app on macOS without re-registering it with the Dock.
+//
+// The Notch HUD is a `focusable:false` (non-activating) panel. If such a panel is the only window
+// ordered front, macOS can re-evaluate the app as having no regular window and drop its Dock tile
+// (the original "Dock icon disappears once the HUD opens" bug), so the app re-asserts its Dock
+// presence when the HUD is created and shown and whenever the main window is shown.
+//
+// That re-assert used to run unconditionally, on the claim that it was idempotent. It is not:
+// Electron's `app.dock.show()` calls `TransformProcessType(kProcessTransformToForegroundApplication)`
+// every time, and transforming an app that is ALREADY a foreground app can leave the Dock showing
+// it twice — the pinned tile without a running dot, plus a second tile in the "recent apps" section
+// that is the one actually running (issue #1305). Clicking the pinned tile then asks LaunchServices
+// to open the app again, which reads to the user as "it opens a new instance".
+//
+// So the re-assert now acts only when the app has really lost its Dock presence.
+// `app.dock.isVisible()` answers exactly that: Electron reports it from the current
+// `NSRunningApplication` activation policy (`== Regular`).
+
+/** The slice of Electron's `app` this needs; structural so the decision tests without Electron. */
+export interface DockPresenceApp {
+ setActivationPolicy(policy: 'regular'): void
+ dock?: {
+ isVisible(): boolean
+ show(): unknown
+ }
+}
+
+/** Returns true when it asked macOS to restore the Dock presence, false when it left it alone. */
+export function ensureRegularDockPresence(app: DockPresenceApp, platform: NodeJS.Platform): boolean {
+ if (platform !== 'darwin') return false
+ const dock = app.dock
+ // No dock API (older Electron): keep the old behaviour of asserting the policy once.
+ let visible = false
+ try {
+ visible = dock?.isVisible() === true
+ } catch {
+ // A read that fails is no evidence the tile is there; fall through and restore it.
+ }
+ if (visible) return false
+ try {
+ app.setActivationPolicy('regular')
+ } catch {
+ /* older Electron / transient — ignore */
+ }
+ // `dock.show()` returns a Promise in recent Electron; swallow it either way.
+ try {
+ void Promise.resolve(dock?.show()).catch(() => {})
+ } catch {
+ /* ignore */
+ }
+ return true
+}
diff --git a/src/main/notch-hud.ts b/src/main/notch-hud.ts
index c3ee1fe38..124ffabec 100644
--- a/src/main/notch-hud.ts
+++ b/src/main/notch-hud.ts
@@ -23,6 +23,7 @@ import {
import type { NormalizedAgentEvent } from '../shared/agents/normalize'
import { createHudModel, type HudModel, type HudContextUpdate } from './notch-hud-model'
import { hudGeometry, hudPlacement, type HudGeometry } from './notch-hud-geometry'
+import { ensureRegularDockPresence } from './dock-presence'
import {
sanitizeNotchAlign,
sanitizeNotchOffsetY,
@@ -46,23 +47,12 @@ const SWEEP_MS = 60 * 1000
* that is orderFront-ed on screen (e.g. it shows before the main window has finished loading, or
* while the main window is hidden by hide-on-close), macOS re-evaluates the app as having no
* regular window and drops its Dock tile — the "Dock icon disappears once the HUD opens" bug.
- * Asserting `regular` + `dock.show()` is idempotent and cheap, and guarantees the HUD never
- * demotes the app's Dock presence. No-op off macOS.
+ * It restores the Dock presence only when it is actually gone: `dock.show()` is NOT idempotent,
+ * and calling it on an app already in the Dock can show the app twice (issue #1305; see
+ * ./dock-presence.ts). No-op off macOS.
*/
export function assertRegularDockPresence(): void {
- if (process.platform !== 'darwin') return
- try {
- // Idempotent: re-asserting 'regular' when already regular is a no-op.
- app.setActivationPolicy('regular')
- } catch {
- /* older Electron / transient — ignore */
- }
- // `dock.show()` returns a Promise in recent Electron; swallow it either way.
- try {
- void Promise.resolve(app.dock?.show()).catch(() => {})
- } catch {
- /* ignore */
- }
+ ensureRegularDockPresence(app, process.platform)
}
// ---- Singleton (mirror main-window.ts) -----------------------------------------------------
diff --git a/src/main/window-raise.guard.test.ts b/src/main/window-raise.guard.test.ts
index 7b25c5361..5ee5b67e6 100644
--- a/src/main/window-raise.guard.test.ts
+++ b/src/main/window-raise.guard.test.ts
@@ -79,12 +79,21 @@ const ALLOWED = new Map<string, { calls: number; why: string }>([
[
'notch-hud.ts',
{
- calls: 5,
+ calls: 4,
+ why:
+ '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'
+ }
+ ],
+ [
+ 'dock-presence.ts',
+ {
+ calls: 1,
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"
+ 'making the app look like an accessory), and only when the app has actually lost its ' +
+ 'Dock tile (issue #1305)'
}
],
[