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): transient Running / Needs you / Unread filter chips

review2bedebf887ed
diff --git a/src/renderer/components/kanban/KanbanView.statusChips.test.tsx b/src/renderer/components/kanban/KanbanView.statusChips.test.tsx
new file mode 100644
index 000000000..2b92c3085
--- /dev/null
+++ b/src/renderer/components/kanban/KanbanView.statusChips.test.tsx
@@ -0,0 +1,144 @@
+// @vitest-environment jsdom
+//
+// The transient Running / Needs you / Unread chips: derived from the agent-status store, OR'd
+// together, and NEVER persisted — a filter on second-by-second state that survived a restart would
+// show a wrong board before anyone had looked at it.
+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 { useAgentStatus } from '../../state/agentStatus'
+
+vi.mock('../../session/session', () => ({
+ useSession: () => ({ source: 'local', api: window.nodeTerminal })
+}))
+
+let root: Root | null = null
+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: 'col', title: 'Work', color: '#0a84ff' }],
+ assignments: [
+ { nodeId: 'a', columnId: 'col' },
+ { nodeId: 'b', columnId: 'col' },
+ { nodeId: 'c', columnId: 'col' }
+ ]
+})
+
+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 () => {} }
+ }
+ useAgentStatus.setState({
+ byId: {
+ a: { unread: false, state: 'working' },
+ b: { unread: true, state: 'waiting' }
+ }
+ } as never)
+})
+afterEach(() => {
+ if (root) act(() => root!.unmount())
+ root = null
+ host?.remove()
+ document.body.innerHTML = ''
+ useAgentStatus.setState({ byId: {} } as never)
+ vi.unstubAllGlobals()
+})
+
+function mount(): void {
+ host = document.createElement('div')
+ document.body.appendChild(host)
+ root = createRoot(host)
+ const noop = (): void => {}
+ act(() =>
+ root!.render(
+ <KanbanView
+ board={board()}
+ sessions={['a', 'b', 'c'].map(card)}
+ onChange={noop}
+ onOpenNode={noop}
+ onCreateNode={noop}
+ onRenameNode={noop}
+ onEditSticky={noop}
+ onDeleteNode={noop}
+ onModalNodeChange={noop}
+ onBrowserNav={noop}
+ onSetIcon={noop}
+ />
+ )
+ )
+}
+
+const visible = (): string[] =>
+ [...document.querySelectorAll('.kanban-card--session .kanban-card__title')].map((el) => el.textContent ?? '')
+
+const chip = (label: string): HTMLElement =>
+ [...document.querySelectorAll<HTMLElement>('.kanban-status-chip')].find((el) =>
+ el.textContent?.startsWith(label)
+ )!
+
+const click = (el: Element): void => {
+ act(() => {
+ el.dispatchEvent(new MouseEvent('click', { bubbles: true }))
+ })
+}
+
+const storageSnapshot = (): Record<string, string | null> => {
+ const out: Record<string, string | null> = {}
+ for (let i = 0; i < localStorage.length; i++) {
+ const k = localStorage.key(i)!
+ out[k] = localStorage.getItem(k)
+ }
+ return out
+}
+
+describe('KanbanView — status chips', () => {
+ it('shows a count per chip, derived from the agent-status store', () => {
+ mount()
+ expect(chip('Running').textContent).toContain('1')
+ expect(chip('Needs you').textContent).toContain('1')
+ expect(chip('Unread').textContent).toContain('1')
+ })
+
+ it('one chip narrows the board; two are an OR', () => {
+ mount()
+ click(chip('Running'))
+ expect(visible()).toEqual(['Card a'])
+ click(chip('Unread'))
+ expect(visible()).toEqual(['Card a', 'Card b'])
+ })
+
+ it('follows the store live (a card that stops running leaves the Running view)', () => {
+ mount()
+ click(chip('Running'))
+ act(() => useAgentStatus.setState({ byId: { a: { unread: false, state: 'done' } } } as never))
+ expect(visible()).toEqual([])
+ })
+
+ it('is never persisted: no storage write, and a remount starts unfiltered', () => {
+ mount()
+ const before = storageSnapshot()
+ click(chip('Running'))
+ click(chip('Needs you'))
+ expect(storageSnapshot()).toEqual(before)
+ act(() => root!.unmount())
+ root = null
+ host.remove()
+ mount()
+ expect(visible()).toEqual(['Card a', 'Card b', 'Card c'])
+ expect(document.querySelector('.kanban-status-chip--on')).toBeNull()
+ })
+})
diff --git a/src/renderer/components/kanban/KanbanView.tsx b/src/renderer/components/kanban/KanbanView.tsx
index 9500fe1d4..996ac57ae 100644
--- a/src/renderer/components/kanban/KanbanView.tsx
+++ b/src/renderer/components/kanban/KanbanView.tsx
@@ -4,6 +4,10 @@ import {
boardProgress, categoryChangeImpact, categoryChangeMessage, columnCategory
} from '@shared/kanban-category'
import { useKanbanDisplay } from '../../state/kanbanDisplay'
+import {
+ STATUS_CHIPS, chipCounts, matchesStatusChips, parseStatusChipSig, statusChipSig,
+ type StatusChip, type StatusChipCard
+} from '../../lib/kanbanStatusChips'
import type { NodeIcon } from '@shared/node-icon'
import { AGENT_CONFIG, BUILTIN_AGENT_IDS, type AgentId } from '@shared/agents/config'
import { useViewMode } from '../../state/viewMode'
@@ -159,6 +163,9 @@ export const KanbanView = memo(function KanbanView({
// show everything; otherwise a card must carry at least one selected label (cardMatchesLabelFilter).
const [labelFilter, setLabelFilter] = useState<string[]>([])
const [filterOpen, setFilterOpen] = useState(false)
+ // Status chips (Running / Needs you / Unread) — TRANSIENT component state, never persisted and
+ // never part of a saved view: they filter on second-by-second agent state (lib/kanbanStatusChips).
+ const [statusChips, setStatusChips] = useState<StatusChip[]>([])
const [source, setSource] = useState<KanbanSource>('all')
// One GitHub summary modal for both kinds; the kind decides whether it offers a move.
const [modalIssue, setModalIssue] = useState<
@@ -258,6 +265,7 @@ export const KanbanView = memo(function KanbanView({
useEffect(() => {
setSource('all')
setModalIssue(null)
+ setStatusChips([])
}, [projectId])
useEffect(() => {
if (!modalIssue || !github) return
@@ -298,6 +306,15 @@ export const KanbanView = memo(function KanbanView({
)
const byId = useMemo(() => new Map(sessions.map((s) => [s.id, s])), [sessions])
const sessionIds = useMemo(() => sessions.map((s) => s.id), [sessions])
+ // The chips' facts through a DERIVED SIGNATURE (a primitive that changes only when a card's
+ // running / needs-you / unread fact does) — never `byId`, which changes on every hook event of
+ // every node and would re-render the whole board each time.
+ const chipCards = useMemo<StatusChipCard[]>(() => sessions.map((s) => ({ id: s.id, kind: s.kind })), [sessions])
+ const statusSig = useAgentStatus((st) => statusChipSig(st.byId, chipCards))
+ const statusFacts = useMemo(() => parseStatusChipSig(statusSig), [statusSig])
+ const statusCounts = useMemo(() => chipCounts(statusFacts), [statusFacts])
+ const toggleStatusChip = (chip: StatusChip): void =>
+ setStatusChips((cur) => (cur.includes(chip) ? cur.filter((c) => c !== chip) : [...cur, chip]))
// Stable per-card label arrays: labelsForCard allocates a fresh array per call, and that
// identity churn alone would defeat SessionCard's memo. Recomputed only on a board change.
@@ -390,8 +407,15 @@ export const KanbanView = memo(function KanbanView({
// them per column — and their identities hold across renders that change neither the board,
// the sessions, nor the filter, which is what lets the memoized columns skip.
const columnCards = useMemo(() => {
+ // Label filter AND status chips (each an OR within itself).
const vis = (ids: string[]): string[] =>
- activeLocalFilter.length ? ids.filter((id) => cardMatchesLabelFilter(board, id, activeLocalFilter)) : ids
+ activeLocalFilter.length || statusChips.length
+ ? ids.filter(
+ (id) =>
+ (!activeLocalFilter.length || cardMatchesLabelFilter(board, id, activeLocalFilter)) &&
+ matchesStatusChips(statusFacts, id, statusChips)
+ )
+ : ids
const toCards = (ids: string[]): KanbanSession[] => {
const cards = ids.flatMap((id) => (byId.has(id) ? [byId.get(id)!] : []))
return cards.length ? cards : NO_CARDS
@@ -400,7 +424,7 @@ export const KanbanView = memo(function KanbanView({
ungrouped: toCards(vis(unassigned(board, sessionIds))),
byColumn: new Map(board.columns.map((c) => [c.id, toCards(vis(assignedTo(board, c.id)))]))
}
- }, [board, byId, sessionIds, activeLocalFilter])
+ }, [board, byId, sessionIds, activeLocalFilter, statusChips, statusFacts])
// 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.
@@ -645,6 +669,23 @@ export const KanbanView = memo(function KanbanView({
Showing the most recently updated pull requests only.
</span>
)}
+ <div className="kanban-status-chips" role="group" aria-label="Filter by agent status">
+ {STATUS_CHIPS.map(({ id, label }) => {
+ const on = statusChips.includes(id)
+ return (
+ <button
+ key={id}
+ className={`kanban-status-chip kanban-status-chip--${id}${on ? ' kanban-status-chip--on' : ''}`}
+ aria-pressed={on}
+ title={`Show only ${label.toLowerCase()} sessions (not saved — this follows live agent state)`}
+ onClick={() => toggleStatusChip(id)}
+ >
+ {label}
+ <span className="kanban-status-chip__count">{statusCounts[id]}</span>
+ </button>
+ )
+ })}
+ </div>
{(paletteLabels.length > 0 || githubLabels.length > 0 || activeFilter.length > 0) && (
<div className="kanban-header__filter">
<button
diff --git a/src/renderer/components/kanban/SessionCard.tsx b/src/renderer/components/kanban/SessionCard.tsx
index f31e167ac..25a2df124 100644
--- a/src/renderer/components/kanban/SessionCard.tsx
+++ b/src/renderer/components/kanban/SessionCard.tsx
@@ -8,6 +8,7 @@ import { NodeIconView } from '../NodeIcon'
import { LabelChips } from './LabelChips'
import { PRIORITIES } from './CardMetaBar'
import type { KanbanSession } from './KanbanView'
+import { cardBadge } from '../../lib/kanbanStatusChips'
const PRIO_COLOR = Object.fromEntries(PRIORITIES.map((p) => [p.id, p.color])) as Record<KanbanPriority, string>
@@ -50,26 +51,11 @@ export const SessionCard = memo(function SessionCard({
const r = (e.currentTarget as HTMLElement).getBoundingClientRect()
return e.clientY < r.top + r.height / 2 ? 'before' : 'after'
}
- // The board is the canvas's other view of the same sessions, and it reads the same store — so
- // SLEEPING (Eco: the agent CLI was exited to reclaim its RAM) is one more branch here, not a
- // follow-up. Ranked last: a hibernated node is idle by definition, so `working`/`waiting` can
- // only mean the wake already landed and the hooks are ahead of the flag.
- // DROPPED (the CLI died unannounced — see terminal/agent-liveness.ts) is ranked FIRST: it is the
- // strongest claim on the card, and it cannot actually collide with the others, since the verdict
- // is only ever raised on a `done` node that is neither paused nor hibernated. Ordering it here is
- // about which sentence a reader of this chain meets first, not about resolving a conflict.
- const badge =
- session.kind !== 'sticky' && status?.dropped
- ? 'dropped'
- : session.kind !== 'sticky' && status?.state === 'working'
- ? 'running'
- : session.kind !== 'sticky' && (status?.state === 'waiting' || status?.state === 'blocked')
- ? 'needs'
- : session.kind !== 'sticky' && status?.paused
- ? 'paused'
- : session.kind !== 'sticky' && status?.hibernated
- ? 'sleeping'
- : null
+ // The board is the canvas's other view of the same sessions and reads the same store, so the
+ // node's pause/liveness chips (DROPPED, PAUSED, SLEEPING) are badges here too.
+ // The ONE badge rule, shared with the board's status chips (lib/kanbanStatusChips), so a chip
+ // can never select cards whose badge says something else. The ranking and its reasons live there.
+ const badge = cardBadge(session.kind, status)
const stickyPreview = session.kind === 'sticky' ? (session.text ?? '').trim() : ''
const assignees = meta?.assignees ?? []
const due = meta?.dueAt
diff --git a/src/renderer/lib/kanbanStatusChips.test.ts b/src/renderer/lib/kanbanStatusChips.test.ts
new file mode 100644
index 000000000..93c048431
--- /dev/null
+++ b/src/renderer/lib/kanbanStatusChips.test.ts
@@ -0,0 +1,97 @@
+import { describe, expect, it } from 'vitest'
+import type { AgentNodeStatus } from '../state/agentStatus'
+import {
+ STATUS_CHIPS,
+ cardBadge,
+ chipCounts,
+ matchesStatusChips,
+ parseStatusChipSig,
+ statusChipSig,
+ type StatusChipCard
+} from './kanbanStatusChips'
+
+const st = (s: Partial<AgentNodeStatus>): AgentNodeStatus => ({ unread: false, ...s })
+
+describe('cardBadge — the ONE badge rule the card and the chips share', () => {
+ it('ranks dropped > running > needs > paused > sleeping', () => {
+ expect(cardBadge('terminal', st({ dropped: true, state: 'working' }))).toBe('dropped')
+ expect(cardBadge('terminal', st({ state: 'working' }))).toBe('running')
+ expect(cardBadge('terminal', st({ state: 'waiting' }))).toBe('needs')
+ expect(cardBadge('terminal', st({ state: 'blocked' }))).toBe('needs')
+ expect(cardBadge('terminal', st({ paused: true }))).toBe('paused')
+ expect(cardBadge('terminal', st({ hibernated: true }))).toBe('sleeping')
+ expect(cardBadge('terminal', st({ state: 'done' }))).toBeNull()
+ expect(cardBadge('terminal', undefined)).toBeNull()
+ })
+
+ it('a sticky note never carries a status badge', () => {
+ expect(cardBadge('sticky', st({ state: 'working' }))).toBeNull()
+ })
+})
+
+describe('statusChipSig — a derived signature, never the whole byId map', () => {
+ const cards: StatusChipCard[] = [
+ { id: 'a', kind: 'terminal' },
+ { id: 'b', kind: 'terminal' },
+ { id: 'c', kind: 'sticky' }
+ ]
+
+ it('changes only when a chip-relevant fact changes', () => {
+ const one = statusChipSig({ a: st({ state: 'working', stateAt: 1, lastEventAt: 1 }) }, cards)
+ // Same facts, different freshness clocks and unrelated fields: the board must NOT re-render.
+ const two = statusChipSig(
+ { a: st({ state: 'working', stateAt: 99, lastEventAt: 42, session: 'renamed' }) },
+ cards
+ )
+ expect(two).toBe(one)
+ expect(statusChipSig({ a: st({ state: 'waiting' }) }, cards)).not.toBe(one)
+ })
+
+ it('ignores nodes that are not cards on this board', () => {
+ expect(statusChipSig({ zzz: st({ state: 'working', unread: true }) }, cards)).toBe('')
+ })
+
+ it('round-trips through the parser', () => {
+ const facts = parseStatusChipSig(
+ statusChipSig(
+ {
+ a: st({ state: 'working' }),
+ b: st({ state: 'blocked', unread: true }),
+ c: st({ unread: true })
+ },
+ cards
+ )
+ )
+ expect([...facts.running]).toEqual(['a'])
+ expect([...facts.needs]).toEqual(['b'])
+ expect([...facts.unread].sort()).toEqual(['b', 'c'])
+ })
+
+ it('a dropped agent is not "running" even if its last state said so', () => {
+ const facts = parseStatusChipSig(statusChipSig({ a: st({ state: 'working', dropped: true }) }, cards))
+ expect(facts.running.size).toBe(0)
+ })
+})
+
+describe('matchesStatusChips', () => {
+ const facts = parseStatusChipSig('a:r..|b:.nu|')
+
+ it('no active chip matches everything', () => {
+ expect(matchesStatusChips(facts, 'zzz', [])).toBe(true)
+ })
+
+ it('is an OR over the active chips', () => {
+ expect(matchesStatusChips(facts, 'a', ['running'])).toBe(true)
+ expect(matchesStatusChips(facts, 'b', ['running'])).toBe(false)
+ expect(matchesStatusChips(facts, 'b', ['running', 'unread'])).toBe(true)
+ expect(matchesStatusChips(facts, 'zzz', ['needs'])).toBe(false)
+ })
+
+ it('counts per chip', () => {
+ expect(chipCounts(facts)).toEqual({ running: 1, needs: 1, unread: 1 })
+ })
+
+ it('names the three chips in order', () => {
+ expect(STATUS_CHIPS.map((c) => c.label)).toEqual(['Running', 'Needs you', 'Unread'])
+ })
+})
diff --git a/src/renderer/lib/kanbanStatusChips.ts b/src/renderer/lib/kanbanStatusChips.ts
new file mode 100644
index 000000000..91dfc6b0c
--- /dev/null
+++ b/src/renderer/lib/kanbanStatusChips.ts
@@ -0,0 +1,97 @@
+/**
+ * The board's transient status filter chips — Running / Needs you / Unread — and the ONE badge
+ * rule the session card and the chips both read, so a chip can never select cards whose badge
+ * says something else.
+ *
+ * Two rules come with it:
+ *
+ * 1. **Derived signature, never `byId`.** The board subscribes to `statusChipSig(byId, cards)`, a
+ * primitive string that changes only when a chip-relevant fact of a card ON THIS BOARD changes.
+ * Subscribing to the map would re-render the whole board on every hook event of every node —
+ * the churn Canvas's `armedDepSig` / `loopSig` exist to avoid.
+ * 2. **Never persisted.** The chips filter on second-by-second agent state. A filter like that
+ * surviving a restart (or a saved view carrying it) shows a board that is wrong before anyone
+ * has looked at it, so the chips live in component state and nowhere else.
+ */
+import type { AgentNodeStatus } from '../state/agentStatus'
+
+export type StatusChip = 'running' | 'needs' | 'unread'
+
+export const STATUS_CHIPS: ReadonlyArray<{ id: StatusChip; label: string }> = [
+ { id: 'running', label: 'Running' },
+ { id: 'needs', label: 'Needs you' },
+ { id: 'unread', label: 'Unread' }
+]
+
+export type CardBadge = 'dropped' | 'running' | 'needs' | 'paused' | 'sleeping'
+
+/**
+ * The status badge a session card shows. DROPPED ranks first (the CLI died unannounced — the
+ * strongest claim on the card, and only ever raised on a `done` node, so it cannot actually
+ * collide with the others); SLEEPING last (a hibernated node is idle by definition, so `working`
+ * or `waiting` there can only mean the wake landed and the hooks are ahead of the flag). A sticky
+ * note has no agent and never carries one.
+ */
+export function cardBadge(kind: string, status: AgentNodeStatus | undefined): CardBadge | null {
+ if (kind === 'sticky' || !status) return null
+ if (status.dropped) return 'dropped'
+ if (status.state === 'working') return 'running'
+ if (status.state === 'waiting' || status.state === 'blocked') return 'needs'
+ if (status.paused) return 'paused'
+ if (status.hibernated) return 'sleeping'
+ return null
+}
+
+export interface StatusChipCard {
+ id: string
+ kind: string
+}
+
+/** One entry per card with at least one chip fact: `id:` + `r|.` `n|.` `u|.` + `|`. */
+export function statusChipSig(
+ byId: Readonly<Record<string, AgentNodeStatus | undefined>>,
+ cards: readonly StatusChipCard[]
+): string {
+ let sig = ''
+ for (const card of cards) {
+ const status = byId[card.id]
+ if (!status) continue
+ const badge = cardBadge(card.kind, status)
+ const r = badge === 'running'
+ const n = badge === 'needs'
+ const u = !!status.unread
+ if (!r && !n && !u) continue
+ sig += `${card.id}:${r ? 'r' : '.'}${n ? 'n' : '.'}${u ? 'u' : '.'}|`
+ }
+ return sig
+}
+
+export interface StatusChipFacts {
+ running: Set<string>
+ needs: Set<string>
+ unread: Set<string>
+}
+
+export function parseStatusChipSig(sig: string): StatusChipFacts {
+ const facts: StatusChipFacts = { running: new Set(), needs: new Set(), unread: new Set() }
+ for (const entry of sig.split('|')) {
+ const colon = entry.lastIndexOf(':')
+ if (colon <= 0) continue
+ const id = entry.slice(0, colon)
+ const flags = entry.slice(colon + 1)
+ if (flags[0] === 'r') facts.running.add(id)
+ if (flags[1] === 'n') facts.needs.add(id)
+ if (flags[2] === 'u') facts.unread.add(id)
+ }
+ return facts
+}
+
+/** Does this card pass the active chips? No chip = everything; several = any of them (OR). */
+export function matchesStatusChips(facts: StatusChipFacts, id: string, active: readonly StatusChip[]): boolean {
+ if (!active.length) return true
+ return active.some((chip) => facts[chip].has(id))
+}
+
+export function chipCounts(facts: StatusChipFacts): Record<StatusChip, number> {
+ return { running: facts.running.size, needs: facts.needs.size, unread: facts.unread.size }
+}
diff --git a/src/renderer/styles.css b/src/renderer/styles.css
index 746dc708f..47def20ed 100644
--- a/src/renderer/styles.css
+++ b/src/renderer/styles.css
@@ -11974,6 +11974,52 @@ button.group-node__setup:disabled {
color: var(--accent);
}
+/* ── Board status chips (header) — transient filters on live agent state ── */
+.kanban-status-chips {
+ display: inline-flex;
+ align-items: center;
+ gap: 4px;
+ margin-left: 8px;
+}
+.kanban-status-chip {
+ display: inline-flex;
+ align-items: center;
+ gap: 5px;
+ background: transparent;
+ border: 1px solid rgba(var(--tint-rgb), 0.12);
+ border-radius: 999px;
+ color: rgba(var(--tint-rgb), 0.65);
+ font-size: 11px;
+ padding: 2px 8px;
+ cursor: pointer;
+ white-space: nowrap;
+}
+.kanban-status-chip:hover {
+ color: var(--text-strong);
+ background: rgba(var(--tint-rgb), 0.06);
+}
+.kanban-status-chip__count {
+ font-variant-numeric: tabular-nums;
+ color: rgba(var(--tint-rgb), 0.45);
+}
+.kanban-status-chip--on {
+ border-color: var(--accent);
+ color: var(--text-strong);
+ background: color-mix(in srgb, var(--accent) 12%, transparent);
+}
+.kanban-status-chip--running.kanban-status-chip--on {
+ border-color: var(--state-working);
+ background: color-mix(in srgb, var(--state-working) 14%, transparent);
+}
+.kanban-status-chip--needs.kanban-status-chip--on {
+ border-color: var(--state-attention);
+ background: color-mix(in srgb, var(--state-attention) 14%, transparent);
+}
+.kanban-status-chip--unread.kanban-status-chip--on {
+ border-color: var(--state-unread);
+ background: color-mix(in srgb, var(--state-unread) 14%, transparent);
+}
+
/* ── Board label filter (header) ── */
.kanban-header__filter {
position: relative;