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(kanban): handoff pings for a card's assignee
reviewe81f612cceaf
diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsxindex 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().settingsdiff --git a/src/renderer/lib/handoffPings.test.ts b/src/renderer/lib/handoffPings.test.tsnew file mode 100644index 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.tsnew file mode 100644index 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()+}