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
import { describe, expect, it } from 'vitest'
import {
parseTeamProgressSig,
stationKind,
stationsByOpener,
summarizeTeam,
teamProgressSig,
teamProgressText,
type StationNodeLike,
type TeamStation
} from './teamProgress'
import type { AgentNodeStatus } from '../state/agentStatus'
import { markLegacyWaitRopes, missingDepRopes, pruneRopes, waitRopeId } from './edgeModel'
const term = (id: string, extra: Partial<StationNodeLike> = {}): StationNodeLike => ({
id,
kind: 'terminal',
title: id.toUpperCase(),
agentId: 'claude',
...extra
})
const rope = (source: string, target: string) => ({ id: `ctrl-${source}-${target}`, source, target })
const wait = (source: string, target: string) => ({ id: waitRopeId(source, target), source, target })
/**
* The ropes as the LIVE canvas holds them, in the order its effects run: load (legacy waits
* re-marked) → heal (`missingDepRopes`) → prune against the nodes still on the canvas. Every
* scenario below goes through this before `stationsByOpener`, because the canvas's prune is what
* broke the old "first rope is the opener" rule.
*/
function canvasRopes(
fileRopes: ReturnType<typeof rope>[],
nodes: { id: string; data: { pendingLaunch?: { after: string[]; command: string } } }[]
): ReturnType<typeof rope>[] {
const restored = markLegacyWaitRopes(fileRopes)
const held = [...restored, ...missingDepRopes(nodes, restored)]
return pruneRopes(held, new Set(nodes.map((n) => n.id)))
}
const live = (id: string, after?: string[]) =>
({ id, data: after ? { pendingLaunch: { after, command: 'go' } } : {} })
const st = (patch: Partial<AgentNodeStatus>): AgentNodeStatus => ({ unread: false, ...patch }) as AgentNodeStatus
describe('stationsByOpener', () => {
it('groups the rope targets under the node that opened them, in rope order', () => {
const map = stationsByOpener([rope('o', 'a'), rope('o', 'b')], [term('o'), term('a'), term('b')])
expect(map.get('o')?.map((s) => s.id)).toEqual(['a', 'b'])
expect(map.get('o')?.[0]).toEqual({ id: 'a', title: 'A', agentId: 'claude', queued: false })
})
it('a wait rope is never an opener (pipeline as the canvas mints it)', () => {
// o opened a, b, c; b waits on a, c waits on b.
const ropes = [rope('o', 'a'), rope('o', 'b'), wait('a', 'b'), rope('o', 'c'), wait('b', 'c')]
const map = stationsByOpener(ropes, [term('o'), term('a'), term('b'), term('c')])
expect(map.get('o')?.map((s) => s.id)).toEqual(['a', 'b', 'c'])
expect(map.has('a')).toBe(false)
expect(map.has('b')).toBe(false)
})
it('a deleted opener in an UNPRUNED stored file does not hand its station to a later rope', () => {
// The Omni board reads the store's copy, which keeps ropes to deleted nodes until a canvas
// load prunes them — the first rope still claims its target there.
const map = stationsByOpener([rope('gone', 'a'), rope('b', 'a')], [term('a'), term('b')])
expect(map.size).toBe(0)
})
it('a deleted station is not a station', () => {
const ropes = [rope('o', 'a'), rope('o', 'gone'), wait('a', 'gone')]
const map = stationsByOpener(ropes, [term('o'), term('a')])
expect(map.get('o')?.map((s) => s.id)).toEqual(['a'])
expect(map.has('a')).toBe(false)
})
it('only session nodes are stations (a browser popup rope is lineage, not a team member)', () => {
const map = stationsByOpener(
[rope('o', 'web'), rope('o', 'note'), rope('o', 'a')],
[term('o'), { id: 'web', kind: 'browser' }, { id: 'note', kind: 'sticky' }, term('a')]
)
expect(map.get('o')?.map((s) => s.id)).toEqual(['a'])
})
it('carries the held launch as `queued`', () => {
const map = stationsByOpener([rope('o', 'a')], [term('o'), term('a', { queued: true })])
expect(map.get('o')?.[0].queued).toBe(true)
})
it('reuses the previous arrays and map when nothing changed', () => {
const nodes = [term('o'), term('a'), term('p'), term('b')]
const ropes = [rope('o', 'a'), rope('p', 'b')]
const first = stationsByOpener(ropes, nodes)
const again = stationsByOpener(ropes, nodes.map((n) => ({ ...n })), first)
expect(again).toBe(first)
const renamed = stationsByOpener(ropes, [term('o'), term('a', { title: 'new' }), term('p'), term('b')], first)
expect(renamed).not.toBe(first)
expect(renamed.get('p')).toBe(first.get('p'))
expect(renamed.get('o')).not.toBe(first.get('o'))
})
it('a dropped group changes the map identity', () => {
const first = stationsByOpener([rope('o', 'a')], [term('o'), term('a')])
expect(stationsByOpener([], [term('o'), term('a')], first)).not.toBe(first)
})
it('hostile ropes and nodes from a hand-edited project.json never throw', () => {
const hostile: unknown[] = [
null,
5,
'ctrl-o-a',
[],
{ source: {}, target: 'a' },
{ source: 'o', target: 7 },
{ source: '', target: 'a' },
{ source: 'o', target: 'o' },
{ source: '__proto__', target: 'constructor' },
{ source: 'o', target: 'a', id: { evil: true } },
Object.create(null)
]
const nodes = [
term('o'),
term('a', { title: { toString: () => 'x' }, agentId: 42 }),
term('__proto__'),
term('constructor'),
{ id: 5, kind: 'terminal' },
null as unknown as StationNodeLike
]
for (const ropes of [hostile, 'nope', { length: 3 }, null, undefined, 12]) {
expect(() => stationsByOpener(ropes, nodes)).not.toThrow()
}
const map = stationsByOpener(hostile, nodes)
expect(map.get('o')).toEqual([{ id: 'a', title: '', queued: false }])
expect(map.get('__proto__')?.map((s) => s.id)).toEqual(['constructor'])
expect(() => stationsByOpener([rope('o', 'a')], 'nodes' as never)).not.toThrow()
})
})
describe('stationKind', () => {
const s = (patch: Partial<TeamStation> = {}): TeamStation => ({ id: 'a', title: 'A', agentId: 'claude', queued: false, ...patch })
it('maps each hook state', () => {
expect(stationKind(s(), st({ state: 'done' }))).toBe('done')
expect(stationKind(s(), st({ state: 'working' }))).toBe('working')
expect(stationKind(s(), st({ state: 'waiting' }))).toBe('needs')
expect(stationKind(s(), st({ state: 'blocked' }))).toBe('needs')
expect(stationKind(s(), st({ state: 'done', lastTurnError: { at: 1 } }))).toBe('errored')
expect(stationKind(s(), st({ state: 'done', dropped: true }))).toBe('dropped')
})
it('unknown is unknown — never done — for an agent that can report', () => {
expect(stationKind(s(), undefined)).toBe('unknown')
expect(stationKind(s(), st({}))).toBe('unknown')
})
it('a node that can never report is untracked, not unknown', () => {
expect(stationKind(s({ agentId: undefined }), undefined)).toBe('untracked')
expect(stationKind(s({ agentId: 'custom:nohooks' }), undefined)).toBe('untracked')
// …unless the store has seen it run a reporting agent (a hand-launched claude in a plain terminal).
expect(stationKind(s({ agentId: undefined }), st({ agentId: 'claude' }))).toBe('unknown')
expect(stationKind(s({ agentId: undefined }), st({ state: 'done' }))).toBe('done')
})
it('paused / hibernated survive a restart as a finished turn', () => {
expect(stationKind(s(), st({ paused: true }))).toBe('paused')
expect(stationKind(s(), st({ hibernated: true }))).toBe('paused')
})
it('a CLI that announced its exit is ended — not unknown, so the ring can complete', () => {
expect(stationKind(s(), st({ sessionEnded: true }))).toBe('ended')
expect(summarizeTeam(['done', 'ended'])).toMatchObject({ done: 2, total: 2, attention: null })
// A live turn after a resume wins over the stale flag.
expect(stationKind(s(), st({ sessionEnded: true, state: 'working' }))).toBe('working')
})
it('a held launch outranks idle readings but not live ones', () => {
expect(stationKind(s({ queued: true }), undefined)).toBe('queued')
expect(stationKind(s({ queued: true }), st({ state: 'done' }))).toBe('queued')
expect(stationKind(s({ queued: true }), st({ state: 'working' }))).toBe('working')
expect(stationKind(s({ queued: true }), st({ state: 'waiting' }))).toBe('needs')
})
})
describe('teamProgressSig / summarizeTeam', () => {
const stations: TeamStation[] = ['d', 'w', 'n', 'e', 'x', 'q', 'u', 'p', 'plain'].map((id) => ({
id,
title: id,
agentId: id === 'plain' ? undefined : 'claude',
queued: id === 'q'
}))
const byId: Record<string, AgentNodeStatus> = {
d: st({ state: 'done' }),
w: st({ state: 'working' }),
n: st({ state: 'blocked' }),
e: st({ state: 'done', lastTurnError: { at: 1 } }),
x: st({ state: 'done', dropped: true }),
p: st({ hibernated: true })
}
it('counts per state, unknown and untracked kept out of N', () => {
const kinds = parseTeamProgressSig(teamProgressSig(byId, stations))
expect(kinds).toEqual(['done', 'working', 'needs', 'errored', 'dropped', 'queued', 'unknown', 'paused', 'untracked'])
const p = summarizeTeam(kinds)
expect(p.done).toBe(2)
expect(p.total).toBe(8)
expect(p.counts.unknown).toBe(1)
expect(p.attention).toBe('error')
expect(teamProgressText(p)).toBe(
'2 of 8 done — 1 dropped, 1 last turn failed, 1 needs you, 1 working, 1 queued, 1 unknown (+1 without status)'
)
})
it('the signature carries no ids, and is stable across same-state events', () => {
const sig = teamProgressSig(byId, stations)
expect(sig).not.toContain('plain')
const refreshed = { ...byId, d: st({ state: 'done', stateAt: 999 }) }
expect(teamProgressSig(refreshed, stations)).toBe(sig)
})
it('a station that is not in the store reads unknown', () => {
const p = summarizeTeam(parseTeamProgressSig(teamProgressSig({}, stations.slice(0, 2))))
expect(p).toMatchObject({ done: 0, total: 2, attention: null })
expect(p.counts.unknown).toBe(2)
})
it('attention ranks needs over working', () => {
expect(summarizeTeam(['working', 'needs', 'done']).attention).toBe('needs')
expect(summarizeTeam(['working', 'done']).attention).toBe('working')
expect(summarizeTeam(['done', 'done']).attention).toBeNull()
})
it('an unreadable signature character reads as unknown, never done', () => {
expect(parseTeamProgressSig('dZ')).toEqual(['done', 'unknown'])
})
})
describe('team membership survives the canvas pruning its ropes', () => {
const stations = (ropes: ReturnType<typeof rope>[], ids: string[]) =>
stationsByOpener(ropes, ids.map((id) => term(id)))
it('(a) deleting the orchestrator does not make an upstream station the next one\'s leader', () => {
// O opened B and C; C runs --after B.
const file = [rope('O', 'B'), rope('O', 'C'), wait('B', 'C')]
const before = canvasRopes(file, [live('O'), live('B'), live('C', ['B'])])
expect(stations(before, ['O', 'B', 'C']).get('O')?.map((s) => s.id)).toEqual(['B', 'C'])
const after = canvasRopes(before, [live('B'), live('C', ['B'])])
expect(stations(after, ['B', 'C']).size).toBe(0)
})
it('(a) the same canvas saved before waits were marked (legacy ids), loaded then pruned', () => {
const legacy = [rope('O', 'B'), rope('O', 'C'), rope('B', 'C')]
const loaded = canvasRopes(legacy, [live('O'), live('B'), live('C')])
expect(stations(loaded, ['O', 'B', 'C']).get('O')?.map((s) => s.id)).toEqual(['B', 'C'])
const pruned = canvasRopes(loaded, [live('B'), live('C')])
expect(stations(pruned, ['B', 'C']).size).toBe(0)
})
it('(a) a verify panel: closing the caller does not give the reviewed node a team of reviewers', () => {
// K verified T: reviewers R1, R2 wait on T; judge J waits on both. K opened all three.
const file = [
rope('K', 'R1'), rope('K', 'R2'), rope('K', 'J'),
wait('T', 'R1'), wait('T', 'R2'), wait('R1', 'J'), wait('R2', 'J')
]
const nodes = [live('T'), live('R1', ['T']), live('R2', ['T']), live('J', ['R1', 'R2'])]
const withCaller = canvasRopes(file, [live('K'), ...nodes])
expect(stations(withCaller, ['K', 'T', 'R1', 'R2', 'J']).get('K')?.map((s) => s.id)).toEqual(['R1', 'R2', 'J'])
const closed = canvasRopes(withCaller, nodes)
expect(stations(closed, ['T', 'R1', 'R2', 'J']).size).toBe(0)
})
it('(b) the user removing the opener rope does not promote the wait', () => {
const held = canvasRopes([rope('O', 'B'), rope('O', 'C'), wait('B', 'C')], [live('O'), live('B'), live('C', ['B'])])
const removed = held.filter((r) => r.id !== 'ctrl-O-C')
const map = stations(removed, ['O', 'B', 'C'])
expect(map.get('O')?.map((s) => s.id)).toEqual(['B'])
expect(map.has('B')).toBe(false)
})
it('(c) a cross-project open whose opener rope is pruned on first load: the healed wait is no opener', () => {
// `--project` + `--after`: the file holds only the opener's rope, and its source lives in
// another project; the load heals the wait rope, the prune drops the opener's.
const loaded = canvasRopes([rope('elsewhere', 'N')], [live('B'), live('N', ['B'])])
expect(loaded.map((r) => r.id)).toEqual([waitRopeId('B', 'N')])
expect(stations(loaded, ['B', 'N']).size).toBe(0)
})
})
describe('a recorded opener (data.openedBy) decides which rope names it', () => {
it('closes the markLegacyWaitRopes residual: a surviving wait is not promoted to opener', () => {
// Saved pruned before waits were marked: O (deleted) opened B and C, C waited on B. Only the
// wait survived, unmarked. By ropes alone it reads as "B opened C".
const file = [rope('B', 'C')]
const legacy = stationsByOpener(file, [term('B'), term('C')])
expect(legacy.get('B')?.map((s) => s.id)).toEqual(['C'])
const recorded = stationsByOpener(file, [term('B'), term('C', { openedBy: 'O' })])
expect(recorded.size).toBe(0)
})
it('the recorded opener\'s rope claims the node even when another rope comes first', () => {
const ropes = [rope('X', 'C'), rope('O', 'C')]
const map = stationsByOpener(ropes, [term('X'), term('O'), term('C', { openedBy: 'O' })])
expect(map.get('O')?.map((s) => s.id)).toEqual(['C'])
expect(map.has('X')).toBe(false)
})
it('the rope keeps it in force: no opener rope, no team, whatever the field says', () => {
const map = stationsByOpener([], [term('O'), term('C', { openedBy: 'O' })])
expect(map.size).toBe(0)
})
it('a hostile or self-naming field is ignored and the rope rule applies', () => {
for (const openedBy of ['../O', 42, 'C', '']) {
const map = stationsByOpener([rope('O', 'C')], [term('O'), term('C', { openedBy })])
expect(map.get('O')?.map((s) => s.id)).toEqual(['C'])
}
})
it('both node readers carry the field through', async () => {
const { stationNodeFromFlow, stationNodeFromState } = await import('../state/teamStations')
expect(
stationNodeFromFlow({ id: 'C', type: 'terminal', position: { x: 0, y: 0 }, data: { openedBy: 'O' } } as never)
.openedBy
).toBe('O')
expect(stationNodeFromState({ id: 'C', kind: 'terminal', openedBy: 'O' } as never).openedBy).toBe('O')
})
})