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(kanban): the Omni board never deletes a peer's card; a fresh node goes before its card

review0c65bc137557
diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsx
index 8aee3e71f..b123ce5bd 100644
--- a/src/renderer/canvas/Canvas.tsx
+++ b/src/renderer/canvas/Canvas.tsx
@@ -618,7 +618,7 @@ import { snapNodeToGrid } from '../lib/nodeSizing'
import { snapResizeChanges } from '../lib/resizeSnap'
import { canClearDirty, canCommitCanvas, canCreateOnCanvas, liveCanvasHolds } from '../state/persistGuards'
import { rebaseOnLatest, useNodesEpoch } from './nodesEpoch'
-import { createKanbanPublisher } from './kanban-sync'
+import { boardLiveNodeIds, createKanbanPublisher } from './kanban-sync'
import { isHidden } from '../lib/ui-visibility'
import { boardLogEvents } from '../lib/boardLogDiff'
import { useBoardLog } from '../state/boardLog'
@@ -3188,6 +3188,27 @@ export function Canvas() {
[]
)
+ /**
+ * Cast a node created THIS tick before anything that names it — spec §2's batch order (node adds,
+ * then card adds). A board write publishes at once from the store funnel (`setProjectKanban` →
+ * the kanban publisher), while `setNodes` lands on a later render and the node publish effect runs
+ * after that, so a site that files a fresh node's card would otherwise put the card on the wire
+ * first. A peer holding the card of a node it has not received prunes the card on its next board
+ * commit (the prune stays local — its removal is never cast — but that peer's own board keeps the
+ * loss). Only for the canvas React Flow holds: a node charged to a stored project is not the node
+ * publisher's. The node is written into `nodesRef` beside the caller's `setNodes` (idempotent), the
+ * same synchronous-ref discipline `attachWorktree` follows, so the render that lands it diffs to
+ * nothing. `node` must be the node AS INSERTED (its frame parenting included).
+ */
+ const castNewNodeNow = useCallback(
+ (projectId: string, node: CanvasNode): void => {
+ if (nodesProjectIdRef.current !== projectId || loadingRef.current) return
+ if (!nodesRef.current.some((n) => n.id === node.id)) nodesRef.current = [...nodesRef.current, node]
+ publisherRef.current?.publish(publishableLater(nodesRef.current))
+ },
+ [publishableLater]
+ )
+
// ---- persistence helpers ----
const commitActiveToStore = useCallback(() => {
const id = useProjects.getState().activeProjectId
@@ -3740,18 +3761,19 @@ export function Canvas() {
const guard = createMutationGuard()
/**
* The node ids live in `projectId` — what the kanban publisher's prune rule asks (a card whose
- * node is not live is pruned locally and its removal NEVER cast). One project's set, never a mix:
- * the project React Flow holds answers from the epoch pair (`nodesRef` is that project's canvas
- * exactly while `nodesProjectIdRef` names it — useNodesEpoch), every other project from its
- * stored copy (a project mid-load is still the store's until the load installs it).
+ * node is not live is pruned locally and its removal NEVER cast). One project's set, never a mix
+ * (`boardLiveNodeIds`): the project React Flow holds answers from the epoch pair (`nodesRef` is
+ * that project's canvas exactly while `nodesProjectIdRef` names it — useNodesEpoch), every other
+ * project from its stored copy (a project mid-load is still the store's until the load installs
+ * it) — and while the Omni board is open, whose lanes prune against the stored copy, the rendered
+ * project answers from React Flow ∩ store (ruling R6).
*/
const liveNodeIdsFor = (projectId: string): ReadonlySet<string> =>
- new Set(
- (nodesProjectIdRef.current === projectId
- ? nodesRef.current
- : (useProjects.getState().getProject(projectId)?.nodes ?? [])
- ).map((n) => n.id)
- )
+ boardLiveNodeIds({
+ rendered: nodesProjectIdRef.current === projectId ? nodesRef.current.map((n) => n.id) : null,
+ stored: (useProjects.getState().getProject(projectId)?.nodes ?? []).map((n) => n.id),
+ omniOpen: isGlobalKanbanOpen()
+ })
/**
* THE ONE CAST on canvas:mut, for every family this Canvas publishes — nodes and edges (the
* canvas publisher, for the active project) and board ops (the kanban publisher, for whichever
@@ -3811,8 +3833,10 @@ export function Canvas() {
* Viewer/Commenter publishes nothing: the host refuses canvas:mut for them (R5).
*/
const shouldPublishFor = (projectId: string): boolean =>
- sessionForProject(projectId).api === activeSession.api &&
+ // The peer check FIRST: the node publisher asks this at ~20 Hz while a node is dragged, and a
+ // solo canvas must pay for nothing more than it did before the board shared this gate.
hasPeersRef.current &&
+ sessionForProject(projectId).api === activeSession.api &&
!isHostedReadOnly(activeSession.id)
const pub = createCanvasPublisher(
(m) => {
@@ -5612,7 +5636,7 @@ export function Canvas() {
// "Start with agent in a new worktree" opens the agent in the same tick as the frame) — the
// same `PendingLaunch` hold a control open into a preparing frame gets (`setupHoldGroup`).
extra?: { issueRef?: IssueRef; awaitSetupGroup?: string }
- ): { node: CanvasNode; projectId: string } | undefined => {
+ ): { node: CanvasNode; placed: CanvasNode; projectId: string } | undefined => {
// Resolve the target project LIVE, at click time — never from this callback's render
// closure. Menu onClick closures outlive the render that built them (`setMenu` freezes
// them into state), and the sessions-sidebar "+" deliberately switches projects before
@@ -5703,7 +5727,9 @@ export function Canvas() {
markDirty()
// The project this node was charged to — the caller files anything else about the node (a
// board card, its run history) against THIS id, never a second live read of the store.
- return { node, projectId: targetProjectId }
+ // `placed` is the node exactly as inserted (frame parenting included) — what a caller casting
+ // it ahead of its board card must send (`castNewNodeNow`).
+ return { node, placed, projectId: targetProjectId }
},
[
setNodes,
@@ -10554,6 +10580,8 @@ export function Canvas() {
setNodes((ns) => [...ns, node])
const board = project?.kanban ?? defaultKanban(targetProjectId)
if (columnId) {
+ // The node goes on the wire BEFORE the card that names it (spec §2 batch order).
+ castNewNodeNow(targetProjectId, node)
useProjects.getState().setProjectKanban(targetProjectId, assignNode(board, node.id, columnId, null))
}
markDirty()
@@ -10580,7 +10608,7 @@ export function Canvas() {
event: { type: 'card-created', to: toName, title }
})
},
- [emptyNodePos, setNodes, markDirty]
+ [emptyNodePos, setNodes, markDirty, castNewNodeNow]
)
// ---- GitHub issue → agent session ("Start with agent ▸") ----
@@ -10596,7 +10624,7 @@ export function Canvas() {
(
issue: GitHubIssueCardView,
ref: IssueRef,
- created: { node: CanvasNode; projectId: string },
+ created: { node: CanvasNode; placed: CanvasNode; projectId: string },
agentId: AgentId
) => {
const { node, projectId: targetProjectId } = created
@@ -10605,6 +10633,8 @@ export function Canvas() {
const board = useProjects.getState().getProject(targetProjectId)?.kanban ?? defaultKanban(targetProjectId)
const column = issue.columnId ? board.columns.find((c) => c.id === issue.columnId) : undefined
if (column) {
+ // The node goes on the wire BEFORE the card that names it (spec §2 batch order).
+ castNewNodeNow(targetProjectId, created.placed)
useProjects.getState().setProjectKanban(targetProjectId, assignNode(board, nodeId, column.id, null))
markDirty()
}
@@ -10629,7 +10659,7 @@ export function Canvas() {
})
if (started) useBoardLog.getState().append(sessionForProject(targetProjectId).api, targetProjectId, started)
},
- [markDirty]
+ [markDirty, castNewNodeNow]
)
/** The reference + first prompt of an issue start, or a notice saying why nothing started. The
diff --git a/src/renderer/canvas/issue-worktree.source.test.ts b/src/renderer/canvas/issue-worktree.source.test.ts
index a81408e96..fd4d8f7b2 100644
--- a/src/renderer/canvas/issue-worktree.source.test.ts
+++ b/src/renderer/canvas/issue-worktree.source.test.ts
@@ -171,7 +171,7 @@ describe('addAgentNode parents OUTSIDE the setNodes updater', () => {
// DefaultLane update first mirrors `nodesRef` back to state, which does not yet hold a frame
// `attachWorktree` created this tick — `parentInto` would then find no group and leave the
// agent top-level, outside the worktree frame it was opened for.
- const add = between('const addAgentNode = useCallback(', 'return { node, projectId: targetProjectId }')
+ const add = between('const addAgentNode = useCallback(', 'return { node, placed, projectId: targetProjectId }')
const placed = add.indexOf('const placed = groupId ? parentInto(node, groupId) : node')
expect(placed).toBeGreaterThan(-1)
expect(placed).toBeLessThan(add.indexOf('setNodes((ns) => [...ns, placed])'))
diff --git a/src/renderer/canvas/kanban-sync-wiring.test.ts b/src/renderer/canvas/kanban-sync-wiring.test.ts
index 14639662f..a012abfa9 100644
--- a/src/renderer/canvas/kanban-sync-wiring.test.ts
+++ b/src/renderer/canvas/kanban-sync-wiring.test.ts
@@ -61,8 +61,38 @@ describe('kanban sync wiring', () => {
// project's from the store.
it('the live node ids are the epoch-correct set for the project asked about', () => {
const body = between(canvas, 'const liveNodeIdsFor = (projectId: string): ReadonlySet<string> =>', 'const castFor = ')
- expect(body).toMatch(/nodesProjectIdRef\.current === projectId\s*\?\s*nodesRef\.current/)
- expect(body).toMatch(/useProjects\.getState\(\)\.getProject\(projectId\)\?\.nodes/)
+ expect(body).toContain('boardLiveNodeIds({')
+ expect(body).toMatch(/rendered: nodesProjectIdRef\.current === projectId \? nodesRef\.current\.map\(\(n\) => n\.id\) : null/)
+ expect(body).toMatch(/stored: \(useProjects\.getState\(\)\.getProject\(projectId\)\?\.nodes \?\? \[\]\)\.map\(\(n\) => n\.id\)/)
+ // R6: while the Omni board is open its lanes prune against the STORED nodes.
+ expect(body).toContain('omniOpen: isGlobalKanbanOpen()')
+ })
+
+ // R7: the solo path (~20 Hz while dragging) asks the cheap question first.
+ it('the one gate asks for a peer before it resolves any session', () => {
+ const gate = between(canvas, 'const shouldPublishFor = (projectId: string): boolean =>', 'const pub = createCanvasPublisher(')
+ expect(gate.indexOf('hasPeersRef.current')).toBeGreaterThan(-1)
+ expect(gate.indexOf('hasPeersRef.current')).toBeLessThan(gate.indexOf('sessionForProject('))
+ })
+
+ // R7: spec §2 batch order — node adds before card adds. A board write casts at once from the
+ // store funnel; `setNodes` lands on a later render. So a site that files a FRESH node's card casts
+ // the node first.
+ it('a fresh node is cast before the board write that files its card', () => {
+ const helper = between(canvas, 'const castNewNodeNow = useCallback(', '[publishableLater]')
+ expect(helper).toContain('if (nodesProjectIdRef.current !== projectId || loadingRef.current) return')
+ expect(helper).toContain('if (!nodesRef.current.some((n) => n.id === node.id)) nodesRef.current = [...nodesRef.current, node]')
+ expect(helper).toContain('publisherRef.current?.publish(publishableLater(nodesRef.current))')
+ for (const [start, cast] of [
+ ['const createNodeInColumn = useCallback(', 'castNewNodeNow(targetProjectId, node)'],
+ ['const fileIssueSession = useCallback(', 'castNewNodeNow(targetProjectId, created.placed)']
+ ]) {
+ const body = between(canvas, start, 'useBoardLog.getState().append(')
+ expect(body.indexOf(cast), start).toBeGreaterThan(-1)
+ expect(body.indexOf(cast), start).toBeLessThan(body.indexOf('setProjectKanban('))
+ }
+ // …and the node cast is the one React Flow will hold: `addAgentNode` hands back the node as placed.
+ expect(canvas).toContain('return { node, placed, projectId: targetProjectId }')
})
it('peer kanban ops are applied through the store reducer, never through setProjectKanban', () => {
diff --git a/src/renderer/canvas/kanban-sync.test.ts b/src/renderer/canvas/kanban-sync.test.ts
index e9e19906d..516f40fa2 100644
--- a/src/renderer/canvas/kanban-sync.test.ts
+++ b/src/renderer/canvas/kanban-sync.test.ts
@@ -1,5 +1,5 @@
import { describe, it, expect, beforeEach, afterEach } from 'vitest'
-import { createKanbanPublisher, type KanbanPublisherDeps } from './kanban-sync'
+import { boardLiveNodeIds, createKanbanPublisher, type KanbanPublisherDeps } from './kanban-sync'
import { applyKanbanOp } from '@shared/kanban-ops'
import { defaultKanbanFor } from '@shared/kanban-default-board'
import type { CanvasMutation, KanbanOp, ProjectKanban } from '@shared/types'
@@ -155,6 +155,48 @@ describe('createKanbanPublisher', () => {
})
})
+// RULING R6. The Omni board prunes each lane against the STORED nodes, and for the project React Flow
+// holds that copy lags the canvas while the board is open (a peer's node op, a "+ New" or an agent
+// spawn lands in React Flow only). A card the Omni board just pruned because its node is not stored
+// yet must not read as a live card someone took off the board — that removal would delete it for
+// everyone. So while the Omni board is open the rendered project's live set is React Flow ∩ store.
+describe('boardLiveNodeIds (R6)', () => {
+ it('a project React Flow does not hold answers from its stored nodes', () => {
+ expect([...boardLiveNodeIds({ rendered: null, stored: ['a', 'b'], omniOpen: true })]).toEqual(['a', 'b'])
+ expect([...boardLiveNodeIds({ rendered: null, stored: ['a'], omniOpen: false })]).toEqual(['a'])
+ })
+
+ it('the rendered project answers from React Flow while the Omni board is closed', () => {
+ expect([...boardLiveNodeIds({ rendered: ['a', 'n'], stored: ['a'], omniOpen: false })].sort()).toEqual(['a', 'n'])
+ })
+
+ it('…and from React Flow ∩ store while it is open', () => {
+ expect([...boardLiveNodeIds({ rendered: ['a', 'n'], stored: ['a', 'gone'], omniOpen: true })]).toEqual(['a'])
+ })
+
+ it('a card the Omni board pruned because its node is not stored yet is never removed for everyone', () => {
+ // n is on the canvas (a peer's node op landed in React Flow) but not in the stored copy the Omni
+ // lane prunes against. The peer's card for n arrived; the Omni user moved another card.
+ const sent: CanvasMutation[] = []
+ const live = { rendered: ['m', 'n'], stored: ['m'] }
+ const pub = createKanbanPublisher({
+ send: (_id, m) => { sent.push(m); return true },
+ liveNodeIds: () => boardLiveNodeIds({ ...live, omniOpen: true }),
+ shouldPublish: () => true,
+ applyLocal: () => {}
+ })
+ const prev: ProjectKanban = {
+ ...withCard(withCard(undefined, 'm', todo), 'n', todo),
+ meta: [{ nodeId: 'n', priority: 'high' }]
+ }
+ // What the Omni lane commits: m moved, and n's card + meta pruned (n is not a stored session).
+ const next: ProjectKanban = { ...withCard(prev, 'm', doing), assignments: [{ nodeId: 'm', columnId: doing }], meta: [] }
+ pub.publish(P, prev, next)
+ expect(sent.filter((m) => m.op === 'kb-card-remove' || m.op === 'kb-meta-remove')).toEqual([])
+ expect(sent).toContainEqual({ op: 'kb-card', assignment: { nodeId: 'm', columnId: doing } })
+ })
+})
+
// The store funnel + the publisher + the store reducer, together: what Canvas wires up.
describe('the store funnel publishes, and only the funnel', () => {
const node = { id: 'n1', kind: 'terminal', title: 'n1', color: '#fff', group: '', position: { x: 0, y: 0 }, size: { width: 10, height: 10 } }
diff --git a/src/renderer/canvas/kanban-sync.ts b/src/renderer/canvas/kanban-sync.ts
index 81e4a02e8..cb5d29e94 100644
--- a/src/renderer/canvas/kanban-sync.ts
+++ b/src/renderer/canvas/kanban-sync.ts
@@ -59,3 +59,27 @@ function stable(v: unknown): string {
: val
)
}
+
+/**
+ * The node ids a board write may treat as LIVE in one project — what the prune rule asks
+ * (`liveNodeIds` above). One project's ids, never a mix:
+ * - a project React Flow does not hold (`rendered` null) answers from its stored nodes;
+ * - the project React Flow holds answers from React Flow, whose array is ahead of the stored copy;
+ * - …except while the Omni board is open (ruling R6): its lanes prune against the STORED nodes, and
+ * for the rendered project that copy lags React Flow for as long as the board is up (a peer's node
+ * op, a "+ New" or an agent spawn lands in React Flow only, and the store catches up at the next
+ * commit). A card the Omni board pruned because its node is not stored yet would read as a live
+ * card someone took off the board, and its removal would delete it for every client. So the
+ * answer there is React Flow ∩ store — both describe the same project, and a smaller live set
+ * can only ever cast fewer removals.
+ */
+export function boardLiveNodeIds(src: {
+ rendered: readonly string[] | null
+ stored: readonly string[]
+ omniOpen: boolean
+}): ReadonlySet<string> {
+ if (!src.rendered) return new Set(src.stored)
+ if (!src.omniOpen) return new Set(src.rendered)
+ const stored = new Set(src.stored)
+ return new Set(src.rendered.filter((id) => stored.has(id)))
+}