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(kanban): lifecycle category on columns
review8080d380b089
diff --git a/src/core/project-kanban-write.labels.test.ts b/src/core/project-kanban-write.labels.test.tsindex f67610883..d8bfcccca 100644--- a/src/core/project-kanban-write.labels.test.ts+++ b/src/core/project-kanban-write.labels.test.ts@@ -113,6 +113,9 @@ describe('editProjectCardLabels — the first label seeds the board', () => {editProjectCardLabels(file(), 'term-a', edit({ create: [{ name: 'bug', color: 'red' }] }), NOW, () => 'kcol-x'))expect(out.kanban.columns.map((c: { title: string }) => c.title)).toEqual(DEFAULT_BOARD_COLUMNS.map((c) => c.title))+ expect(out.kanban.columns.map((c: { category?: string }) => c.category)).toEqual(+ DEFAULT_BOARD_COLUMNS.map((c) => c.category)+ )expect(out.kanban.assignments).toEqual([])expect(labelsForCard(out.kanban, 'term-a').map((l) => l.name)).toEqual(['bug'])})diff --git a/src/core/project-kanban-write.test.ts b/src/core/project-kanban-write.test.tsindex f70bc55ef..73fb6855c 100644--- a/src/core/project-kanban-write.test.ts+++ b/src/core/project-kanban-write.test.ts@@ -32,6 +32,15 @@ describe('ensureProjectBoard', () => {expect(out.savedAt).toBe(NOW.toISOString())})+ it('seeds the lifecycle category the desktop default carries (a phone-born board is the same board)', () => {+ const out = parse(ensureProjectBoard(file(), NOW, () => 'kcol-fixed'))+ expect(out.kanban.columns.map((c: { category?: string }) => c.category)).toEqual([+ 'unstarted',+ 'started',+ 'done'+ ])+ })+it('mints a distinct id per column, in the desktop shape', () => {const out = parse(ensureProjectBoard(file(), NOW))const ids: string[] = out.kanban.columns.map((c: { id: string }) => c.id)diff --git a/src/core/project-kanban-write.ts b/src/core/project-kanban-write.tsindex d66e2595b..97ae7b642 100644--- a/src/core/project-kanban-write.ts+++ b/src/core/project-kanban-write.ts@@ -13,7 +13,7 @@// parse must never be invented or overwritten), or a request that is already satisfied (a board that// exists, a card already in that column) — a retry must not churn `rev`.-import { DEFAULT_BOARD_COLUMNS, makeColumnId } from '../shared/kanban-default-board'+import { defaultBoardColumns, makeColumnId } from '../shared/kanban-default-board'import {KANBAN_LABEL_COLORS,boardLabels,@@ -73,7 +73,7 @@ export function ensureProjectBoard(raw: string, now: Date, mintId = makeColumnIdconst board = boardOf(root)if (!board) return nullif (columnsOf(board).length > 0) return null- board.columns = DEFAULT_BOARD_COLUMNS.map((c) => ({ id: mintId(), title: c.title, color: c.color }))+ board.columns = defaultBoardColumns(mintId)if (!Array.isArray(board.assignments)) board.assignments = []root.kanban = boardreturn bumped(root, now)@@ -255,7 +255,7 @@ export function editProjectCardLabels(const next = k as unknown as Record<string, unknown>if (columnsOf(next).length === 0) {- next.columns = DEFAULT_BOARD_COLUMNS.map((c) => ({ id: mintId(), title: c.title, color: c.color }))+ next.columns = defaultBoardColumns(mintId)}if (!Array.isArray(next.assignments)) next.assignments = []root.kanban = nextdiff --git a/src/core/workspace-files.test.ts b/src/core/workspace-files.test.tsindex 0f6657786..6b5c86a72 100644--- a/src/core/workspace-files.test.ts+++ b/src/core/workspace-files.test.ts@@ -1,8 +1,8 @@import { describe, it, expect } from 'vitest'-import type { CanvasNodeState, Project, Workspace } from '../shared/types'+import type { CanvasNodeState, Project, ProjectKanban, Workspace } from '../shared/types'import {toPortableNodes, resolveNodes, projectToFile, fileToProject, framingViewport,- sameProjectContent, splitWorkspace, serializeProjectFile+ sameProjectContent, splitWorkspace, serializeProjectFile, sanitizeKanban} from './workspace-files'import { legacyFileId } from '../shared/project-id'import { CANVAS_LAYOUTS_CAP, type CanvasLayout } from '../shared/canvas-layout'@@ -578,6 +578,72 @@ describe('kanban board persistence', () => {})})+describe('sanitizeKanban — the board is hostile, git-shared input', () => {+ const clean = (): ProjectKanban => ({+ columns: [+ { id: 'kcol-a', title: 'To Do', color: '#0a84ff', category: 'unstarted' },+ { id: 'kcol-b', title: 'Done', color: '#32d74b', category: 'done' }+ ],+ assignments: [{ nodeId: 'term-abc', columnId: 'kcol-b' }]+ })++ it('returns a clean board BY IDENTITY (no churn on a well-formed file)', () => {+ const k = clean()+ expect(sanitizeKanban(k)).toBe(k)+ })++ it('rejects what validKanban rejects', () => {+ expect(sanitizeKanban(undefined)).toBeUndefined()+ expect(sanitizeKanban({ columns: [], cards: [] })).toBeUndefined()+ expect(sanitizeKanban('nope')).toBeUndefined()+ })++ it('keeps an UNKNOWN category string (a newer build\'s value must survive our save)', () => {+ const k = { ...clean(), columns: [{ id: 'kcol-a', title: 'To Do', color: '#fff', category: 'blocked' }] }+ expect(sanitizeKanban(k)?.columns[0]).toEqual({ id: 'kcol-a', title: 'To Do', color: '#fff', category: 'blocked' })+ })++ it('drops a NON-string category without throwing, keeping the column', () => {+ const k = { ...clean(), columns: [{ id: 'kcol-a', title: 'To Do', color: '#fff', category: { evil: 1 } }] }+ expect(sanitizeKanban(k)?.columns).toEqual([{ id: 'kcol-a', title: 'To Do', color: '#fff' }])+ })++ it('drops column entries a renderer would crash on (non-object, missing id/title)', () => {+ const k = {+ columns: [null, 42, { id: 'x' }, { title: 'no id' }, { id: 'ok', title: { oops: 1 } }, clean().columns[0]],+ assignments: []+ }+ expect(sanitizeKanban(k)?.columns).toEqual([clean().columns[0]])+ })++ it('drops malformed assignments and keeps the rest', () => {+ const k = { ...clean(), assignments: [null, { nodeId: 1, columnId: 'kcol-a' }, { nodeId: 'n' }, { nodeId: 'n', columnId: 'kcol-a' }] }+ expect(sanitizeKanban(k)?.assignments).toEqual([{ nodeId: 'n', columnId: 'kcol-a' }])+ })++ it('keeps fields it does not know (a newer build\'s board data round-trips)', () => {+ const k = { ...clean(), futureThing: [1, 2], columns: [{ ...clean().columns[0], wip: 3 }] }+ const out = sanitizeKanban(k) as unknown as Record<string, unknown>+ expect(out.futureThing).toEqual([1, 2])+ expect((out.columns as Array<Record<string, unknown>>)[0].wip).toBe(3)+ })++ it('runs on the READ seam (fileToProject)', () => {+ const f = projectToFile(project(), 1, '2026-07-18T00:00:00.000Z')+ const evil = { ...f, kanban: { columns: [null, { id: 'a', title: 'A', color: '#fff', category: 7 }], assignments: [] } }+ expect(fileToProject(evil as unknown as ProjectFileV1, { id: 'p1' }).kanban).toEqual({+ columns: [{ id: 'a', title: 'A', color: '#fff' }],+ assignments: []+ })+ })++ it('runs on the WRITE seam (projectToFile) — live data reached by a peer is not trusted either', () => {+ const live = { columns: [{ id: 'a', title: 'A', color: '#fff', category: [] }], assignments: [7] }+ const f = projectToFile(project({ kanban: live as unknown as ProjectKanban }), 1, 'now')+ expect(f.kanban).toEqual({ columns: [{ id: 'a', title: 'A', color: '#fff' }], assignments: [] })+ })+})+describe('the shared file carries content, not machine identity', () => {const p = project({id: 'project-mridky20-11', cwd: '/a/foo', name: 'shared', defaultAccountId: 'acct-1',diff --git a/src/core/workspace-files.ts b/src/core/workspace-files.tsindex 02b037103..eda8992a5 100644--- a/src/core/workspace-files.ts+++ b/src/core/workspace-files.ts@@ -362,6 +362,8 @@ export function projectToFile(// as IN. Validating one direction only passes every round-trip test while leaving the other one// open. See @shared/canvas-layout.const layouts = sanitizeLayouts(p.layouts)+ // Same two-seam rule for the board (see `sanitizeKanban`).+ const kanban = p.kanban ? sanitizeKanban(p.kanban) : undefinedreturn {version: 1,rev,@@ -380,7 +382,7 @@ export function projectToFile(// the acknowledgment is machine-local (IndexEntryV3.capabilityAck) and must never travel....projectCapabilityFields(p),...(p.dinoHighScore ? { dinoHighScore: p.dinoHighScore } : {}),- ...(p.kanban ? { kanban: p.kanban } : {}),+ ...(kanban ? { kanban } : {}),// `layoutViewports` is deliberately absent: a field of that name in the shared file is a// forgery (a repo carrying one person's camera), and `fileToProject` never reads one....(layouts ? { layouts } : {})@@ -399,6 +401,52 @@ export function validKanban(k: unknown): k is ProjectKanban {)}+const isRecord = (x: unknown): x is Record<string, unknown> =>+ !!x && typeof x === 'object' && !Array.isArray(x)++/**+ * The board as it may be ADMITTED: `validKanban`'s shape rule plus the per-entry repairs a+ * hand-edited, git-shared file needs before a renderer touches it — a render throw on a bad board+ * boot-loops the app (the board view choice persists in localStorage).+ *+ * Repairs, never inventions:+ * - a column that is not an object with a string `id` and `title` is dropped (React cannot render+ * an object title, and `resolveColumnRef` lower-cases it);+ * - a column's `category` that is not a STRING is dropped. An unknown string is KEPT: it may be a+ * category a newer build added, and dropping it here would erase that build's data from the+ * shared file on our next save. Readers treat it as absent (`columnCategory`);+ * - an assignment that is not an object with string `nodeId` and `columnId` is dropped.+ * Every other field — known or not — round-trips untouched.+ *+ * Returns the SAME object when nothing needed repair, so a clean file is never rewritten, and+ * `undefined` for anything `validKanban` refuses. Used on every seam: `fileToProject` (in),+ * `projectToFile` (out), and the inline-project branch of the store, which bypasses both.+ */+export function sanitizeKanban(k: unknown): ProjectKanban | undefined {+ if (!validKanban(k)) return undefined+ let changed = false+ const columns: ProjectKanban['columns'] = []+ for (const c of k.columns as unknown[]) {+ if (!isRecord(c) || typeof c.id !== 'string' || typeof c.title !== 'string') {+ changed = true+ continue+ }+ if ('category' in c && typeof c.category !== 'string') {+ const { category: _drop, ...rest } = c+ columns.push(rest as unknown as ProjectKanban['columns'][number])+ changed = true+ continue+ }+ columns.push(c as unknown as ProjectKanban['columns'][number])+ }+ const assignments = (k.assignments as unknown[]).filter(+ (a): a is ProjectKanban['assignments'][number] =>+ isRecord(a) && typeof a.nodeId === 'string' && typeof a.columnId === 'string'+ )+ if (assignments.length !== k.assignments.length) changed = true+ return changed ? { ...k, columns, assignments } : k+}+/** A `{x, y}` point, checked at the boundary because the file is hostile input. */function validPoint(p: unknown): p is { x: number; y: number } {return (@@ -511,6 +559,7 @@ export function fileToProject(// (they are shared content, the cameras are not), or a hand edit dropped it. Pruning on the way// in as well as out is what stops workspace.json accumulating orphans forever.const layoutViewports = pruneLayoutViewports(base.layoutViewports, layouts)+ const kanban = sanitizeKanban(f.kanban)return {id: base.id,// A project whose stored name IS its own path is one this machine (or a teammate's) created@@ -542,7 +591,7 @@ export function fileToProject(// (readProjectCapabilities). `"true"`, 1, {} et al. vanish here, at the boundary....readProjectCapabilities(f),...(f.dinoHighScore ? { dinoHighScore: f.dinoHighScore } : {}),- ...(validKanban(f.kanban) ? { kanban: f.kanban } : {}),+ ...(kanban ? { kanban } : {}),...(base.cwd ? { cwd: base.cwd } : {}),...(base.ssh ? { ssh: base.ssh } : {}),...(base.closed ? { closed: true } : {}),diff --git a/src/core/workspace-store.test.ts b/src/core/workspace-store.test.tsindex 5c1e51b97..67691550e 100644--- a/src/core/workspace-store.test.ts+++ b/src/core/workspace-store.test.ts@@ -233,6 +233,18 @@ describe('inline (cwd-less) project kanban shape guard', () => {const loaded = await new WorkspaceStore().load()expect(loaded.projects[0].kanban).toEqual(board)})++ it('sanitizes an inline board like a file one (the inline branch bypasses fileToProject)', async () => {+ await writeInlineIndex({+ columns: [null, { id: 'kcol-a', title: 'To Do', color: '#0a84ff', category: 5 }],+ assignments: [{ nodeId: 3 }]+ })+ const loaded = await new WorkspaceStore().load()+ expect(loaded.projects[0].kanban).toEqual({+ columns: [{ id: 'kcol-a', title: 'To Do', color: '#0a84ff' }],+ assignments: []+ })+ })})describe('one-time exec migration (pre-existing project files)', () => {diff --git a/src/core/workspace-store.ts b/src/core/workspace-store.tsindex 767ec1791..a7e00be02 100644--- a/src/core/workspace-store.ts+++ b/src/core/workspace-store.ts@@ -13,7 +13,7 @@ import {PROJECT_DIR, PROJECT_FILE, fileToProject, inlineProjectFileRelPath, isInlineProjectFileId,projectToFile, resolveNodes, sameProjectContent,sanitizeLoadedClosedSessions, sanitizeNodeTriggers, serializeProjectFile, splitWorkspace,- validKanban,+ sanitizeKanban,type IndexEntryV3, type ProjectFileV1, type WorkspaceIndexV3} from './workspace-files'import { readProjectSettingsFile, writeProjectSettingsFile } from './project-settings-files'@@ -333,7 +333,8 @@ export class WorkspaceStore {// and the same trigger shape rule (workspace.json is hand-editable input too).// `rest` drops BOTH guarded fields; each is added back below only if it passes its guard.const { kanban, closedSessions, layouts, layoutViewports, ...rest } = e.project- const base = validKanban(kanban) ? { ...rest, kanban } : rest+ const admittedKanban = sanitizeKanban(kanban)+ const base = admittedKanban ? { ...rest, kanban: admittedKanban } : rest// An inline project's embedded layouts are hand-editable input exactly like a git-shared// file's, and they never pass through `fileToProject` on this branch, so they are// sanitized (and their cameras pruned against them) here instead.diff --git a/src/renderer/components/kanban/KanbanColumn.tsx b/src/renderer/components/kanban/KanbanColumn.tsxindex cf874cfe7..c239abba9 100644--- a/src/renderer/components/kanban/KanbanColumn.tsx+++ b/src/renderer/components/kanban/KanbanColumn.tsx@@ -1,8 +1,10 @@import { Fragment, memo, useLayoutEffect, useRef, useState } from 'react'import { createPortal } from 'react-dom'import { IconClose } from '../icons'-import type { KanbanColumn as KanbanColumnT } from '@shared/types'+import type { KanbanColumn as KanbanColumnT, KanbanColumnCategory } from '@shared/types'import { SYSTEM_NODE_COLOR_SWATCHES } from '@shared/node-colors'+import { CATEGORY_LABELS, KANBAN_COLUMN_CATEGORIES, columnCategory } from '@shared/kanban-category'+import { ContextMenu, type MenuItem } from '../ContextMenu'import type { KanbanCreateChoice, KanbanCreateOption } from './KanbanView'import { byLane, type KanbanSourceId } from '../../lib/kanbanSources'@@ -30,6 +32,10 @@ interface KanbanColumnProps {onRename?: (columnId: string, title: string) => voidonRecolor?: (columnId: string, color: string) => voidonDelete?: (columnId: string) => void+ /** Set (or clear, with `undefined`) the column's lifecycle category. Absent = no column menu+ * (the Ungrouped column, a board surface that does not edit categories). The BOARD decides+ * whether the change needs confirming; the column only reports what was picked. */+ onSetCategory?: (columnId: string, category: KanbanColumnCategory | undefined) => void/** "+ New" menu entries (agents, terminal, sticky) and what to do when one is picked* (columnId null = Ungrouped: no assignment). */createOptions: KanbanCreateOption[]@@ -42,9 +48,10 @@ interface KanbanColumnProps {}export const KanbanColumn = memo(function KanbanColumn({- column, lanes, onRename, onRecolor, onDelete,+ column, lanes, onRename, onRecolor, onDelete, onSetCategory,createOptions, onCreate, onColumnDragStart, onDragEnd, onDropOnColumn}: KanbanColumnProps) {+ const [columnMenu, setColumnMenu] = useState<{ x: number; y: number } | null>(null)const [editingTitle, setEditingTitle] = useState(false)const [title, setTitle] = useState(column?.title ?? '')const [swatchesOpen, setSwatchesOpen] = useState(false)@@ -96,7 +103,23 @@ export const KanbanColumn = memo(function KanbanColumn({}, [newMenuOpen])const colId = column?.id ?? null+ const category = columnCategory(column)const orderedLanes = byLane(lanes)+ // The column menu: the lifecycle category (a closed set) as check rows, current one ticked.+ const menuItems = (): MenuItem[] => {+ if (!column || !onSetCategory) return []+ const pick = (next: KanbanColumnCategory | undefined): MenuItem => ({+ label: next ? CATEGORY_LABELS[next] : 'No category',+ icon: category === next ? <span aria-label="current">✓</span> : undefined,+ onClick: () => onSetCategory(column.id, next)+ })+ return [+ { type: 'label', label: 'Category' },+ ...KANBAN_COLUMN_CATEGORIES.map(pick),+ { type: 'separator' },+ pick(undefined)+ ]+ }const count = lanes.reduce((total, lane) => total + lane.count, 0)const commitTitle = () => {@@ -126,6 +149,11 @@ export const KanbanColumn = memo(function KanbanColumn({onColumnDragStart?.(column.id)}}onDragEnd={onDragEnd}+ onContextMenu={(e) => {+ if (!column || !onSetCategory) return+ e.preventDefault()+ setColumnMenu({ x: e.clientX, y: e.clientY })+ }}>{column ? (<button@@ -161,7 +189,28 @@ export const KanbanColumn = memo(function KanbanColumn({{column ? column.title : 'Ungrouped'}</span>)}+ {category && (+ <span+ className={`kanban-col__category kanban-col__category--${category}`}+ title={`Lifecycle category: ${CATEGORY_LABELS[category]}`}+ >+ {CATEGORY_LABELS[category]}+ </span>+ )}<span className="kanban-col__count">{count}</span>+ {column && onSetCategory && (+ <button+ className="kanban-col__menu"+ title="Column options"+ aria-label="Column options"+ onClick={(e) => {+ const r = (e.currentTarget as HTMLElement).getBoundingClientRect()+ setColumnMenu({ x: r.left, y: r.bottom + 4 })+ }}+ >+ ⋯+ </button>+ )}{column && (<buttonclassName="kanban-col__close"@@ -172,6 +221,15 @@ export const KanbanColumn = memo(function KanbanColumn({</button>)}</div>+ {columnMenu && column && onSetCategory && (+ <ContextMenu+ x={columnMenu.x}+ y={columnMenu.y}+ zIndex={60}+ items={menuItems()}+ onClose={() => setColumnMenu(null)}+ />+ )}{column && swatchesOpen && (<div className="kanban-col__swatches">{/* System subset, not the agent colors: ColumnPill draws a column's color as 10pxdiff --git a/src/renderer/components/kanban/KanbanView.category.test.tsx b/src/renderer/components/kanban/KanbanView.category.test.tsxnew file mode 100644index 000000000..96c1dbe38--- /dev/null+++ b/src/renderer/components/kanban/KanbanView.category.test.tsx@@ -0,0 +1,187 @@+// @vitest-environment jsdom+//+// Column lifecycle categories on the board: the progress readout, hiding `closed` columns behind a+// per-user toggle, and the rule that a category is never changed SILENTLY under cards.+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 { useKanbanDisplay } from '../../state/kanbanDisplay'+import { useProjects } from '../../state/projects'++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: 'todo', title: 'To Do', color: '#0a84ff', category: 'unstarted' },+ { id: 'review', title: 'Review', color: '#ffd60a', category: 'started' },+ { id: 'done', title: 'Done', color: '#32d74b', category: 'done' },+ { id: 'wontfix', title: "Won't fix", color: '#8e8e93', category: 'closed' },+ { id: 'empty', title: 'Empty', color: '#bf5af2' }+ ],+ assignments: [+ { nodeId: 'a', columnId: 'todo' },+ { nodeId: 'b', columnId: 'review' },+ { nodeId: 'c', columnId: 'done' },+ { nodeId: 'd', columnId: 'wontfix' }+ ]+})++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 () => {} }+ }+ useProjects.setState({ activeProjectId: 'p-cat' } as never)+ useKanbanDisplay.setState({ byProject: {} })+})+afterEach(() => {+ act(() => root.unmount())+ host.remove()+ document.body.innerHTML = ''+ vi.unstubAllGlobals()+})++function render(k: ProjectKanban, onChange = vi.fn(), sessions = ['a', 'b', 'c', 'd', 'e'].map(card)) {+ host = document.createElement('div')+ document.body.appendChild(host)+ root = createRoot(host)+ const noop = (): void => {}+ const el = (b: ProjectKanban) => (+ <KanbanView+ board={b}+ sessions={sessions}+ onChange={onChange}+ onOpenNode={noop}+ onCreateNode={noop}+ onRenameNode={noop}+ onEditSticky={noop}+ onDeleteNode={noop}+ onModalNodeChange={noop}+ onBrowserNav={noop}+ onSetIcon={noop}+ />+ )+ act(() => root.render(el(k)))+ return { onChange, rerender: (b: ProjectKanban) => act(() => root.render(el(b))) }+}++const columnTitles = (): string[] =>+ [...document.querySelectorAll('.kanban-col__title')].map((el) => el.textContent ?? '')++const click = (el: Element | null | undefined): void => {+ if (!el) throw new Error('missing element')+ act(() => {+ el.dispatchEvent(new MouseEvent('click', { bubbles: true }))+ })+}++function openColumnMenu(title: string): void {+ const col = [...document.querySelectorAll('.kanban-col')].find(+ (c) => c.querySelector('.kanban-col__title')?.textContent === title+ )+ click(col?.querySelector('.kanban-col__menu'))+}++const menuRow = (label: string): Element | undefined =>+ [...document.querySelectorAll('.ctx-item')].find((el) => el.textContent?.includes(label))++describe('KanbanView — lifecycle progress', () => {+ it('reads done+closed over every live card, Ungrouped included', () => {+ render(board())+ // c (done) + d (closed) of a,b,c,d,e (e is Ungrouped).+ expect(document.querySelector('.kanban-progress')?.textContent).toContain('2/5')+ })++ it('shows nothing when no column says what "complete" means', () => {+ const k = { ...board(), columns: board().columns.map(({ category: _c, ...c }) => c) }+ render(k)+ expect(document.querySelector('.kanban-progress')).toBeNull()+ })+})++describe('KanbanView — closed columns', () => {+ it('are hidden by default, behind a toggle that names how many', () => {+ render(board())+ expect(columnTitles()).not.toContain("Won't fix")+ const toggle = document.querySelector('.kanban-closed-toggle')+ expect(toggle?.textContent).toContain('1')+ click(toggle)+ expect(columnTitles()).toContain("Won't fix")+ })++ it('the choice is this user’s (localStorage), never a board edit', () => {+ const { onChange } = render(board())+ click(document.querySelector('.kanban-closed-toggle'))+ expect(onChange).not.toHaveBeenCalled()+ expect(useKanbanDisplay.getState().showClosed('p-cat')).toBe(true)+ })++ it('offers no toggle on a board with no closed column', () => {+ render({ ...board(), columns: board().columns.filter((c) => c.category !== 'closed') })+ expect(document.querySelector('.kanban-closed-toggle')).toBeNull()+ })+})++describe('KanbanView — changing a category', () => {+ it('an EMPTY column changes immediately', () => {+ const { onChange } = render(board())+ openColumnMenu('Empty')+ click(menuRow('Done'))+ expect(onChange).toHaveBeenCalledTimes(1)+ const next = onChange.mock.calls[0][0] as ProjectKanban+ expect(next.columns.find((c) => c.id === 'empty')?.category).toBe('done')+ })++ it('a column WITH cards asks first, naming the count — never silently re-means its cards', () => {+ const { onChange } = render(board())+ openColumnMenu('Review')+ click(menuRow('Done'))+ expect(onChange).not.toHaveBeenCalled()+ const dialog = document.querySelector('.confirm')+ expect(dialog?.textContent).toContain('1 card')+ click([...document.querySelectorAll('button')].find((b) => b.textContent === 'Change category'))+ expect(onChange).toHaveBeenCalledTimes(1)+ const next = onChange.mock.calls[0][0] as ProjectKanban+ expect(next.columns.find((c) => c.id === 'review')?.category).toBe('done')+ })++ it('cancelling the confirmation changes nothing', () => {+ const { onChange } = render(board())+ openColumnMenu('Review')+ click(menuRow('Closed'))+ click([...document.querySelectorAll('button')].find((b) => b.textContent === 'Cancel'))+ expect(onChange).not.toHaveBeenCalled()+ })++ it('the Ungrouped column has no category menu (it is virtual)', () => {+ render(board())+ const ungrouped = document.querySelector('.kanban-col--ungrouped')+ expect(ungrouped?.querySelector('.kanban-col__menu')).toBeNull()+ })++ it('a categorized column shows its category in the header', () => {+ render(board())+ const review = [...document.querySelectorAll('.kanban-col')].find(+ (c) => c.querySelector('.kanban-col__title')?.textContent === 'Review'+ )+ expect(review?.querySelector('.kanban-col__category')?.textContent).toBe('Started')+ })+})diff --git a/src/renderer/components/kanban/KanbanView.tsx b/src/renderer/components/kanban/KanbanView.tsxindex f550a72ef..24d8444f4 100644--- a/src/renderer/components/kanban/KanbanView.tsx+++ b/src/renderer/components/kanban/KanbanView.tsx@@ -1,5 +1,9 @@import { memo, useCallback, useEffect, useMemo, useRef, useState } from 'react'-import type { KanbanLabel, ProjectKanban } from '@shared/types'+import type { KanbanColumnCategory, KanbanLabel, ProjectKanban } from '@shared/types'+import {+ boardProgress, categoryChangeImpact, categoryChangeMessage, columnCategory+} from '@shared/kanban-category'+import { useKanbanDisplay } from '../../state/kanbanDisplay'import type { NodeIcon } from '@shared/node-icon'import { AGENT_CONFIG, BUILTIN_AGENT_IDS, type AgentId } from '@shared/agents/config'import { useViewMode } from '../../state/viewMode'@@ -9,7 +13,7 @@ import { useBoardWallpaperStyle } from '../../state/wallpaper'import {addColumn, assignNode, assignedTo, boardLabels, cardMatchesLabelFilter, cardMeta, columnForNode,deleteColumn, labelsForCard, moveColumn,- nextColumnColor, pruneAssignments, recolorColumn, renameColumn, unassigned+ nextColumnColor, pruneAssignments, recolorColumn, renameColumn, setColumnCategory, unassigned} from '../../lib/kanban'import { markCanvasCovered } from '../../lib/canvasCovered'import { labelSwatch } from '../../lib/kanbanLabelColors'@@ -169,6 +173,13 @@ export const KanbanView = memo(function KanbanView({const projectId = useProjects((s) => s.activeProjectId)const projectName = useProjects((s) => s.projects.find((p) => p.id === s.activeProjectId)?.name)const projectColor = useProjects((s) => s.projects.find((p) => p.id === s.activeProjectId)?.color)+ // Per-user display: whether `closed` columns are on screen (localStorage, never the board).+ const showClosed = useKanbanDisplay((s) => s.byProject[projectId]?.showClosed === true)+ const setShowClosed = useKanbanDisplay((s) => s.setShowClosed)+ // A category change that would re-mean cards waits here for an explicit confirmation.+ const [pendingCategory, setPendingCategory] = useState<+ { columnId: string; category: KanbanColumnCategory | undefined; message: string } | null+ >(null)const github = useGitHubIssues((state) => state.projects[projectId])const githubReadOnly = Object.values(github?.pages ?? {}).some((page) => page.readOnly)// Pull requests are evicted first when a repository outgrows the cache bounds, so the lane can@@ -391,6 +402,18 @@ export const KanbanView = memo(function KanbanView({}}, [board, byId, sessionIds, activeLocalFilter])+ // Lifecycle: the board's progress (null when no column says what "complete" means) and the+ // columns this user sees — `closed` ones only when they asked for them.+ const progress = useMemo(() => boardProgress(board, sessionIds), [board, sessionIds])+ const closedCount = useMemo(+ () => board.columns.filter((c) => columnCategory(c) === 'closed').length,+ [board.columns]+ )+ const shownColumns = useMemo(+ () => (showClosed ? board.columns : board.columns.filter((c) => columnCategory(c) !== 'closed')),+ [board.columns, showClosed]+ )+// Stable column/card plumbing — every handler the memoized columns receive is identity-stable// across renders (the column binds its own id; cards bind theirs).const handleCardDragStart = useCallback((id: string) => {@@ -421,6 +444,21 @@ export const KanbanView = memo(function KanbanView({(columnId: string) => commit(deleteColumn(board, columnId)),[board, commit])+ // A category is a claim about every card in the column, so a change that would re-mean cards is+ // never applied silently: an empty column changes at once, a populated one asks first.+ const handleSetCategory = useCallback(+ (columnId: string, category: KanbanColumnCategory | undefined) => {+ const impact = categoryChangeImpact(board, columnId, category, sessionIds)+ if (!impact) {+ const next = setColumnCategory(board, columnId, category)+ if (next !== board) commit(next)+ return+ }+ const title = board.columns.find((c) => c.id === columnId)?.title ?? 'this column'+ setPendingCategory({ columnId, category, message: categoryChangeMessage(title, impact, !showClosed) })+ },+ [board, commit, sessionIds, showClosed]+ )const handleMoveGitHub = requestGitHubMoveconst githubPage = useCallback((columnId: string | null) =>github?.pages[columnId ?? 'ungrouped'], [github])@@ -563,6 +601,30 @@ export const KanbanView = memo(function KanbanView({<div className="kanban-header"><span className="kanban-header__dot" style={{ background: projectColor }} /><span className="kanban-header__name">{projectName}</span>+ {progress && (+ <span+ className="kanban-progress"+ title="Cards in Done and Closed columns, out of every card on the board"+ >+ <span className="kanban-progress__bar">+ <span+ className="kanban-progress__fill"+ style={{ width: `${Math.round((progress.complete / progress.total) * 100)}%` }}+ />+ </span>+ {progress.complete}/{progress.total} done+ </span>+ )}+ {closedCount > 0 && (+ <button+ className={`kanban-filter-btn kanban-closed-toggle${showClosed ? ' kanban-filter-btn--on' : ''}`}+ title={showClosed ? 'Hide closed columns' : 'Show closed columns'}+ aria-pressed={showClosed}+ onClick={() => setShowClosed(projectId, !showClosed)}+ >+ {showClosed ? 'Hide closed' : `Show closed · ${closedCount}`}+ </button>+ )}{board.github && <KanbanSourceFilter value={source} onChange={setSource} />}{board.github && github?.loading && <span className="kanban-github-status">Loading GitHub issues…</span>}{board.github && github?.error && (@@ -645,7 +707,7 @@ export const KanbanView = memo(function KanbanView({onDragEnd={handleDragEnd}onDropOnColumn={dropOnColumn}/>- {board.columns.map((col) => (+ {shownColumns.map((col) => (<KanbanColumnkey={col.id}column={col}@@ -653,6 +715,7 @@ export const KanbanView = memo(function KanbanView({onRename={handleRenameColumn}onRecolor={handleRecolorColumn}onDelete={handleDeleteColumn}+ onSetCategory={handleSetCategory}createOptions={createOptions}onCreate={onCreateNode}onColumnDragStart={handleColumnDragStart}@@ -706,6 +769,19 @@ export const KanbanView = memo(function KanbanView({onClose={() => setModalIssue(null)}/>)}+ {pendingCategory && (+ <ConfirmDialog+ message={pendingCategory.message}+ confirmLabel="Change category"+ onCancel={() => setPendingCategory(null)}+ onConfirm={() => {+ const { columnId, category } = pendingCategory+ setPendingCategory(null)+ const next = setColumnCategory(board, columnId, category)+ if (next !== board) commit(next)+ }}+ />+ )}{pendingGitHubMove && (<ConfirmDialogmessage={pendingGitHubMove.confirmation.message}diff --git a/src/renderer/components/settings/sections/GitHubIssuesSection.test.tsx b/src/renderer/components/settings/sections/GitHubIssuesSection.test.tsxindex cc5bf45ab..a924d942f 100644--- a/src/renderer/components/settings/sections/GitHubIssuesSection.test.tsx+++ b/src/renderer/components/settings/sections/GitHubIssuesSection.test.tsx@@ -169,6 +169,30 @@ describe('GitHubIssuesSection', () => {+ // Before lifecycle categories the default was simply the LAST column; a board with an archive+ // column after Done would then close issues into the archive.+ it('defaults the completion column to the board\'s Done-category column, not merely the last one', async () => {+ useProjects.setState({+ activeProjectId: 'p1',+ projects: [{+ id: 'p1', name: 'Project', color: '#8b5cf6', viewport: { x: 0, y: 0, zoom: 1 },+ nodes: [], cwd: '/repo',+ kanban: {+ columns: [+ { id: 'todo', title: 'Todo', color: '#2563eb', category: 'unstarted' },+ { id: 'shipped', title: 'Shipped', color: '#16a34a', category: 'done' },+ { id: 'archive', title: 'Archive', color: '#8e8e93', category: 'closed' }+ ],+ assignments: []+ }+ }]+ })+ await mount()+ const toggle = host.querySelector<HTMLElement>('[aria-label="Include GitHub issues"]')!+ await act(async () => { toggle.dispatchEvent(new MouseEvent('click', { bubbles: true })) })+ expect(useProjects.getState().getProject('p1')?.kanban?.github?.completionColumnId).toBe('shipped')+ })+it('reports an Approve failure beside the Approve button, not three rows below it', async () => {;(window as unknown as { nodeTerminal: any }).nodeTerminal.githubControl.approve =vi.fn(async () => { throw Object.assign(new Error('invalid-configuration'), { code: 'invalid-configuration' }) })diff --git a/src/renderer/components/settings/sections/GitHubIssuesSection.tsx b/src/renderer/components/settings/sections/GitHubIssuesSection.tsxindex f9b62dbd3..4889bf39b 100644--- a/src/renderer/components/settings/sections/GitHubIssuesSection.tsx+++ b/src/renderer/components/settings/sections/GitHubIssuesSection.tsx@@ -5,6 +5,8 @@ import type {GitHubControlView,ProjectKanbanGitHub} from '@shared/github-issues'+import type { KanbanColumn } from '@shared/types'+import { defaultCompletionColumnId } from '@shared/kanban-category'import { useProjects } from '../../../state/projects'import { markWorkspaceDirty } from '../../../state/workspaceDirty'import { SettingsSection } from '../SettingsSection'@@ -45,13 +47,16 @@ const ENTRIES = Object.values(ROWS)type Confirmation = 'labels' | 'cache' | 'revoke' | nulltype NoticeRow = 'repository' | 'authentication' | 'data'-function defaultGitHub(columns: Array<{ id: string; title: string }>): ProjectKanbanGitHub {+function defaultGitHub(columns: Array<Pick<KanbanColumn, 'id' | 'title' | 'category'>>): ProjectKanbanGitHub {+ // The board's own Done column when its categories say which one that is; the last column only+ // for an uncategorized board (the pre-category default). See @shared/kanban-category.+ const completionColumnId = defaultCompletionColumnId(columns)return {columnMappings: columns.map((column) => ({columnId: column.id,label: `status:${column.title.trim().toLocaleLowerCase('en-US').replace(/\s+/g, '-')}`})),- ...(columns.length ? { completionColumnId: columns[columns.length - 1].id } : {})+ ...(completionColumnId ? { completionColumnId } : {})}}diff --git a/src/renderer/lib/kanban.test.ts b/src/renderer/lib/kanban.test.tsindex 2feae223c..853fd0e62 100644--- a/src/renderer/lib/kanban.test.ts+++ b/src/renderer/lib/kanban.test.ts@@ -6,7 +6,8 @@ import {setCardDue, setCardPriority, toggleAssignee, unassigned,boardLabels, cardMatchesLabelFilter, createLabel, deleteLabel, labelColor, labelsForCard,recolorLabel, renameLabel, reorderLabels, toggleCardLabel,- autoLabelColor, migrateProjectTags, migrateTagsToLabels, setCardLabels, resolveColumnRef+ autoLabelColor, migrateProjectTags, migrateTagsToLabels, setCardLabels, resolveColumnRef,+ setColumnCategory} from './kanban'import type { Project } from '@shared/types'@@ -26,6 +27,7 @@ describe('defaultKanban', () => {it('makes To Do / In Progress / Done with unique ids and no assignments', () => {const k = defaultKanban()expect(k.columns.map((c) => c.title)).toEqual(['To Do', 'In Progress', 'Done'])+ expect(k.columns.map((c) => c.category)).toEqual(['unstarted', 'started', 'done'])expect(new Set(k.columns.map((c) => c.id)).size).toBe(3)expect(k.assignments).toEqual([])})@@ -53,6 +55,21 @@ describe('columns', () => {expect(k.columns[1]).toMatchObject({ id: 'b', title: 'WIP', color: '#fff' })expect(k.columns[0]).toEqual(board().columns[0])})+ it('setColumnCategory sets, changes and clears ONLY the target column', () => {+ const set = setColumnCategory(board(), 'b', 'done')+ expect(set.columns[1]).toEqual({ id: 'b', title: 'Doing', color: '#ffd60a', category: 'done' })+ expect(set.columns[0]).toEqual(board().columns[0])+ const cleared = setColumnCategory(set, 'b', undefined)+ expect(cleared.columns[1]).toEqual(board().columns[1])+ expect('category' in cleared.columns[1]).toBe(false)+ })+ it('setColumnCategory: unknown column or unchanged value returns the SAME board (no persist)', () => {+ const k = board()+ expect(setColumnCategory(k, 'nope', 'done')).toBe(k)+ expect(setColumnCategory(k, 'a', undefined)).toBe(k)+ const set = setColumnCategory(k, 'a', 'started')+ expect(setColumnCategory(set, 'a', 'started')).toBe(set)+ })it('moveColumn before a target and to the end (null)', () => {expect(moveColumn(board(), 'b', 'a').columns.map((c) => c.id)).toEqual(['b', 'a'])expect(moveColumn(board(), 'a', null).columns.map((c) => c.id)).toEqual(['b', 'a'])diff --git a/src/renderer/lib/kanban.ts b/src/renderer/lib/kanban.tsindex 46d4187c0..38b510898 100644--- a/src/renderer/lib/kanban.ts+++ b/src/renderer/lib/kanban.ts@@ -1,6 +1,9 @@-import type { CanvasNodeState, KanbanAssignment, KanbanColumn, Project, ProjectKanban } from '@shared/types'+import type {+ CanvasNodeState, KanbanAssignment, KanbanColumn, KanbanColumnCategory, Project, ProjectKanban+} from '@shared/types'+import { columnCategory } from '@shared/kanban-category'import { SYSTEM_NODE_COLORS } from '../state/workspace'-import { DEFAULT_BOARD_COLUMNS, makeColumnId } from '@shared/kanban-default-board'+import { defaultBoardColumns } from '@shared/kanban-default-board'import { autoLabelColor, boardLabels, cardMeta, createLabel, metaList, setCardLabels } from '@shared/kanban-labels'// The card-meta + label transforms live in `@shared/kanban-labels` (the host core applies the@@ -21,7 +24,7 @@ const kid = (prefix: string): string => `${prefix}-${Math.random().toString(36).* shared definition so a board born on either surface is the same board. */export function defaultKanban(): ProjectKanban {return {- columns: DEFAULT_BOARD_COLUMNS.map((c) => ({ id: makeColumnId(), title: c.title, color: c.color })),+ columns: defaultBoardColumns(),assignments: []}}@@ -61,6 +64,26 @@ export function recolorColumn(k: ProjectKanban, columnId: string, color: string)return { ...k, columns: k.columns.map((c) => (c.id === columnId ? { ...c, color } : c)) }}+/** Sets (or, with `undefined`, clears) a column's lifecycle category. Returns the SAME board when+ * nothing changes (unknown column, or the value it already reads as), so a caller can skip a+ * no-op persist. The UI confirms first when the column holds cards (`categoryChangeImpact`). */+export function setColumnCategory(+ k: ProjectKanban,+ columnId: string,+ category: KanbanColumnCategory | undefined+): ProjectKanban {+ const target = k.columns.find((c) => c.id === columnId)+ if (!target || columnCategory(target) === columnCategory({ category })) return k+ return {+ ...k,+ columns: k.columns.map((c) => {+ if (c.id !== columnId) return c+ const { category: _old, ...rest } = c+ return category ? { ...rest, category } : rest+ })+ }+}+/** Moves a column before `beforeId` (null = to the end). */export function moveColumn(k: ProjectKanban, columnId: string, beforeId: string | null): ProjectKanban {if (columnId === beforeId) return kdiff --git a/src/renderer/state/kanbanDisplay.test.ts b/src/renderer/state/kanbanDisplay.test.tsnew file mode 100644index 000000000..edbf07543--- /dev/null+++ b/src/renderer/state/kanbanDisplay.test.ts@@ -0,0 +1,35 @@+import { describe, expect, it } from 'vitest'+import { parseKanbanDisplay, useKanbanDisplay } from './kanbanDisplay'++describe('parseKanbanDisplay', () => {+ it('reads a well-formed per-project map', () => {+ expect(parseKanbanDisplay('{"p1":{"showClosed":true},"p2":{"showClosed":false}}')).toEqual({+ p1: { showClosed: true },+ p2: { showClosed: false }+ })+ })++ it('is empty (every default) for missing or unparseable storage', () => {+ expect(parseKanbanDisplay(null)).toEqual({})+ expect(parseKanbanDisplay('{nope')).toEqual({})+ expect(parseKanbanDisplay('[1,2]')).toEqual({})+ expect(parseKanbanDisplay('"str"')).toEqual({})+ })++ it('keeps only literal booleans — a hand-edited value never flips a default', () => {+ expect(parseKanbanDisplay('{"p1":{"showClosed":"yes"},"p2":7,"p3":{"showClosed":true,"x":1}}')).toEqual({+ p1: {},+ p3: { showClosed: true }+ })+ })+})++describe('useKanbanDisplay', () => {+ it('closed columns are hidden until the user asks, per project', () => {+ const s = useKanbanDisplay.getState()+ expect(s.showClosed('p-a')).toBe(false)+ s.setShowClosed('p-a', true)+ expect(useKanbanDisplay.getState().showClosed('p-a')).toBe(true)+ expect(useKanbanDisplay.getState().showClosed('p-b')).toBe(false)+ })+})diff --git a/src/renderer/state/kanbanDisplay.ts b/src/renderer/state/kanbanDisplay.tsnew file mode 100644index 000000000..31ea63c2e--- /dev/null+++ b/src/renderer/state/kanbanDisplay.ts@@ -0,0 +1,68 @@+import { create } from 'zustand'+import { readLocal, writeLocal } from '../lib/localStore'++// How ONE person looks at a project's board — PERSONAL, per machine: localStorage, never the+// git-shared .nodeterm/project.json (same rule as the view mode and the card panel). What the board+// SAYS (its columns, their categories) is shared; whether this user wants the `closed` columns in+// front of them is not — one teammate hiding finished work must not hide it for everybody.+//+// Deliberately NOT here: the transient status chips (Running / Needs you / Unread). They filter on+// second-by-second agent state, and a filter like that surviving a restart shows a board that is+// wrong before anyone has looked at it. They live in KanbanView's component state.++export const KANBAN_DISPLAY_KEY = 'nodeterm.kanbanDisplay'++export interface ProjectBoardDisplay {+ /** Show columns whose category is `closed`. Absent = hidden (the point of `closed`). */+ showClosed?: boolean+}++export type KanbanDisplayMap = Record<string, ProjectBoardDisplay>++const isRecord = (x: unknown): x is Record<string, unknown> =>+ !!x && typeof x === 'object' && !Array.isArray(x)++/** Parses the persisted map. Anything unreadable is "every default"; only literal booleans are+ * kept, so a hand-edited value can never flip a default it did not spell exactly. */+export function parseKanbanDisplay(raw: string | null): KanbanDisplayMap {+ if (!raw) return {}+ let parsed: unknown+ try {+ parsed = JSON.parse(raw)+ } catch {+ return {}+ }+ if (!isRecord(parsed)) return {}+ const out: KanbanDisplayMap = {}+ for (const [pid, v] of Object.entries(parsed)) {+ if (!isRecord(v)) continue+ const entry: ProjectBoardDisplay = {}+ if (typeof v.showClosed === 'boolean') entry.showClosed = v.showClosed+ out[pid] = entry+ }+ return out+}++function save(map: KanbanDisplayMap): void {+ try {+ writeLocal(KANBAN_DISPLAY_KEY, JSON.stringify(map))+ } catch {+ /* quota/private-mode: a display preference is a nicety, never fail the UI */+ }+}++interface KanbanDisplayState {+ byProject: KanbanDisplayMap+ showClosed(projectId: string): boolean+ setShowClosed(projectId: string, show: boolean): void+}++export const useKanbanDisplay = create<KanbanDisplayState>((set, get) => ({+ byProject: parseKanbanDisplay(readLocal(KANBAN_DISPLAY_KEY)),+ showClosed: (projectId) => get().byProject[projectId]?.showClosed === true,+ setShowClosed: (projectId, show) => {+ const byProject = { ...get().byProject, [projectId]: { ...get().byProject[projectId], showClosed: show } }+ save(byProject)+ set({ byProject })+ }+}))diff --git a/src/renderer/styles.css b/src/renderer/styles.cssindex 4b28b9a63..746dc708f 100644--- a/src/renderer/styles.css+++ b/src/renderer/styles.css@@ -10494,6 +10494,55 @@ button.group-node__setup:disabled {.kanban-col__close:hover {color: var(--danger);}+/* Lifecycle category marker (@shared/kanban-category): a quiet word beside the title, never a+ second colour language — the column's own dot already carries its identity. */+.kanban-col__category {+ flex: 0 0 auto;+ font-size: 9.5px;+ font-weight: 700;+ letter-spacing: 0.05em;+ text-transform: uppercase;+ color: rgba(var(--tint-rgb), 0.5);+ border: 1px solid rgba(var(--tint-rgb), 0.14);+ border-radius: 4px;+ padding: 0 4px;+ white-space: nowrap;+}+.kanban-col__menu {+ background: none;+ border: none;+ color: rgba(var(--tint-rgb), 0.35);+ cursor: pointer;+ font-size: 13px;+ line-height: 1;+ padding: 0 2px;+}+.kanban-col__menu:hover {+ color: var(--text-strong);+}+/* Board progress (cards in done+closed columns over every card) in the title strip. */+.kanban-progress {+ display: inline-flex;+ align-items: center;+ gap: 6px;+ margin-left: 6px;+ font-size: 11px;+ color: rgba(var(--tint-rgb), 0.55);+ white-space: nowrap;+ font-variant-numeric: tabular-nums;+}+.kanban-progress__bar {+ width: 56px;+ height: 4px;+ border-radius: 2px;+ background: rgba(var(--tint-rgb), 0.1);+ overflow: hidden;+}+.kanban-progress__fill {+ display: block;+ height: 100%;+ background: var(--state-success);+}.kanban-col__swatches {display: flex;gap: 6px;diff --git a/src/shared/kanban-category.test.ts b/src/shared/kanban-category.test.tsnew file mode 100644index 000000000..43d5cde7a--- /dev/null+++ b/src/shared/kanban-category.test.ts@@ -0,0 +1,147 @@+import { describe, expect, it } from 'vitest'+import type { KanbanColumn, ProjectKanban } from './types'+import {+ CATEGORY_LABELS,+ KANBAN_COLUMN_CATEGORIES,+ boardProgress,+ categoryChangeImpact,+ categoryChangeMessage,+ columnCategory,+ defaultCompletionColumnId,+ isCompletedCategory+} from './kanban-category'++const col = (id: string, category?: unknown): KanbanColumn =>+ ({ id, title: id, color: '#fff', ...(category !== undefined ? { category } : {}) }) as KanbanColumn++const board = (): ProjectKanban => ({+ columns: [col('todo', 'unstarted'), col('doing', 'started'), col('done', 'done'), col('gone', 'closed')],+ assignments: [+ { nodeId: 'a', columnId: 'todo' },+ { nodeId: 'b', columnId: 'doing' },+ { nodeId: 'c', columnId: 'done' },+ { nodeId: 'd', columnId: 'gone' },+ { nodeId: 'dead', columnId: 'done' }+ ]+})++describe('columnCategory', () => {+ it('reads the four known values', () => {+ for (const c of KANBAN_COLUMN_CATEGORIES) expect(columnCategory(col('x', c))).toBe(c)+ })++ it('reads an absent, unknown or non-string value as ABSENT (never throws)', () => {+ expect(columnCategory(col('x'))).toBeUndefined()+ expect(columnCategory(col('x', 'blocked'))).toBeUndefined()+ expect(columnCategory(col('x', 'constructor'))).toBeUndefined()+ expect(columnCategory(col('x', 3))).toBeUndefined()+ expect(columnCategory(col('x', { evil: true }))).toBeUndefined()+ expect(columnCategory(undefined)).toBeUndefined()+ })++ it('labels every category', () => {+ expect(Object.keys(CATEGORY_LABELS).sort()).toEqual([...KANBAN_COLUMN_CATEGORIES].sort())+ })++ it('done and closed are the completed categories', () => {+ expect(KANBAN_COLUMN_CATEGORIES.filter(isCompletedCategory)).toEqual(['done', 'closed'])+ expect(isCompletedCategory(undefined)).toBe(false)+ })+})++describe('boardProgress', () => {+ it('counts live cards in done+closed columns over every live card, Ungrouped included', () => {+ // e is unassigned (Ungrouped) — unfinished work; `dead` is not a live card.+ expect(boardProgress(board(), ['a', 'b', 'c', 'd', 'e'])).toEqual({ complete: 2, total: 5 })+ })++ it('is null when no column says what "complete" means', () => {+ const k: ProjectKanban = {+ columns: [col('x'), col('y', 'started')],+ assignments: [{ nodeId: 'a', columnId: 'x' }]+ }+ expect(boardProgress(k, ['a'])).toBeNull()+ })++ it('is null for an empty board (0/0 is not progress)', () => {+ expect(boardProgress(board(), [])).toBeNull()+ })++ it('a dangling assignment is Ungrouped, not complete', () => {+ const k: ProjectKanban = { ...board(), assignments: [{ nodeId: 'a', columnId: 'deleted' }] }+ expect(boardProgress(k, ['a'])).toEqual({ complete: 0, total: 1 })+ })+})++describe('defaultCompletionColumnId', () => {+ it('prefers the first done column', () => {+ expect(defaultCompletionColumnId([col('a', 'done'), col('b', 'closed'), col('c', 'done')])).toBe('a')+ })++ it('falls back to the first closed column', () => {+ expect(defaultCompletionColumnId([col('a', 'started'), col('b', 'closed')])).toBe('b')+ })++ it('falls back to the last column when nothing is categorized (the old default)', () => {+ expect(defaultCompletionColumnId([col('a'), col('b')])).toBe('b')+ })++ it('is undefined with no columns', () => {+ expect(defaultCompletionColumnId([])).toBeUndefined()+ })+})++describe('categoryChangeImpact', () => {+ it('names the live cards a change would re-mean', () => {+ expect(categoryChangeImpact(board(), 'doing', 'done', ['a', 'b', 'c', 'd'])).toEqual({+ cards: 1,+ from: 'started',+ to: 'done'+ })+ })++ it('is null for an empty column — nothing to re-mean', () => {+ expect(categoryChangeImpact(board(), 'doing', 'done', ['a', 'c'])).toBeNull()+ })++ it('is null when the category does not actually change', () => {+ expect(categoryChangeImpact(board(), 'doing', 'started', ['b'])).toBeNull()+ })++ it('treats an unknown stored value as absent, so clearing it is not a change', () => {+ const k: ProjectKanban = { columns: [col('x', 'blocked')], assignments: [{ nodeId: 'a', columnId: 'x' }] }+ expect(categoryChangeImpact(k, 'x', undefined, ['a'])).toBeNull()+ expect(categoryChangeImpact(k, 'x', 'done', ['a'])).toEqual({ cards: 1, from: undefined, to: 'done' })+ })++ it('is null for an unknown column', () => {+ expect(categoryChangeImpact(board(), 'nope', 'done', ['a'])).toBeNull()+ })+})++describe('categoryChangeMessage', () => {+ it('says the cards will count as finished when a column becomes done', () => {+ const m = categoryChangeMessage('Review', { cards: 1, from: 'started', to: 'done' }, false)+ expect(m).toContain('"Review"')+ expect(m).toContain('Started')+ expect(m).toContain('Done')+ expect(m).toContain('1 card will count as finished')+ })++ it('says they will no longer count when a done column stops being one', () => {+ expect(categoryChangeMessage('Done', { cards: 3, from: 'done', to: undefined }, false)).toContain(+ '3 cards will no longer count as finished'+ )+ })++ it('warns that the cards disappear from view when a column becomes closed and closed is hidden', () => {+ const hidden = categoryChangeMessage('Old', { cards: 2, from: undefined, to: 'closed' }, true)+ expect(hidden).toContain('hidden')+ const shown = categoryChangeMessage('Old', { cards: 2, from: undefined, to: 'closed' }, false)+ expect(shown).not.toContain('hidden')+ })++ it('still names the count for a change between two unfinished categories', () => {+ expect(categoryChangeMessage('Q', { cards: 4, from: 'unstarted', to: 'started' }, false)).toContain('4 cards')+ })+})diff --git a/src/shared/kanban-category.ts b/src/shared/kanban-category.tsnew file mode 100644index 000000000..33e61fc90--- /dev/null+++ b/src/shared/kanban-category.ts@@ -0,0 +1,143 @@+/**+ * Column lifecycle categories — what a column MEANS, independent of what it is called.+ *+ * A board's columns are free-form ("Backlog", "Review", "Shipped"), so nothing could tell which of+ * them hold finished work. The optional `KanbanColumn.category` says it once, per column, and three+ * things read it: the board's progress (`boardProgress`), hiding `closed` columns behind a toggle,+ * and the default GitHub completion column (`defaultCompletionColumnId`).+ *+ * It lives in `shared` because the board is git-shared content read by the renderer, the core (the+ * relay's board verbs seed the default board) and — across the repo boundary — the phone, which+ * must at least tolerate the field.+ *+ * **Every reader goes through `columnCategory`.** The value comes from a hand-editable, git-shared+ * file, so a stored string outside the closed set (a typo, or a category a NEWER build added) reads+ * as ABSENT rather than being trusted, and a non-string never reaches a comparison. The value+ * itself is left in the file: dropping an unknown string on save would erase a newer build's data+ * from the shared file the moment an older teammate saved.+ */+import type { KanbanColumn, KanbanColumnCategory, ProjectKanban } from './types'++/** The closed set, in lifecycle order (the order the column menu lists them). */+export const KANBAN_COLUMN_CATEGORIES: readonly KanbanColumnCategory[] = [+ 'unstarted',+ 'started',+ 'done',+ 'closed'+]++/** Menu / chip wording for each category. */+export const CATEGORY_LABELS: Readonly<Record<KanbanColumnCategory, string>> = {+ unstarted: 'Not started',+ started: 'Started',+ done: 'Done',+ closed: 'Closed'+}++const KNOWN = new Set<string>(KANBAN_COLUMN_CATEGORIES)++/** The column's category, or undefined when absent, unknown or not a string. Never throws. */+export function columnCategory(+ col: Pick<KanbanColumn, 'category'> | { category?: unknown } | undefined | null+): KanbanColumnCategory | undefined {+ const c = (col as { category?: unknown } | undefined | null)?.category+ return typeof c === 'string' && KNOWN.has(c) ? (c as KanbanColumnCategory) : undefined+}++/** `done` and `closed` both mean "no work left here" — the numerator of the board's progress. */+export function isCompletedCategory(c: KanbanColumnCategory | undefined): boolean {+ return c === 'done' || c === 'closed'+}++/**+ * The board's progress: live cards sitting in a `done`/`closed` column over EVERY live card+ * (Ungrouped included — an unfiled card is unfinished work, not work that does not exist).+ *+ * Null when it would be meaningless: no column carries a completed category (the board has not+ * said what "complete" means, so any number would be invented), or there are no cards (0/0).+ * A dangling assignment (its column deleted elsewhere) is Ungrouped, as everywhere on the board.+ */+export function boardProgress(+ k: ProjectKanban,+ liveIds: readonly string[]+): { complete: number; total: number } | null {+ const completedCols = new Set(+ k.columns.filter((c) => isCompletedCategory(columnCategory(c))).map((c) => c.id)+ )+ if (completedCols.size === 0 || liveIds.length === 0) return null+ const live = new Set(liveIds)+ const complete = new Set(+ k.assignments+ .filter((a) => live.has(a?.nodeId) && completedCols.has(a.columnId))+ .map((a) => a.nodeId)+ ).size+ return { complete, total: live.size }+}++/**+ * The column a GitHub issue should close into by default: the first `done` column, else the first+ * `closed` one, else the LAST column — which is what the default was before categories existed, so+ * an uncategorized board keeps exactly its old behaviour.+ */+export function defaultCompletionColumnId(+ columns: ReadonlyArray<Pick<KanbanColumn, 'id' | 'category'>>+): string | undefined {+ return (+ columns.find((c) => columnCategory(c) === 'done')?.id ??+ columns.find((c) => columnCategory(c) === 'closed')?.id ??+ columns.at(-1)?.id+ )+}++/**+ * What changing a column's category would do to the cards already in it — or null when it would+ * do nothing (unknown column, no live cards in it, or no actual change).+ *+ * A category is not a label on the column, it is a claim about every card in it: moving "Review"+ * from `started` to `done` silently counts its cards as finished, and moving a column to `closed`+ * can hide its cards behind the "show closed" toggle. So the board refuses to do either SILENTLY:+ * a non-null answer means the UI must confirm, naming the count. An empty column changes freely.+ */+export function categoryChangeImpact(+ k: ProjectKanban,+ columnId: string,+ next: KanbanColumnCategory | undefined,+ liveIds: readonly string[]+): { cards: number; from: KanbanColumnCategory | undefined; to: KanbanColumnCategory | undefined } | null {+ const column = k.columns.find((c) => c.id === columnId)+ if (!column) return null+ const from = columnCategory(column)+ const to = columnCategory({ category: next })+ if (from === to) return null+ const live = new Set(liveIds)+ const cards = new Set(+ k.assignments.filter((a) => a?.columnId === columnId && live.has(a.nodeId)).map((a) => a.nodeId)+ ).size+ return cards > 0 ? { cards, from, to } : null+}++/**+ * The confirmation sentence for a category change that would re-mean cards (`categoryChangeImpact`+ * answered non-null). It names the column, the before/after and the COUNT, then the consequence+ * the user cannot see from the menu: the progress numerator moving, or the cards leaving view+ * when the column becomes `closed` while this user hides closed columns.+ */+export function categoryChangeMessage(+ title: string,+ impact: { cards: number; from: KanbanColumnCategory | undefined; to: KanbanColumnCategory | undefined },+ closedHidden: boolean+): string {+ const name = (c: KanbanColumnCategory | undefined): string => (c ? CATEGORY_LABELS[c] : 'No category')+ const n = `${impact.cards} card${impact.cards === 1 ? '' : 's'}`+ const head = `Change "${title}" from ${name(impact.from)} to ${name(impact.to)}?`+ const wasDone = isCompletedCategory(impact.from)+ const nowDone = isCompletedCategory(impact.to)+ const effects: string[] = []+ if (nowDone && !wasDone) effects.push(`Its ${n} will count as finished in the board's progress.`)+ else if (wasDone && !nowDone) effects.push(`Its ${n} will no longer count as finished.`)+ else effects.push(`This changes what the column means for its ${n}.`)+ if (impact.to === 'closed' && closedHidden) {+ effects.push('Closed columns are hidden on your board, so the column and its cards will leave view.')+ }+ return [head, ...effects].join(' ')+}diff --git a/src/shared/kanban-default-board.test.ts b/src/shared/kanban-default-board.test.tsindex f95f9d453..c95680897 100644--- a/src/shared/kanban-default-board.test.ts+++ b/src/shared/kanban-default-board.test.ts@@ -20,6 +20,13 @@ describe('DEFAULT_BOARD_COLUMNS', () => {])expect(DEFAULT_BOARD_COLUMNS.map((c) => c.color)).toEqual(['#0a84ff', '#ffd60a', '#32d74b'])})++ // The lifecycle category is ADDITIVE to the cross-surface contract: the phone's copy may lack it+ // (a board it seeds simply has uncategorized columns, which every reader tolerates), but a board+ // born on the desktop or through the relay knows which column holds finished work.+ it('maps them onto the lifecycle: unstarted / started / done', () => {+ expect(DEFAULT_BOARD_COLUMNS.map((c) => c.category)).toEqual(['unstarted', 'started', 'done'])+ })})describe('makeColumnId', () => {diff --git a/src/shared/kanban-default-board.ts b/src/shared/kanban-default-board.tsindex 01810920e..3eb30f8cd 100644--- a/src/shared/kanban-default-board.ts+++ b/src/shared/kanban-default-board.ts@@ -8,25 +8,40 @@* and, across the repo boundary, nodeterm-ios `KanbanDefaults` (which cannot import this file and* therefore copies it verbatim under a pinning test).*- * Only the TITLES, their ORDER and their COLORS are shared. Column ids are minted per board and are+ * Only the TITLES, their ORDER, their COLORS and their lifecycle CATEGORY are shared (the category+ * is additive: a surface whose copy lacks it seeds uncategorized columns, which every reader+ * tolerates — see @shared/kanban-category). Column ids are minted per board and are* deliberately random: a board is created exactly once, by whichever surface got there first, and* every later reader addresses columns by the ids that board carries — so two surfaces agreeing on* an id would buy nothing and a fixed id would collide across projects.*/import { SYSTEM_NODE_COLORS } from './node-colors'+import type { KanbanColumn, KanbanColumnCategory } from './types'export interface DefaultBoardColumn {title: stringcolor: string+ category: KanbanColumnCategory}/** The three starting columns, in board order. */export const DEFAULT_BOARD_COLUMNS: readonly DefaultBoardColumn[] = [- { title: 'To Do', color: SYSTEM_NODE_COLORS[0] },- { title: 'In Progress', color: SYSTEM_NODE_COLORS[2] },- { title: 'Done', color: SYSTEM_NODE_COLORS[1] }+ { title: 'To Do', color: SYSTEM_NODE_COLORS[0], category: 'unstarted' },+ { title: 'In Progress', color: SYSTEM_NODE_COLORS[2], category: 'started' },+ { title: 'Done', color: SYSTEM_NODE_COLORS[1], category: 'done' }] as const+/** The default columns with freshly minted ids — the ONE place a seeded column's shape is spelled,+ * so the renderer's lazy default and the core's relay seeding cannot drift apart. */+export function defaultBoardColumns(mintId: () => string = makeColumnId): KanbanColumn[] {+ return DEFAULT_BOARD_COLUMNS.map((c) => ({+ id: mintId(),+ title: c.title,+ color: c.color,+ category: c.category+ }))+}+/*** A column id in the desktop's shape: `kcol-<8 chars of base36>`.*diff --git a/src/shared/types.ts b/src/shared/types.tsindex fcd8467f4..4c69f9bb0 100644--- a/src/shared/types.ts+++ b/src/shared/types.ts@@ -616,11 +616,19 @@ export interface BridgeLink {target: string}+/** Where a column sits in a card's lifecycle (see @shared/kanban-category). A closed set; an+ * unknown value read from a hand-edited or newer file reads as ABSENT (`columnCategory`), and is+ * left in the file untouched so a newer build's value survives an older build's save. */+export type KanbanColumnCategory = 'unstarted' | 'started' | 'done' | 'closed'+/** One kanban board column. Column order = array order in ProjectKanban.columns. */export interface KanbanColumn {id: stringtitle: stringcolor: string+ /** Optional lifecycle category. Absent = uncategorized (the pre-category board, and any column+ * the user never categorized). Read it through `columnCategory`, never directly. */+ category?: KanbanColumnCategory}/** Assignment of one session node to a board column. A session with no assignment sits