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(kanban): an unanchored card move lands at the top of its column

review4eb2f4ba92dc
diff --git a/src/core/canvas-control-core.ts b/src/core/canvas-control-core.ts
index 27e8cf003..34c8c53e1 100644
--- a/src/core/canvas-control-core.ts
+++ b/src/core/canvas-control-core.ts
@@ -567,7 +567,8 @@ export function buildCanvasControlInstructions(shimPath: string): string {
' plus the virtual Ungrouped column. Start here when you need a column id or want the board state.',
'- `assign --node <id> [--column <id|title>] [--before <nodeId>]` — move a session card to a column',
' (match by column id or title). Omit `--column` (or pass `ungrouped`) to send it back to Ungrouped.',
- ' `--before <nodeId>` drops it above that card within the column. This is board metadata only — it',
+ ' `--before <nodeId>` drops it above that card within the column; without `--before` it lands at the',
+ ' TOP of the column, where the next reader of the board looks first. This is board metadata only — it',
' never moves the node on the canvas or changes its group. Use it to reflect progress: move a card',
' to your "In Progress"/"Done" column as work advances.',
...settingsVerbDocLines(),
@@ -1091,7 +1092,9 @@ Verbs:
- \`assign --node <id> [--column <id|title>] [--before <nodeId>]\` — file a session card under a
column, matching \`--column\` by id or (case-insensitive) title. Omit \`--column\`, or pass
\`ungrouped\`, to send it back to Ungrouped; \`--before <nodeId>\` drops it just above that card
- within the column. This is board metadata ONLY — it never moves the node on the canvas, changes
+ within the column, and without \`--before\` the card lands at the TOP of the column — so a card
+ you just moved to "Done" is the first one there, not buried at the bottom of a long column (a
+ \`--before\` naming a card that is not in that column counts as no anchor). This is board metadata ONLY — it never moves the node on the canvas, changes
its group, or touches the running session. Use it to reflect progress: as a station finishes,
move its card into your "In Progress" / "Done" column so the board tells the real story.
${settingsVerbDocLines().join('\n')}
diff --git a/src/core/project-kanban-write.test.ts b/src/core/project-kanban-write.test.ts
index 73fb6855c..e233c470e 100644
--- a/src/core/project-kanban-write.test.ts
+++ b/src/core/project-kanban-write.test.ts
@@ -128,6 +128,28 @@ describe('setProjectCardColumn', () => {
expect(out.kanban.meta).toEqual([{ nodeId: 'term-a-1', priority: 'high' }])
})
+ // The phone's move names no anchor, so it follows the desktop's unanchored rule: the TOP of the
+ // destination, where the person who just filed it will look for it.
+ it('an unanchored move lands at the TOP of a column that already has cards', () => {
+ const out = parse(
+ setProjectCardColumn(
+ board([
+ { nodeId: 'term-z-9', columnId: 'kcol-b' },
+ { nodeId: 'term-y-8', columnId: 'kcol-b' },
+ { nodeId: 'term-a-1', columnId: 'kcol-a' }
+ ]),
+ 'term-a-1',
+ 'kcol-b',
+ NOW
+ )
+ )
+ expect(out.kanban.assignments.map((a: { nodeId: string }) => a.nodeId)).toEqual([
+ 'term-a-1',
+ 'term-z-9',
+ 'term-y-8'
+ ])
+ })
+
it('refuses a column this board does not have', () => {
expect(setProjectCardColumn(board(), 'term-a-1', 'kcol-gone', NOW)).toBeNull()
})
diff --git a/src/core/project-kanban-write.ts b/src/core/project-kanban-write.ts
index 97ae7b642..680fa63d6 100644
--- a/src/core/project-kanban-write.ts
+++ b/src/core/project-kanban-write.ts
@@ -80,7 +80,9 @@ export function ensureProjectBoard(raw: string, now: Date, mintId = makeColumnId
}
/**
- * Move one card to `columnId`, or to the virtual Ungrouped column (`columnId === null`).
+ * Move one card to `columnId`, or to the virtual Ungrouped column (`columnId === null`). The move
+ * names no position, so — like every unanchored move on the desktop — the card lands at the TOP of
+ * the destination column.
*
* Only `kanban.assignments` is touched: `meta` (assignees / due / priority / labels) is independent
* of placement on the desktop too, and a move must not disturb it.
@@ -119,7 +121,16 @@ export function setProjectCardColumn(
if ((current ?? null) === columnId) return null
const kept = before.filter((a) => a?.nodeId !== nodeId)
- board.assignments = columnId === null ? kept : [...kept, { nodeId, columnId }]
+ if (columnId === null) {
+ board.assignments = kept
+ } else {
+ // Unanchored ⇒ the TOP of the destination, the desktop's rule (`assignNode`): array order is
+ // column order, so that is just before the column's first assignment; an empty column's first
+ // card joins the end of the array.
+ const first = kept.findIndex((a) => a?.columnId === columnId)
+ const at = first === -1 ? kept.length : first
+ board.assignments = [...kept.slice(0, at), { nodeId, columnId }, ...kept.slice(at)]
+ }
if (!Array.isArray(board.columns)) board.columns = columns
root.kanban = board
return bumped(root, now)
diff --git a/src/main/canvas-control-core.test.ts b/src/main/canvas-control-core.test.ts
index 4807696e2..312597629 100644
--- a/src/main/canvas-control-core.test.ts
+++ b/src/main/canvas-control-core.test.ts
@@ -251,6 +251,17 @@ describe('parseControlRequest', () => {
expect(body.toLowerCase()).toContain('confirm')
})
+ // `assign` with no `--before` used to append at the bottom of the column — a card an agent had
+ // just moved into a long Done column read as gone. It now lands at the TOP, and an agent reading
+ // either body must be told so (a doc that still says "end" is a stale contract).
+ it('both agent-facing texts say an unanchored assign lands at the TOP of the column', () => {
+ for (const body of [buildCanvasSkillBody('/x/shim.sh'), buildCanvasControlInstructions('/tmp/nodeterm.sh')]) {
+ const assign = body.slice(body.indexOf('assign --node'), body.indexOf('assign --node') + 900)
+ expect(assign).toMatch(/[Ww]ithout `--before`[^.]*\bTOP\b/)
+ expect(assign).not.toMatch(/\bat the end\b|\bappend/i)
+ }
+ })
+
// The parser change in this commit's sibling is only half a fix: an agent that never learns the
// `=` form simply cannot express a value beginning with `--`, and the failure stays silent for it.
// So both agent-facing texts must carry the rule, not just one of them.
diff --git a/src/renderer/components/kanban/GlobalKanbanView.tsx b/src/renderer/components/kanban/GlobalKanbanView.tsx
index e3aeb9352..b0b84cc21 100644
--- a/src/renderer/components/kanban/GlobalKanbanView.tsx
+++ b/src/renderer/components/kanban/GlobalKanbanView.tsx
@@ -7,7 +7,7 @@ import { useBoardWallpaperStyle } from '../../state/wallpaper'
import {
addColumn, assignNode, assignedTo, boardLabels, cardMatchesLabelFilter, cardMeta, columnForNode,
deleteColumn, labelsForCard, moveColumn,
- nextColumnColor, pruneAssignments, recolorColumn, renameColumn, unassigned, defaultKanban
+ nextColumnColor, pruneAssignments, recolorColumn, renameColumn, unassigned, defaultKanban, AT_COLUMN_END
} from '../../lib/kanban'
import { KanbanColumn, type KanbanLane } from './KanbanColumn'
import { SessionCard } from './SessionCard'
@@ -142,7 +142,7 @@ const Swimlane = memo(function Swimlane({
if (drag.kind === 'column') {
if (columnId !== null) commit(moveColumn(board, drag.id, columnId))
} else {
- commit(assignNode(board, drag.id, columnId, null))
+ commit(assignNode(board, drag.id, columnId, AT_COLUMN_END))
}
}, [board, commit])
@@ -153,10 +153,10 @@ const Swimlane = memo(function Swimlane({
return
}
const ids = columnId === null ? unassigned(board, sessionIds) : assignedTo(board, columnId)
- let beforeId: string | null = targetNodeId
+ let beforeId: string | typeof AT_COLUMN_END = targetNodeId
if (side === 'after') {
const i = ids.indexOf(targetNodeId)
- beforeId = i >= 0 && i + 1 < ids.length ? ids[i+1] : null
+ beforeId = i >= 0 && i + 1 < ids.length ? ids[i+1] : AT_COLUMN_END
}
commit(assignNode(board, drag.id, columnId, beforeId))
}, [board, commit, sessionIds])
diff --git a/src/renderer/components/kanban/KanbanView.placement.test.tsx b/src/renderer/components/kanban/KanbanView.placement.test.tsx
new file mode 100644
index 000000000..0b71aa297
--- /dev/null
+++ b/src/renderer/components/kanban/KanbanView.placement.test.tsx
@@ -0,0 +1,139 @@
+// @vitest-environment jsdom
+//
+// Where a moved card lands. An UNANCHORED move (the card menu's "Move to", the agent `assign` verb)
+// goes to the TOP of the destination; a POSITIONAL drop keeps saying where it was dropped — below
+// the last card, or on the column's empty space under its cards, is the BOTTOM.
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { act } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { KanbanView, type KanbanSession } from './KanbanView'
+import type { ProjectKanban } from '@shared/types'
+import { assignedTo } from '../../lib/kanban'
+
+vi.mock('../../session/session', () => ({
+ useSession: () => ({ source: 'local', api: window.nodeTerminal })
+}))
+
+let root: Root
+let host: HTMLElement
+const card = (id: string): KanbanSession =>
+ ({ id, title: `Card ${id}`, color: '#fff', kind: 'terminal', spawn: {} }) as unknown as KanbanSession
+
+const board = (): ProjectKanban => ({
+ columns: [
+ { id: 'a', title: 'To Do', color: '#0a84ff' },
+ { id: 'b', title: 'Done', color: '#32d74b' }
+ ],
+ assignments: [
+ { nodeId: 'n1', columnId: 'a' },
+ { nodeId: 'n2', columnId: 'b' },
+ { nodeId: 'n3', columnId: 'b' }
+ ]
+})
+
+beforeEach(() => {
+ vi.stubGlobal('IS_REACT_ACT_ENVIRONMENT', true)
+ vi.stubGlobal(
+ 'ResizeObserver',
+ class {
+ observe(): void {}
+ unobserve(): void {}
+ disconnect(): void {}
+ }
+ )
+ ;(window as unknown as { nodeTerminal: unknown }).nodeTerminal = {
+ boardLog: { list: async () => [], onChanged: () => () => {} },
+ settings: { save: async () => {} }
+ }
+})
+afterEach(() => {
+ act(() => root.unmount())
+ host.remove()
+ document.body.innerHTML = ''
+ vi.unstubAllGlobals()
+})
+
+function render(): ReturnType<typeof vi.fn> {
+ const onChange = vi.fn()
+ host = document.createElement('div')
+ document.body.appendChild(host)
+ root = createRoot(host)
+ const noop = (): void => {}
+ act(() =>
+ root.render(
+ <KanbanView
+ board={board()}
+ sessions={['n1', 'n2', 'n3'].map(card)}
+ onChange={onChange}
+ onOpenNode={noop}
+ onCreateNode={noop}
+ onRenameNode={noop}
+ onEditSticky={noop}
+ onDeleteNode={noop}
+ onModalNodeChange={noop}
+ onBrowserNav={noop}
+ onSetIcon={noop}
+ />
+ )
+ )
+ return onChange
+}
+
+/** A drag event jsdom will carry: the handlers read `dataTransfer.effectAllowed` and `clientY`. */
+function dragEvent(type: string, clientY = 0): Event {
+ const e = new Event(type, { bubbles: true, cancelable: true })
+ Object.defineProperty(e, 'dataTransfer', { value: { effectAllowed: 'move' } })
+ Object.defineProperty(e, 'clientY', { value: clientY })
+ return e
+}
+
+const cardEl = (id: string): HTMLElement =>
+ [...document.querySelectorAll<HTMLElement>('.kanban-card--session')].find((el) =>
+ el.textContent?.includes(`Card ${id}`)
+ )!
+
+const columnEl = (title: string): HTMLElement =>
+ [...document.querySelectorAll<HTMLElement>('.kanban-col')].find(
+ (c) => c.querySelector('.kanban-col__title')?.textContent === title
+ )!
+
+describe('KanbanView — card placement', () => {
+ it('a drop BELOW the last card lands at the bottom', () => {
+ const onChange = render()
+ act(() => {
+ cardEl('n1').dispatchEvent(dragEvent('dragstart'))
+ })
+ // jsdom rects are all zero, so any positive clientY is the lower half ⇒ "after".
+ act(() => {
+ cardEl('n3').dispatchEvent(dragEvent('drop', 10))
+ })
+ expect(assignedTo(onChange.mock.calls[0][0], 'b')).toEqual(['n2', 'n3', 'n1'])
+ })
+
+ it('a drop on the column body (not on a card) lands at the bottom', () => {
+ const onChange = render()
+ act(() => {
+ cardEl('n1').dispatchEvent(dragEvent('dragstart'))
+ })
+ act(() => {
+ columnEl('Done').dispatchEvent(dragEvent('drop'))
+ })
+ expect(assignedTo(onChange.mock.calls[0][0], 'b')).toEqual(['n2', 'n3', 'n1'])
+ })
+
+ it('the card menu’s "Move to" is unanchored and lands at the TOP', () => {
+ const onChange = render()
+ act(() => {
+ cardEl('n1').dispatchEvent(new MouseEvent('contextmenu', { bubbles: true, clientX: 5, clientY: 5 }))
+ })
+ const moveTo = [...document.querySelectorAll('.ctx-item')].find((el) => el.textContent?.includes('Move to'))!
+ act(() => {
+ moveTo.dispatchEvent(new MouseEvent('mouseover', { bubbles: true }))
+ })
+ const done = [...document.querySelectorAll('.ctx-item')].find((el) => el.textContent === 'Done')!
+ act(() => {
+ done.dispatchEvent(new MouseEvent('click', { bubbles: true }))
+ })
+ expect(assignedTo(onChange.mock.calls[0][0], 'b')).toEqual(['n1', 'n2', 'n3'])
+ })
+})
diff --git a/src/renderer/components/kanban/KanbanView.tsx b/src/renderer/components/kanban/KanbanView.tsx
index 24d8444f4..9500fe1d4 100644
--- a/src/renderer/components/kanban/KanbanView.tsx
+++ b/src/renderer/components/kanban/KanbanView.tsx
@@ -11,7 +11,7 @@ import { useProjects } from '../../state/projects'
import { useSettings } from '../../state/settings'
import { useBoardWallpaperStyle } from '../../state/wallpaper'
import {
- addColumn, assignNode, assignedTo, boardLabels, cardMatchesLabelFilter, cardMeta, columnForNode,
+ AT_COLUMN_END, addColumn, assignNode, assignedTo, boardLabels, cardMatchesLabelFilter, cardMeta, columnForNode,
deleteColumn, labelsForCard, moveColumn,
nextColumnColor, pruneAssignments, recolorColumn, renameColumn, setColumnCategory, unassigned
} from '../../lib/kanban'
@@ -357,7 +357,7 @@ export const KanbanView = memo(function KanbanView({
if (columnId !== null) commit(moveColumn(board, drag.id, columnId))
// a column dropped on Ungrouped is a no-op — Ungrouped is always first
} else if (isProviderDrag(drag)) requestGitHubMove(drag.issue, columnId)
- else commit(assignNode(board, drag.id, columnId, null))
+ else commit(assignNode(board, drag.id, columnId, AT_COLUMN_END))
},
[board, commit, requestGitHubMove]
)
@@ -374,12 +374,12 @@ export const KanbanView = memo(function KanbanView({
requestGitHubMove(drag.issue, columnId)
return
}
- // "after this card" = "before the NEXT card in the column" (null = end of column).
+ // "after this card" = "before the NEXT card in the column" (after the last = the bottom).
const ids = columnId === null ? unassigned(board, sessionIds) : assignedTo(board, columnId)
- let beforeId: string | null = targetNodeId
+ let beforeId: string | typeof AT_COLUMN_END = targetNodeId
if (side === 'after') {
const i = ids.indexOf(targetNodeId)
- beforeId = i >= 0 && i + 1 < ids.length ? ids[i + 1] : null
+ beforeId = i >= 0 && i + 1 < ids.length ? ids[i + 1] : AT_COLUMN_END
}
commit(assignNode(board, drag.id, columnId, beforeId))
},
diff --git a/src/renderer/lib/kanban.test.ts b/src/renderer/lib/kanban.test.ts
index 853fd0e62..eb54aed11 100644
--- a/src/renderer/lib/kanban.test.ts
+++ b/src/renderer/lib/kanban.test.ts
@@ -7,7 +7,7 @@ import {
boardLabels, cardMatchesLabelFilter, createLabel, deleteLabel, labelColor, labelsForCard,
recolorLabel, renameLabel, reorderLabels, toggleCardLabel,
autoLabelColor, migrateProjectTags, migrateTagsToLabels, setCardLabels, resolveColumnRef,
- setColumnCategory
+ setColumnCategory, AT_COLUMN_END
} from './kanban'
import type { Project } from '@shared/types'
@@ -122,9 +122,21 @@ describe('assignments', () => {
expect(unassigned(k, ['n1', 'n2'])).toEqual(['n1', 'n2'])
expect(assignedTo(k, 'a')).toEqual([])
})
- it('assignNode into a column at the end (null) and before a target', () => {
- const atEnd = assignNode(board(), 'n9', 'b', null)
+ // An UNANCHORED move lands at the TOP of its column: a card an agent just moved into a long
+ // "Done" column used to append at the bottom and read as "it disappeared".
+ it('assignNode with no anchor (null) lands at the TOP of the destination', () => {
+ const atTop = assignNode(board(), 'n9', 'b', null)
+ expect(assignedTo(atTop, 'b')).toEqual(['n9', 'n2'])
+ const moved = assignNode(board(), 'n3', 'a', null)
+ expect(assignedTo(moved, 'a')).toEqual(['n3', 'n1'])
+ })
+ it('assignNode at the column END only when asked for it explicitly (a drop below the last card)', () => {
+ const atEnd = assignNode(board(), 'n9', 'b', AT_COLUMN_END)
expect(assignedTo(atEnd, 'b')).toEqual(['n2', 'n9'])
+ const moved = assignNode(board(), 'n1', 'a', AT_COLUMN_END)
+ expect(assignedTo(moved, 'a')).toEqual(['n3', 'n1'])
+ })
+ it('assignNode before a target card in the column', () => {
const before = assignNode(board(), 'n2', 'a', 'n3')
expect(assignedTo(before, 'a')).toEqual(['n1', 'n2', 'n3'])
expect(assignedTo(before, 'b')).toEqual([])
@@ -133,9 +145,9 @@ describe('assignments', () => {
const k = assignNode(board(), 'n1', null, null)
expect(k.assignments.map((a) => a.nodeId)).toEqual(['n2', 'n3'])
})
- it('assignNode: beforeNode in a different column ⇒ end; unknown column ⇒ no-op; self-before ⇒ no-op', () => {
+ it('assignNode: beforeNode in a different column is no anchor ⇒ top; unknown column ⇒ no-op; self-before ⇒ no-op', () => {
const k = assignNode(board(), 'n1', 'b', 'n3')
- expect(assignedTo(k, 'b')).toEqual(['n2', 'n1'])
+ expect(assignedTo(k, 'b')).toEqual(['n1', 'n2'])
expect(assignNode(board(), 'n1', 'nope', null)).toEqual(board())
expect(assignNode(board(), 'n1', 'a', 'n1')).toEqual(board())
})
diff --git a/src/renderer/lib/kanban.ts b/src/renderer/lib/kanban.ts
index 38b510898..b11d6d704 100644
--- a/src/renderer/lib/kanban.ts
+++ b/src/renderer/lib/kanban.ts
@@ -149,15 +149,27 @@ export function unassigned(k: ProjectKanban, sessionIds: string[]): string[] {
return sessionIds.filter((id) => !assigned.has(id))
}
+/** The explicit "bottom of the column" anchor for `assignNode` — a drop BELOW the last card, or on
+ * the column's empty space under its cards. Everything else that names no card lands at the top. */
+export const AT_COLUMN_END: unique symbol = Symbol('kanban.atColumnEnd')
+
/** Assigns/moves a session card. `columnId` null = back to Ungrouped (assignment removed;
- * Ungrouped order is canvas order, so `beforeNodeId` is ignored there). Inserts before
- * `beforeNodeId`'s assignment when that assignment is in the target column, else at the
- * end. Unknown target column is a no-op. */
+ * Ungrouped order is canvas order, so the anchor is ignored there).
+ *
+ * Placement in the destination column:
+ * - `beforeNodeId` names a card IN that column → just above it;
+ * - `AT_COLUMN_END` → at the bottom (only a positional drop asks for this);
+ * - anything else — `null`, or a card that is not in that column — is UNANCHORED and lands at
+ * the TOP. An unanchored move is "file this here" (the card menu, the agent `assign` verb, a
+ * card created from a column): appended at the bottom of a long "Done" column, the card an
+ * agent just finished read as having disappeared.
+ *
+ * Unknown target column is a no-op. */
export function assignNode(
k: ProjectKanban,
nodeId: string,
columnId: string | null,
- beforeNodeId: string | null
+ beforeNodeId: string | null | typeof AT_COLUMN_END
): ProjectKanban {
if (nodeId === beforeNodeId) return k
if (columnId === null) {
@@ -167,10 +179,16 @@ export function assignNode(
if (!k.columns.some((c) => c.id === columnId)) return k
const moved: KanbanAssignment = { nodeId, columnId }
const without = k.assignments.filter((a) => a.nodeId !== nodeId)
- const before = beforeNodeId
- ? without.find((a) => a.nodeId === beforeNodeId && a.columnId === columnId)
- : undefined
- const idx = before ? without.indexOf(before) : -1
+ const anchor =
+ typeof beforeNodeId === 'string'
+ ? without.find((a) => a.nodeId === beforeNodeId && a.columnId === columnId)
+ : undefined
+ // Array order is the column order, so "top" = before the column's first assignment, and an empty
+ // column's first card simply joins the end of the array.
+ const target =
+ anchor ??
+ (beforeNodeId === AT_COLUMN_END ? undefined : without.find((a) => a.columnId === columnId))
+ const idx = target ? without.indexOf(target) : -1
const at = idx === -1 ? without.length : idx
return { ...k, assignments: [...without.slice(0, at), moved, ...without.slice(at)] }
}