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(keybindings): add "Go to next agent needing you" command

Brandon Bridgesff4cff686c3d
diff --git a/CLAUDE.md b/CLAUDE.md
index afc51301f..734d31dba 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -7523,6 +7523,18 @@ the Settings section and ShortcutsPanel start disagreeing about what a chord mea
while subscribed. It cannot double-fire on desktop (only `buildStubApi` reaches it; the relay
tab 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` in
registry source order, the label from `def.title`, and EVERY one of the command's EFFECTIVE
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 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 list
replaced 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 with
reasoning. 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.tsx
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.