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(kanban): a window refocus drops the handoff-ping fold

reviewa726c2eedf30
diff --git a/CLAUDE.md b/CLAUDE.md
index 394425bea..2bc4f60aa 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -5815,7 +5815,9 @@ the Settings section and ShortcutsPanel start disagreeing about what a chord mea
the board's first — never on routine moves, and not for needs-you (the existing agent-status
alert already covers every agent node). Same consent, background-only rule and per-node
cooldown as the turn-end alert, and a handoff ping arms a one-shot FOLD so the Stop hook that
- follows seconds later is not a second notification for the same moment. v1 is agent-driven
+ follows seconds later is not a second notification for the same moment. The fold lasts only
+ while the user is away: a window focus in between drops it (`installHandoffFocusReset`), or the
+ next chime — for a turn the user sat and watched — was swallowed. v1 is agent-driven
moves only: a teammate's move arriving by git, or the phone's relay move, pings nobody.
**Phone** (nodeterm-ios): must at least not break on `category`, `rank` or `views` (extra JSON
keys its board decoder ignores). The relay-served move now lands at the top with a rank, while
diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsx
index 2f06b146d..6ac096b9c 100644
--- a/src/renderer/canvas/Canvas.tsx
+++ b/src/renderer/canvas/Canvas.tsx
@@ -200,7 +200,7 @@ import { containerOrigin, snapPointInRootSpace } from '../lib/gridSnap'
import { zoomFromPct } from '../lib/zoomPresets'
import { CANVAS_MAX_ZOOM, CANVAS_MIN_ZOOM } from './zoom-limits'
import { isSpaceRelease, spacePanKeydown } from '../lib/spacePan'
-import { handoffsFor, noteHandoff, suppressDoneAfterHandoff } from '../lib/handoffPings'
+import { handoffsFor, installHandoffFocusReset, noteHandoff, suppressDoneAfterHandoff } from '../lib/handoffPings'
import { loadIdentity } from '../state/presence'
import { runBoardKey } from '../lib/boardKeys'
import { readCanvasLocked, writeCanvasLocked } from '../lib/canvasLock'
@@ -13948,6 +13948,9 @@ export function Canvas() {
}, [])
const notifyCooldownRef = useRef<Record<string, number>>({})
+ // A handoff ping folds the "finished" alert that follows it (lib/handoffPings) only while the user
+ // is still away: a window focus in between drops the fold, so the next turn end chimes as always.
+ useEffect(() => installHandoffFocusReset(window), [])
// Sound effects have their OWN cooldown: they fire whether or not the window is focused, so they
// can't share the notification one (which only ticks in the background).
const sfxCooldownRef = useRef<Record<string, number>>({})
diff --git a/src/renderer/lib/handoffPings.test.ts b/src/renderer/lib/handoffPings.test.ts
index 93b63c852..8ea346f5d 100644
--- a/src/renderer/lib/handoffPings.test.ts
+++ b/src/renderer/lib/handoffPings.test.ts
@@ -4,6 +4,7 @@ import type { ProjectKanban } from '@shared/types'
import {
HANDOFF_FOLD_MS,
handoffsFor,
+ installHandoffFocusReset,
noteHandoff,
resetHandoffsForTests,
suppressDoneAfterHandoff
@@ -96,6 +97,24 @@ describe('folding the turn-end notification into a handoff ping', () => {
expect(suppressDoneAfterHandoff('n', 2000)).toBe(true)
expect(suppressDoneAfterHandoff('n', 3000)).toBe(false)
})
+
+ it('a refocus in between drops the fold: the user is back, the next turn end chimes', () => {
+ const target = new EventTarget()
+ const stop = installHandoffFocusReset(target)
+ noteHandoff('n', 1000)
+ noteHandoff('m', 1000)
+ target.dispatchEvent(new Event('focus'))
+ expect(suppressDoneAfterHandoff('n', 2000)).toBe(false)
+ expect(suppressDoneAfterHandoff('m', 2000)).toBe(false)
+ // A ping armed AFTER the refocus still folds its own Stop.
+ noteHandoff('n', 3000)
+ expect(suppressDoneAfterHandoff('n', 4000)).toBe(true)
+ // …and once uninstalled, a focus no longer touches the folds.
+ stop()
+ noteHandoff('n', 5000)
+ target.dispatchEvent(new Event('focus'))
+ expect(suppressDoneAfterHandoff('n', 6000)).toBe(true)
+ })
})
// Canvas is too large to mount here; these pin that the two halves are actually wired — a pure
@@ -115,6 +134,10 @@ describe('Canvas wiring (source pins)', () => {
it('the turn-end alert folds into a handoff ping just sent (and only the done sound)', () => {
expect(source()).toContain("if (sound === 'done' && suppressDoneAfterHandoff(e.nodeId, Date.now())) return")
})
+
+ it('the window focus reset is installed for the canvas lifetime', () => {
+ expect(source()).toMatch(/useEffect\(\(\) => installHandoffFocusReset\(window\), \[\]\)/)
+ })
})
// The assign verb runs handoffsFor AFTER its board write; a throw there left the verb without a
diff --git a/src/renderer/lib/handoffPings.ts b/src/renderer/lib/handoffPings.ts
index 51ad6a69b..6692817e5 100644
--- a/src/renderer/lib/handoffPings.ts
+++ b/src/renderer/lib/handoffPings.ts
@@ -13,7 +13,10 @@
* Done does so INSIDE its turn, and the turn's Stop hook follows seconds later — two notifications
* for one event. So a handoff ping arms a one-shot fold for its node: the next "finished"
* notification for that node within `HANDOFF_FOLD_MS` is not sent (the unread dot still is — only
- * the interrupt is folded). A later turn end notifies as always.
+ * the interrupt is folded). A later turn end notifies as always, and so does the next one after the
+ * window comes back to the foreground (`installHandoffFocusReset`): the fold stands for "the user is
+ * away and was just told", and a refocus ends that — otherwise the next chime, maybe for a turn that
+ * had nothing to do with the handoff, was silently swallowed while the user sat watching.
*
* Consent and delivery are the existing path's: `notifyOnClaudeDone` + the one-time consent prompt,
* an OS notification only while the window is in the background, the per-node cooldown.
@@ -64,6 +67,14 @@ export function suppressDoneAfterHandoff(nodeId: string, now: number): boolean {
return now - at <= HANDOFF_FOLD_MS
}
+/** Drops every armed fold when the window gains focus; returns the teardown. The ping is only
+ * sent while the window is in the background, so a focus after it means the user is back. */
+export function installHandoffFocusReset(target: Pick<EventTarget, 'addEventListener' | 'removeEventListener'>): () => void {
+ const drop = (): void => pinged.clear()
+ target.addEventListener('focus', drop)
+ return () => target.removeEventListener('focus', drop)
+}
+
/** Tests only. */
export function resetHandoffsForTests(): void {
pinged.clear()