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.

feat(kanban): handoff pings for a card's assignee

reviewe81f612cceaf
diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsx
index cc6bdfc72..7f72fbe6b 100644
--- a/src/renderer/canvas/Canvas.tsx
+++ b/src/renderer/canvas/Canvas.tsx
@@ -200,6 +200,8 @@ 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 { loadIdentity } from '../state/presence'
import { runBoardKey } from '../lib/boardKeys'
import { readCanvasLocked, writeCanvasLocked } from '../lib/canvasLock'
import {
@@ -12778,6 +12780,25 @@ export function Canvas() {
for (const { nodeId: nid, event } of boardLogEvents(prev, next, cardTitle)) {
useBoardLog.getState().append(api, pid, { kind: 'event', nodeId: nid, event })
}
+ // Handoff pings (lib/handoffPings): an agent filing a card ASSIGNED TO THIS USER into a
+ // handoff column (a done column, or a started one past the first) tells them — through the
+ // existing notification consent, background-only rule and per-node cooldown. Arming the
+ // fold lets the Stop hook that follows seconds later not notify the same moment twice.
+ const notifyPrefs = useSettings.getState().settings
+ if (!document.hasFocus() && notifyPrefs.notifyOnClaudeDone && notifyPrefs.notifyConsentAsked) {
+ const me = loadIdentity()?.name ?? 'you'
+ const now = Date.now()
+ for (const h of handoffsFor(prev, next, me)) {
+ if (now - (notifyCooldownRef.current[h.nodeId] ?? 0) < 5000) continue
+ notifyCooldownRef.current[h.nodeId] = now
+ noteHandoff(h.nodeId, now)
+ void window.nodeTerminal.notify({
+ title: `${ctlProject?.name ?? 'Board'} — handed to you: ${cardTitle(h.nodeId) || 'a card'}`,
+ body: `Moved to ${h.columnTitle}.`,
+ nodeId: h.nodeId
+ })
+ }
+ }
const where = columnId
? next.columns.find((c) => c.id === columnId)?.title ?? columnId
: 'Ungrouped'
@@ -13491,6 +13512,9 @@ export function Canvas() {
// Everything from here down is an INTERRUPT, and this is where a quiet alert stops. The
// unread dot and its ack above are deliberately on the other side of this line.
if (opts?.quiet) return
+ // An agent that just filed its card into a handoff column was already announced to the
+ // assignee (the `assign` verb's handoff ping); its turn end seconds later is the same moment.
+ if (sound === 'done' && suppressDoneAfterHandoff(e.nodeId, Date.now())) return
// Sound first: it is the one alert that also fires while you're in the app but looking at
// another node — the case OS notifications deliberately skip.
const snd = useSettings.getState().settings
diff --git a/src/renderer/lib/handoffPings.test.ts b/src/renderer/lib/handoffPings.test.ts
new file mode 100644
index 000000000..44fe4052e
--- /dev/null
+++ b/src/renderer/lib/handoffPings.test.ts
@@ -0,0 +1,118 @@
+import { readFileSync } from 'fs'
+import { beforeEach, describe, expect, it } from 'vitest'
+import type { ProjectKanban } from '@shared/types'
+import {
+ HANDOFF_FOLD_MS,
+ handoffsFor,
+ noteHandoff,
+ resetHandoffsForTests,
+ suppressDoneAfterHandoff
+} from './handoffPings'
+
+const ME = { name: 'enes', color: '#0a84ff' }
+const SAM = { name: 'sam', color: '#ff453a' }
+
+const board = (assignments: ProjectKanban['assignments'], meta: ProjectKanban['meta'] = []): ProjectKanban => ({
+ columns: [
+ { id: 'todo', title: 'To Do', color: '#0a84ff', category: 'unstarted' },
+ { id: 'doing', title: 'In Progress', color: '#ffd60a', category: 'started' },
+ { id: 'review', title: 'Review', color: '#bf5af2', category: 'started' },
+ { id: 'done', title: 'Done', color: '#32d74b', category: 'done' },
+ { id: 'wontfix', title: "Won't fix", color: '#8e8e93', category: 'closed' },
+ { id: 'plain', title: 'Plain', color: '#fff' }
+ ],
+ assignments,
+ meta
+})
+
+const mine = [{ nodeId: 'n', assignees: [ME] }]
+const from = (col: string) => board([{ nodeId: 'n', columnId: col }], mine)
+
+describe('handoffsFor — which moves are a handoff to ME', () => {
+ it('entering a started column past the FIRST one (review) is a handoff', () => {
+ expect(handoffsFor(from('doing'), from('review'), 'enes')).toEqual([
+ { nodeId: 'n', columnId: 'review', columnTitle: 'Review', category: 'started' }
+ ])
+ })
+
+ it('entering a done column is a handoff', () => {
+ expect(handoffsFor(from('review'), from('done'), 'enes')).toEqual([
+ { nodeId: 'n', columnId: 'done', columnTitle: 'Done', category: 'done' }
+ ])
+ })
+
+ it('routine moves are not: into the FIRST started column, back to not-started, closed, uncategorized', () => {
+ expect(handoffsFor(from('todo'), from('doing'), 'enes')).toEqual([])
+ expect(handoffsFor(from('doing'), from('todo'), 'enes')).toEqual([])
+ expect(handoffsFor(from('doing'), from('wontfix'), 'enes')).toEqual([])
+ expect(handoffsFor(from('doing'), from('plain'), 'enes')).toEqual([])
+ })
+
+ it('a card filed straight from Ungrouped into Done counts', () => {
+ const before = board([], mine)
+ expect(handoffsFor(before, from('done'), 'enes')).toHaveLength(1)
+ })
+
+ it('a reorder within the column is not a move', () => {
+ const a = board([{ nodeId: 'x', columnId: 'done' }, { nodeId: 'n', columnId: 'done' }], mine)
+ const b = board([{ nodeId: 'n', columnId: 'done' }, { nodeId: 'x', columnId: 'done' }], mine)
+ expect(handoffsFor(a, b, 'enes')).toEqual([])
+ })
+
+ it('only for cards assigned to ME — unassigned or someone else’s cards never ping here', () => {
+ expect(handoffsFor(board([{ nodeId: 'n', columnId: 'doing' }]), board([{ nodeId: 'n', columnId: 'done' }]), 'enes')).toEqual([])
+ const sams = [{ nodeId: 'n', assignees: [SAM] }]
+ expect(
+ handoffsFor(board([{ nodeId: 'n', columnId: 'doing' }], sams), board([{ nodeId: 'n', columnId: 'done' }], sams), 'enes')
+ ).toEqual([])
+ })
+
+ it('a board with no categories never pings (it has not said what a handoff is)', () => {
+ const plain = (col: string): ProjectKanban => ({
+ columns: [{ id: 'a', title: 'A', color: '#fff' }, { id: 'b', title: 'B', color: '#fff' }],
+ assignments: [{ nodeId: 'n', columnId: col }],
+ meta: mine
+ })
+ expect(handoffsFor(plain('a'), plain('b'), 'enes')).toEqual([])
+ })
+})
+
+describe('folding the turn-end notification into a handoff ping', () => {
+ beforeEach(() => resetHandoffsForTests())
+
+ it('a "finished" notification right after a handoff ping for the same node is folded', () => {
+ noteHandoff('n', 1000)
+ expect(suppressDoneAfterHandoff('n', 1000 + HANDOFF_FOLD_MS - 1)).toBe(true)
+ })
+
+ it('only for that node, and only inside the window', () => {
+ noteHandoff('n', 1000)
+ expect(suppressDoneAfterHandoff('other', 1001)).toBe(false)
+ expect(suppressDoneAfterHandoff('n', 1000 + HANDOFF_FOLD_MS + 1)).toBe(false)
+ })
+
+ it('folds ONE notification per handoff — a later turn end still notifies', () => {
+ noteHandoff('n', 1000)
+ expect(suppressDoneAfterHandoff('n', 2000)).toBe(true)
+ expect(suppressDoneAfterHandoff('n', 3000)).toBe(false)
+ })
+})
+
+// Canvas is too large to mount here; these pin that the two halves are actually wired — a pure
+// module nobody calls would pass every test above and ship inert.
+describe('Canvas wiring (source pins)', () => {
+ const source = (): string => readFileSync('src/renderer/canvas/Canvas.tsx', 'utf8')
+
+ it('the assign verb pings the handoffs of the move it just made, under the existing consent', () => {
+ const src = source()
+ const assign = src.slice(src.indexOf("case 'assign': {"), src.indexOf("case 'assign': {") + 6000)
+ expect(assign).toContain('handoffsFor(prev, next, me)')
+ expect(assign).toContain('noteHandoff(h.nodeId, now)')
+ expect(assign).toContain('notifyPrefs.notifyOnClaudeDone && notifyPrefs.notifyConsentAsked')
+ expect(assign).toContain('!document.hasFocus()')
+ })
+
+ 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")
+ })
+})
diff --git a/src/renderer/lib/handoffPings.ts b/src/renderer/lib/handoffPings.ts
new file mode 100644
index 000000000..eae75dbee
--- /dev/null
+++ b/src/renderer/lib/handoffPings.ts
@@ -0,0 +1,71 @@
+/**
+ * Handoff pings: tell a card's ASSIGNEE when the work is handed to them — and at no other moment.
+ *
+ * A handoff is a card assigned to this user (by presence name) ENTERING a column that means "your
+ * turn": a `done` column, or a `started` column other than the board's first one (Review / QA after
+ * In Progress). Everything else is a routine move and pings nobody: into the first started column,
+ * back to not-started, into `closed` (won't do), into an uncategorized column — a board with no
+ * categories has not said what a handoff is, so it never pings. "Needs you" is not decided here:
+ * the existing agent-status path already notifies it for every agent node, and a second
+ * notification for the same fact would be noise.
+ *
+ * Double-notify with the turn-end ("finished") notification: an agent that files its card into
+ * 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.
+ *
+ * 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.
+ */
+import type { KanbanColumnCategory, ProjectKanban } from '@shared/types'
+import { columnCategory } from '@shared/kanban-category'
+import { cardMeta } from './kanban'
+
+export const HANDOFF_FOLD_MS = 2 * 60_000
+
+export interface Handoff {
+ nodeId: string
+ columnId: string
+ columnTitle: string
+ category: Extract<KanbanColumnCategory, 'started' | 'done'>
+}
+
+/** The handoffs a board change makes to `me` (see the module note). Pure. */
+export function handoffsFor(prev: ProjectKanban, next: ProjectKanban, me: string): Handoff[] {
+ const firstStarted = next.columns.find((c) => columnCategory(c) === 'started')?.id
+ const before = new Map(prev.assignments.map((a) => [a.nodeId, a.columnId]))
+ const out: Handoff[] = []
+ for (const a of next.assignments) {
+ if (!a || before.get(a.nodeId) === a.columnId) continue
+ const column = next.columns.find((c) => c.id === a.columnId)
+ const category = columnCategory(column)
+ const handoff = category === 'done' || (category === 'started' && a.columnId !== firstStarted)
+ if (!column || !handoff) continue
+ const assignees = cardMeta(next, a.nodeId)?.assignees ?? []
+ if (!assignees.some((p) => p?.name === me)) continue
+ out.push({ nodeId: a.nodeId, columnId: a.columnId, columnTitle: column.title, category: category as Handoff['category'] })
+ }
+ return out
+}
+
+const pinged = new Map<string, number>()
+
+/** A handoff ping went out for `nodeId` at `now`: arm the one-shot fold. */
+export function noteHandoff(nodeId: string, now: number): void {
+ pinged.set(nodeId, now)
+}
+
+/** Should the turn-end notification for `nodeId` be folded into a handoff ping just sent?
+ * Consumes the fold, so it swallows at most one notification per handoff. */
+export function suppressDoneAfterHandoff(nodeId: string, now: number): boolean {
+ const at = pinged.get(nodeId)
+ if (at === undefined) return false
+ pinged.delete(nodeId)
+ return now - at <= HANDOFF_FOLD_MS
+}
+
+/** Tests only. */
+export function resetHandoffsForTests(): void {
+ pinged.clear()
+}