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(keybindings): say why "next agent needing you" finds none after a restart

review3eede8ec86f5
diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsx
index 5be74c3b3..bfd1fd4b0 100644
--- a/src/renderer/canvas/Canvas.tsx
+++ b/src/renderer/canvas/Canvas.tsx
@@ -300,7 +300,12 @@ 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 {
+ needsYouQueue,
+ nextNeedingYou,
+ noAgentWaitingNotice,
+ waitingBeforeRestart
+} from '../lib/nextNeedingYou'
import { liveProjectJumpTarget, projectJumpDigit } from '../lib/projectJump'
import {
liveZoomShortcutAction,
@@ -10494,16 +10499,16 @@ export function Canvas() {
}, [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
+ * "Go to next agent needing you" (`node.nextNeedingYou`, ⌘K): one chord to a waiting agent in
+ * another project. The queue is built ON DEMAND from `getState()` reads — Canvas never
+ * subscribes to the status store's `byId` (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 needsYouInputs = useCallback(() => {
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
@@ -10519,8 +10524,9 @@ export function Canvas() {
color: n.data.color ?? '#888'
}))
: null
- return needsYouQueue(projects, live, active, useAgentStatus.getState().byId)
+ return [projects, live, active, useAgentStatus.getState().byId] as const
}, [nodesRef, nodesProjectIdRef])
+ const needsYouQueueNow = useCallback((): string[] => needsYouQueue(...needsYouInputs()), [needsYouInputs])
const goToNextNeedingYou = useCallback((): void => {
const target = nextNeedingYou(
needsYouQueueNow(),
@@ -10530,13 +10536,14 @@ export function Canvas() {
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.' })
+ // the user bound on purpose do nothing, silently. After a restart an agent already at its
+ // prompt sends no new hook, so the notice says how many were waiting before it.
+ setNotice({ kind: 'info', text: noAgentWaitingNotice(waitingBeforeRestart(...needsYouInputs())) })
return
}
needsYouCursorRef.current = target
travelToNodeRef.current(target)
- }, [needsYouQueueNow])
+ }, [needsYouQueueNow, needsYouInputs])
/**
* Zone snap (issue #394 v1): place `nodeId` (or the placement target, for the keyboard chords)
diff --git a/src/renderer/lib/nextNeedingYou.test.ts b/src/renderer/lib/nextNeedingYou.test.ts
index 578ce68da..27338f458 100644
--- a/src/renderer/lib/nextNeedingYou.test.ts
+++ b/src/renderer/lib/nextNeedingYou.test.ts
@@ -1,5 +1,11 @@
import { describe, it, expect } from 'vitest'
-import { needsYouQueue, nextNeedingYou, type NeedsYouProject } from './nextNeedingYou'
+import {
+ needsYouQueue,
+ nextNeedingYou,
+ noAgentWaitingNotice,
+ waitingBeforeRestart,
+ type NeedsYouProject
+} from './nextNeedingYou'
import type { AgentNodeStatus } from '../state/agentStatus'
const node = (id: string, title = id) => ({ id, kind: 'terminal' as const, title, color: '#888' })
@@ -85,3 +91,45 @@ describe('nextNeedingYou', () => {
expect(nextNeedingYou([], 'x', 'x')).toBeNull()
})
})
+
+describe('after a restart: agents last seen waiting, with nothing reported since', () => {
+ // Live state is transient: right after a relaunch every agent reads unknown, and one already
+ // sitting at a prompt sends no new hook. Only the persisted `lastSeen` clock comes back.
+ const restored = (state: AgentNodeStatus['state']): AgentNodeStatus => ({
+ unread: false,
+ lastSeen: { at: 1000, state, restored: true }
+ })
+
+ it('counts the restored waiting/blocked clocks, not the queue', () => {
+ const status: Record<string, AgentNodeStatus> = {
+ a1: restored('waiting'),
+ a2: restored('blocked'),
+ a3: restored('done'),
+ b1: restored('working'),
+ c1: restored('waiting')
+ }
+ expect(needsYouQueue(projects(), null, 'p1', status)).toEqual([])
+ expect(waitingBeforeRestart(projects(), null, 'p1', status)).toBe(3)
+ })
+
+ it('a clock from THIS run, a live state, or a closed project does not count', () => {
+ const ps = projects()
+ ps[2].closed = true
+ const status: Record<string, AgentNodeStatus> = {
+ a1: { unread: false, lastSeen: { at: 5, state: 'waiting' } }, // seen this run, not restored
+ a2: { ...restored('waiting'), state: 'working', lastEventAt: 9 }, // it reported since
+ c1: restored('waiting') // its project is closed, like the queue's membership
+ }
+ expect(waitingBeforeRestart(ps, null, 'p1', status)).toBe(0)
+ })
+
+ it('says why the queue is empty instead of "no agent is waiting"', () => {
+ expect(noAgentWaitingNotice(0)).toBe('No agent is waiting for you.')
+ expect(noAgentWaitingNotice(1)).toBe(
+ 'No agent has reported waiting since the restart (1 was waiting before it).'
+ )
+ expect(noAgentWaitingNotice(4)).toBe(
+ 'No agent has reported waiting since the restart (4 were waiting before it).'
+ )
+ })
+})
diff --git a/src/renderer/lib/nextNeedingYou.ts b/src/renderer/lib/nextNeedingYou.ts
index c0fc8ca7b..8137d444d 100644
--- a/src/renderer/lib/nextNeedingYou.ts
+++ b/src/renderer/lib/nextNeedingYou.ts
@@ -1,10 +1,9 @@
-// "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).
+// "Go to next agent needing you" (`node.nextNeedingYou`): one chord to reach a waiting agent in
+// another project, instead of opening the sidebar, finding the project and the row, and clicking.
//
// 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
+// with `getState()` — it must NEVER subscribe to the status store's `byId` 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'
@@ -53,6 +52,38 @@ export function needsYouQueue(
.map((r) => r.id)
}
+/**
+ * Agents the queue cannot claim but the user may expect to find in it: live state UNKNOWN (no hook
+ * event since the app started) with a restored `lastSeen` clock that last said `waiting` or
+ * `blocked`. Right after a restart that is every agent still sitting at its prompt — it sends no
+ * new hook until answered — so the honest empty-queue answer counts them rather than saying no
+ * agent is waiting. Same membership as `needsYouQueue` (non-closed projects, travelable rows).
+ */
+export function waitingBeforeRestart(
+ projects: readonly NeedsYouProject[],
+ liveActiveNodes: SessionNodeInput[] | null,
+ activeProjectId: string,
+ statusById: Record<string, AgentNodeStatus>
+): number {
+ const open = projects.filter((p) => !p.closed)
+ return buildStatusList(open, liveActiveNodes, activeProjectId, statusById, '')
+ .flatMap((s) => s.rows)
+ .filter(
+ (r) =>
+ r.statusKind === 'unknown' &&
+ r.statusClock === 'restored' &&
+ (r.lastSeenState === 'waiting' || r.lastSeenState === 'blocked') &&
+ nodeTravel(projects, activeProjectId, r.id).kind !== 'blocked'
+ ).length
+}
+
+/** The notice for an empty queue; `beforeRestart` is `waitingBeforeRestart`'s count. */
+export function noAgentWaitingNotice(beforeRestart: number): string {
+ if (beforeRestart === 0) return 'No agent is waiting for you.'
+ const verb = beforeRestart === 1 ? 'was' : 'were'
+ return `No agent has reported waiting since the restart (${beforeRestart} ${verb} waiting before it).`
+}
+
/**
* The next stop in the cycle.
* - `cursor` is the node this command last travelled to (Canvas keeps it in memory only — a ref,