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(keybindings): add "Go to next agent needing you" command
Brandon Bridgesff4cff686c3d
diff --git a/CLAUDE.md b/CLAUDE.mdindex afc51301f..734d31dba 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -7523,6 +7523,18 @@ the Settings section and ShortcutsPanel start disagreeing about what a chord meawhile subscribed. It cannot double-fire on desktop (only `buildStubApi` reaches it; the relaytab takes `onMarkdownToggle` from the local preload). macOS Chrome reserves ⌘M for minimize,so the default chord only reaches a Mac browser tab after a remap (docs/SERVER.md).+ - **A status-reading command builds its answer PER KEYPRESS, never from a subscription.**+ `node.nextNeedingYou` (ships unbound, mirrored in ⌘K as "Go to next agent needing you"; audit+ roadmap #19 — one chord instead of 3-5 sidebar clicks) builds `needsYouQueue`+ (`lib/nextNeedingYou.ts`) from `useProjects`/`useAgentStatus` `getState()` on each press:+ the status-mode sidebar's "Need attention" rows (`buildStatusList` over the non-closed+ projects), re-sorted OLDEST wait first, minus rows `nodeTravel` reports `blocked`. Canvas must+ never subscribe to `statusById` for it (every flip would re-render the canvas). Travel is+ `travelToNodeRef` (keeps the hosted-team reopen guard), the cycle cursor is a ref (memory+ only), the node the user is already in is skipped when another waits, and an empty queue is+ CLAIMED with an info notice — xterm has already withheld the chord, so declining would only+ make a deliberately bound chord silent. Its handler entry is pinned by+ `keybindings-handler-parity.test.ts`.- **ShortcutsPanel is DERIVED from the registry, never a hand-written list.**`buildShortcutSections` iterates `COMMAND_DEFINITIONS` — one section per `CommandGroup` inregistry source order, the label from `def.title`, and EVERY one of the command's EFFECTIVEdiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 9f6c9532d..c7745fa71 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -998,6 +998,13 @@ make it show up; a command with no effective binding is omitted rather than listreplaced hand-listed 24 ids against a 45-command registry and had drifted four live chords behind— if you find yourself typing a command id into that file, that is the bug reappearing.+**A command that reads agent status reads it per keypress, never by subscription.** Canvas must not+subscribe to `useAgentStatus`'s `byId` (every working/waiting flip would re-render the whole+canvas): `node.nextNeedingYou` builds its queue on demand (`lib/nextNeedingYou.ts`, over+`buildStatusList`) from `getState()` and travels with `travelToNode`, keeping its cycle cursor in a+ref. A new ships-unbound command also needs a `'<id>':` handler entry that+`keybindings-handler-parity.test.ts` can see — the handlers map is `Partial`, so nothing else will.+**Comments explain WHY, and name the failure they prevent.** The codebase is deliberately dense withreasoning. A comment that restates the code is noise; one that says "do not simplify this back,here is what broke" is the point.diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsxindex 869247831..5be74c3b3 100644--- a/src/renderer/canvas/Canvas.tsx+++ b/src/renderer/canvas/Canvas.tsx@@ -300,6 +300,7 @@ import { conductorPrompt } from '../lib/spawnTeamPrompt'import { NotifyConsentDialog } from '../components/NotifyConsentDialog'import { SessionsSidebar } from '../components/SessionsSidebar'import type { SessionNodeInput } from '../lib/sessionList'+import { needsYouQueue, nextNeedingYou } from '../lib/nextNeedingYou'import { liveProjectJumpTarget, projectJumpDigit } from '../lib/projectJump'import {liveZoomShortcutAction,@@ -10492,6 +10493,51 @@ export function Canvas() {// inside the callback decides whether an observation is worth acting on.}, [sessionsPinned, sessionsDismissed, explorerOpen, explorer.pinned, fitMaximizedToUsableArea])+ /**+ * "Go to next agent needing you" (`node.nextNeedingYou`, ⌘K; audit roadmap #19 / qol-2): one+ * chord instead of the 3-5 sidebar clicks a waiting agent in another project took. The queue is+ * built ON DEMAND from `getState()` reads — Canvas never subscribes to `statusById` (every+ * working/waiting flip would re-render the whole canvas; see StatusAwareMiniMap). The cycle+ * cursor is memory only: a restart starts again at the oldest wait, which is the right answer.+ * Travel is `travelToNodeRef` (declared above this point; the callback itself is defined much+ * further down) so a closed-project hop keeps travelToNode's hosted-team reopen guard.+ */+ const needsYouCursorRef = useRef<string | null>(null)+ const needsYouQueueNow = useCallback((): string[] => {+ const { projects, activeProjectId: active } = useProjects.getState()+ // The live canvas only when it is the ACTIVE project's (the epoch pair): mid-switch nodesRef+ // still holds the outgoing project's nodes. Live adds a just-created node the store has not+ // committed yet; without it the persisted nodes are used, exactly as the closed sidebar does.+ const live: SessionNodeInput[] | null =+ nodesProjectIdRef.current === active+ ? nodesRef.current+ .filter((n) => (n.type ?? 'terminal') === 'terminal')+ .map((n) => ({+ id: n.id,+ kind: 'terminal' as const,+ title: n.data.title ?? n.id,+ color: n.data.color ?? '#888'+ }))+ : null+ return needsYouQueue(projects, live, active, useAgentStatus.getState().byId)+ }, [nodesRef, nodesProjectIdRef])+ const goToNextNeedingYou = useCallback((): void => {+ const target = nextNeedingYou(+ needsYouQueueNow(),+ needsYouCursorRef.current,+ useAgentStatus.getState().activeId+ )+ if (!target) {+ // Claimed even when empty: from a focused terminal xterm has already withheld the chord+ // (terminalChordBubbles), so declining would not hand it back — it would only make a chord+ // the user bound on purpose do nothing, silently.+ setNotice({ kind: 'info', text: 'No agent is waiting for you.' })+ return+ }+ needsYouCursorRef.current = target+ travelToNodeRef.current(target)+ }, [needsYouQueueNow])+/*** Zone snap (issue #394 v1): place `nodeId` (or the placement target, for the keyboard chords)* into a zone of the visible canvas. Same declines as maximize; no toggle state — the node has@@ -10610,6 +10656,7 @@ export function Canvas() {'node.focusRight': () => moveNodeFocus('right'),'node.focusUp': () => moveNodeFocus('up'),'node.focusDown': () => moveNodeFocus('down'),+ 'node.nextNeedingYou': () => { goToNextNeedingYou(); return true },'node.maximize': toggleMaximizeCommand,// Every zone, halves through quarters, from the one table (issue #1169)....Object.fromEntries(@@ -18884,6 +18931,22 @@ export function Canvas() {icon: <IconFit />,run: toggleFocusMode},+ // The ⌘K twin of `node.nextNeedingYou` (same function, so they share the cycle cursor).+ // Hidden when nothing waits, like Tidy canvas below: it could only report "no agent".+ ...((): Command[] => {+ const waiting = needsYouQueueNow().length+ return waiting > 0+ ? [+ {+ id: 'next-needing-you',+ label: 'Go to next agent needing you',+ hint: `${waiting} waiting · attention blocked permission`,+ icon: <IconJump />,+ run: goToNextNeedingYou+ }+ ]+ : []+ })(),{ id: 'fit', label: 'Fit view', icon: <IconFit />, run: fitAll },// Hidden below 2 top-level nodes — see arrangeAllNodes....(hasArrangeableNodes()@@ -19112,6 +19175,8 @@ export function Canvas() {saveCanvasLayout,restoreCanvasLayout,toggleFocusMode,+ needsYouQueueNow,+ goToNextNeedingYou,hostedBookmarks,copyHostedInviteCode,forgetHostedTeam,diff --git a/src/renderer/canvas/keybindings-handler-parity.test.ts b/src/renderer/canvas/keybindings-handler-parity.test.tsindex 28ad0cc1b..7aa765325 100644--- a/src/renderer/canvas/keybindings-handler-parity.test.ts+++ b/src/renderer/canvas/keybindings-handler-parity.test.ts@@ -16,6 +16,9 @@ const canvasSource = readFileSync(join(__dirname, 'Canvas.tsx'), 'utf8')describe('Canvas keybinding handler parity', () => {const createIds = COMMAND_DEFINITIONS.map((d) => d.id).filter((id) => id.startsWith('node.new'))+ // Ships unbound like the creates, so it has the same failure mode: a remappable row whose chord+ // does nothing. `node.newSticky` etc. are matched by the prefix; this one is named outright.+ const checkedIds = [...createIds, 'node.nextNeedingYou']it('finds the create commands to check (guards against an empty sweep)', () => {expect(createIds.length).toBeGreaterThanOrEqual(13)@@ -23,7 +26,7 @@ describe('Canvas keybinding handler parity', () => {// `includes` + a message rather than `toContain`: a miss on a 12k-line file would otherwise// print the whole source as the diff and bury the one fact the failure carries.- it.each(createIds)('%s has a handler entry in Canvas.tsx', (id) => {+ it.each(checkedIds)('%s has a handler entry in Canvas.tsx', (id) => {expect(canvasSource.includes(`'${id}':`),`Canvas.tsx has no '${id}' handler — the handlers map is Partial, so nothing else catches this`diff --git a/src/renderer/lib/nextNeedingYou.test.ts b/src/renderer/lib/nextNeedingYou.test.tsnew file mode 100644index 000000000..578ce68da--- /dev/null+++ b/src/renderer/lib/nextNeedingYou.test.ts@@ -0,0 +1,87 @@+import { describe, it, expect } from 'vitest'+import { needsYouQueue, nextNeedingYou, type NeedsYouProject } from './nextNeedingYou'+import type { AgentNodeStatus } from '../state/agentStatus'++const node = (id: string, title = id) => ({ id, kind: 'terminal' as const, title, color: '#888' })++const projects = (): NeedsYouProject[] => [+ { id: 'p1', name: 'Alpha', color: '#111', nodes: [node('a1'), node('a2'), node('a3')] },+ { id: 'p2', name: 'Beta', color: '#222', nodes: [node('b1'), node('b2')] },+ { id: 'p3', name: 'Gamma', color: '#333', nodes: [node('c1')] }+]++const st = (state: AgentNodeStatus['state'], at?: number, unread = false): AgentNodeStatus => ({+ unread,+ state,+ lastEventAt: at+})++describe('needsYouQueue', () => {+ it('lists waiting AND blocked agents across projects, oldest wait first', () => {+ const status: Record<string, AgentNodeStatus> = {+ a1: st('waiting', 300),+ a2: st('working', 50),+ b1: st('blocked', 100),+ b2: st('done', 10, true),+ c1: st('waiting', 200)+ }+ // Working, done and unread rows are not "needing you"; the active project is irrelevant to order.+ expect(needsYouQueue(projects(), null, 'p1', status)).toEqual(['b1', 'c1', 'a1'])+ expect(needsYouQueue(projects(), null, 'p3', status)).toEqual(['b1', 'c1', 'a1'])+ })++ it('breaks clock ties by project store order, then title, deterministically', () => {+ const ps = projects()+ ps[0].nodes = [node('a1', 'zeta'), node('a2', 'Alpha')]+ const status = { a1: st('waiting', 100), a2: st('waiting', 100), b1: st('waiting', 100) }+ expect(needsYouQueue(ps, null, 'p1', status)).toEqual(['a2', 'a1', 'b1'])+ })++ it('sorts a row with no clock last instead of first', () => {+ const status = { a1: st('waiting'), b1: st('waiting', 999) }+ expect(needsYouQueue(projects(), null, 'p1', status)).toEqual(['b1', 'a1'])+ })++ it('matches the sidebar: closed projects are out, an unavailable one cannot be travelled to', () => {+ const ps = projects()+ ps[1].closed = true+ ps[2].unavailable = true+ const status = { a1: st('waiting', 3), b1: st('waiting', 1), c1: st('waiting', 2) }+ expect(needsYouQueue(ps, null, 'p1', status)).toEqual(['a1'])+ })++ it('counts a live active-project node that is not committed to the store yet', () => {+ const live = [...projects()[0].nodes, node('fresh')]+ const status = { fresh: st('blocked', 5), b1: st('waiting', 9) }+ expect(needsYouQueue(projects(), live, 'p1', status)).toEqual(['fresh', 'b1'])+ })++ it('is empty when nothing needs the user', () => {+ expect(needsYouQueue(projects(), null, 'p1', { a1: st('working', 1) })).toEqual([])+ })+})++describe('nextNeedingYou', () => {+ const q = ['x', 'y', 'z']++ it('starts at the oldest, then walks the queue and wraps', () => {+ expect(nextNeedingYou(q, null, null)).toBe('x')+ expect(nextNeedingYou(q, 'x', null)).toBe('y')+ expect(nextNeedingYou(q, 'y', null)).toBe('z')+ expect(nextNeedingYou(q, 'z', null)).toBe('x')+ })++ it('restarts at the oldest still waiting when the last stop was answered', () => {+ expect(nextNeedingYou(['y', 'z'], 'x', null)).toBe('y')+ })++ it('skips the node the user is already in, unless it is the only one', () => {+ expect(nextNeedingYou(q, null, 'x')).toBe('y')+ expect(nextNeedingYou(q, 'y', 'z')).toBe('x')+ expect(nextNeedingYou(['x'], null, 'x')).toBe('x')+ })++ it('is null on an empty queue', () => {+ expect(nextNeedingYou([], 'x', 'x')).toBeNull()+ })+})diff --git a/src/renderer/lib/nextNeedingYou.ts b/src/renderer/lib/nextNeedingYou.tsnew file mode 100644index 000000000..c0fc8ca7b--- /dev/null+++ b/src/renderer/lib/nextNeedingYou.ts@@ -0,0 +1,76 @@+// "Go to next agent needing you" (`node.nextNeedingYou`, audit roadmap #19 / qol-2): one chord+// instead of the 3-5 clicks it took to reach a waiting agent in another project (open the sidebar,+// find the project, find the row, click; more when the project is collapsed).+//+// Pure, so the ordering and the cycle are unit-tested here (vitest runs in the node environment,+// no jsdom). Canvas calls this ON DEMAND, once per keypress or palette open, reading the stores+// with `getState()` — it must NEVER subscribe to `statusById` for this: every working/waiting flip+// would re-render the whole canvas (see `StatusAwareMiniMap`'s header in Canvas.tsx).++import type { AgentNodeStatus } from '../state/agentStatus'+import { buildStatusList, type ProjectInput, type SessionNodeInput } from './sessionList'+import { nodeTravel, type TravelProject } from './presenceTravel'++export type NeedsYouProject = ProjectInput & TravelProject++/**+ * The node ids that need the user (`waiting` / `blocked` — the sidebar's "Need attention" section),+ * across projects, OLDEST first: the agent that has been waiting longest is the one to answer next.+ *+ * Membership is exactly the status-mode sidebar's (`buildStatusList` over the non-closed projects,+ * the same filter `SessionsSidebar` applies), so the command never disagrees with the list the user+ * can see. Order is a re-sort of a COPY: the sidebar's own section stays newest-first.+ * - key: `statusUpdatedAt` ascending (the transition clock); an absent stamp sorts last, then+ * project store order, then title, then id — a deterministic order so the cycle is stable.+ * - a row whose project `nodeTravel` reports `blocked` (unreadable `.nodeterm` folder) is dropped:+ * `travelToNode` silently refuses it, and leaving it in would stall the cycle on a dead stop.+ */+export function needsYouQueue(+ projects: readonly NeedsYouProject[],+ liveActiveNodes: SessionNodeInput[] | null,+ activeProjectId: string,+ statusById: Record<string, AgentNodeStatus>+): string[] {+ const open = projects.filter((p) => !p.closed)+ const pidx = new Map(open.map((p, i) => [p.id, i]))+ const attention =+ buildStatusList(open, liveActiveNodes, activeProjectId, statusById, '').find(+ (s) => s.kind === 'attention'+ )?.rows ?? []+ return attention+ .filter((r) => nodeTravel(projects, activeProjectId, r.id).kind !== 'blocked')+ .sort((a, b) => {+ const at = a.statusUpdatedAt ?? Number.POSITIVE_INFINITY+ const bt = b.statusUpdatedAt ?? Number.POSITIVE_INFINITY+ if (at !== bt) return at < bt ? -1 : 1+ const ap = pidx.get(a.projectId ?? '') ?? Number.MAX_SAFE_INTEGER+ const bp = pidx.get(b.projectId ?? '') ?? Number.MAX_SAFE_INTEGER+ if (ap !== bp) return ap - bp+ const byTitle = a.title.toLowerCase().localeCompare(b.title.toLowerCase())+ if (byTitle !== 0) return byTitle+ return a.id < b.id ? -1 : a.id > b.id ? 1 : 0+ })+ .map((r) => r.id)+}++/**+ * The next stop in the cycle.+ * - `cursor` is the node this command last travelled to (Canvas keeps it in memory only — a ref,+ * never persisted). The pick is the entry AFTER it, wrapping to the oldest.+ * - A cursor no longer in the queue (that agent was answered) restarts at the oldest: the queue+ * is re-read on every press, so "oldest still waiting" is the right next stop.+ * - `currentNodeId` (the terminal the user is focused in) is skipped when anything else waits:+ * the first press from inside the oldest waiting agent must not be a visible no-op.+ * - `null` when nothing needs the user.+ */+export function nextNeedingYou(+ queue: readonly string[],+ cursor: string | null,+ currentNodeId: string | null+): string | null {+ if (queue.length === 0) return null+ const at = cursor === null ? -1 : queue.indexOf(cursor)+ let next = (at + 1) % queue.length+ if (queue[next] === currentNodeId && queue.length > 1) next = (next + 1) % queue.length+ return queue[next]+}diff --git a/src/shared/keybindings.test.ts b/src/shared/keybindings.test.tsindex 96cdddbae..235a94500 100644--- a/src/shared/keybindings.test.ts+++ b/src/shared/keybindings.test.ts@@ -151,6 +151,9 @@ describe('registry invariants', () => {darwin: ['Cmd+ArrowUp'], other: ['Ctrl+Shift+ArrowUp'], allowInTerminal: true },{ id: 'node.focusDown', title: 'Focus node below', group: 'Nodes', scope: 'canvas',darwin: ['Cmd+ArrowDown'], other: ['Ctrl+Shift+ArrowDown'], allowInTerminal: true },+ // Pool only (audit roadmap #19): no default chord on either platform.+ { id: 'node.nextNeedingYou', title: 'Go to next agent needing you', group: 'Nodes',+ scope: 'canvas', darwin: [], other: [], allowInTerminal: true },{ id: 'node.maximize', title: 'Maximize / restore node', group: 'Nodes', scope: 'canvas',darwin: ['Cmd+Shift+Enter'], other: ['Cmd+Shift+Enter'], allowInTerminal: true },{ id: 'node.zoneLeft', title: 'Snap node to left half', group: 'Nodes', scope: 'canvas',diff --git a/src/shared/keybindings.ts b/src/shared/keybindings.tsindex 1f6110977..64132da7b 100644--- a/src/shared/keybindings.ts+++ b/src/shared/keybindings.ts@@ -90,6 +90,7 @@ export type CommandId =| 'node.focusRight'| 'node.focusUp'| 'node.focusDown'+ | 'node.nextNeedingYou'| 'node.maximize'| 'node.zoneLeft'| 'node.zoneRight'@@ -244,6 +245,14 @@ export const COMMAND_DEFINITIONS: readonly CommandDefinition[] = [{ id: 'node.focusDown', title: 'Focus node below', group: 'Nodes', scope: 'canvas',defaultBindings: { darwin: ['Cmd+ArrowDown'], other: ['Ctrl+Shift+ArrowDown'] },allowInTerminal: true },+ // Travel to the agent that has waited longest for you (waiting/blocked), across projects; each+ // press steps to the next one (audit roadmap #19 / qol-2: one chord instead of 3-5 clicks+ // through the sidebar). Ships UNBOUND — every obvious chord already has an owner, and a default+ // would steal it from a user who never asked. Scope 'canvas' + allowInTerminal for the+ // node.focus* reason: the hand that wants to move is in a terminal, and over the kanban board+ // there is no canvas to land on. The queue is built on demand per press (lib/nextNeedingYou).+ { id: 'node.nextNeedingYou', title: 'Go to next agent needing you', group: 'Nodes',+ scope: 'canvas', defaultBindings: both(), allowInTerminal: true },// The header maximize toggle's chord (issue #399): fill the viewport with the node under the// keyboard (else the single selected node), or restore it. allowInTerminal for focus-mode's// reason — the hand that wants more rows is already typing in the terminal being enlarged.