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
fix(control): name every agent's state in `list`
Fabricio Casalibd7d8ef99a5e
diff --git a/CLAUDE.md b/CLAUDE.mdindex ef1965189..2520ed130 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -4322,7 +4322,7 @@ command-bearing opens; this does not add a human-confirm dialog or change mobile`queued:false` is NOT proof of a running CLI: Server's `deliveredIds` acknowledges terminaldelivery only. Its initial commands are persisted before attach/send and retained on failure;only acknowledged sends clear them. Boot ownership remains fail-closed. Desktop `list` (live- and stored projects) names QUEUED / STARTING / LAUNCH FAILED / DROPPED / AGENT STATUS UNCONFIRMED+ and stored projects) names QUEUED / STARTING / LAUNCH FAILED / DROPPED / AGENT STATUS UNCONFIRMED, and every other agent row its state (WORKING / IDLE / NEEDS YOU: an unlabelled idle row and a row waiting on a person used to read the same)rather than treating absence of a hook as success. Server v1 still explicitly refuses `list`.**(8) An armed node must not cold-start its own agent** (found while fixing (7)). The mount-timecold-restore relaunch (`fresh && agentId && canResume(...)`) carries a second, independentdiff --git a/src/core/canvas-control-core.ts b/src/core/canvas-control-core.tsindex 91e8494e1..135332147 100644--- a/src/core/canvas-control-core.ts+++ b/src/core/canvas-control-core.ts@@ -900,6 +900,8 @@ export function buildCanvasControlInstructions(shimPath: string): string {' `queued: false` is not proof the agent is running. `deliveredIds` confirms command delivery only.',' `list` names QUEUED, STARTING, LAUNCH FAILED, EXPIRED, DROPPED and AGENT STATUS UNCONFIRMED',' where observed. STARTING means a background start is in flight: do not `run` that node again.',+ ' Every other agent row names its state: WORKING, IDLE (its turn ended; it waits for input) or',+ ' NEEDS YOU (a question or approval waits for a person, not for you). A plain terminal row carries no state.',' `--prompt` arrives on ONE LINE: every run of whitespace in it, newlines included, is',' collapsed to a single space before the session starts (the prompt rides the launch command',' line typed into the pane). For a structured or multi-line brief use `--prompt-file <abs',@@ -1462,6 +1464,8 @@ Verbs:\`queued: false\` does not prove the agent is running. \`deliveredIds\` confirms command delivery only.\`list\` names QUEUED, STARTING, LAUNCH FAILED, EXPIRED, DROPPED and AGENT STATUS UNCONFIRMEDwhere observed. STARTING means a background start is in flight: do not \`run\` that node again.+ Every other agent row names its state: WORKING, IDLE (its turn ended; it waits for input) or+ NEEDS YOU (a question or approval waits for a person, not for you). A plain terminal row carries no state.\`--prompt\` arrives on ONE LINE. Every run of whitespace in it — newlines included — iscollapsed to a single space before the session starts, because the prompt is passed as anargument on the agent CLI's launch command line and that line is typed into the pane. Twodiff --git a/src/main/canvas-control-core.test.ts b/src/main/canvas-control-core.test.tsindex 0116f7743..f45289035 100644--- a/src/main/canvas-control-core.test.ts+++ b/src/main/canvas-control-core.test.ts@@ -1435,6 +1435,7 @@ describe('--after-pr: open a node that waits on a pull request', () => {expect(flat).toContain('default 24h, at most 14d')expect(flat).toContain('`list` marks it EXPIRED')expect(flat).toContain('`list` names QUEUED, STARTING, LAUNCH FAILED, EXPIRED, DROPPED and AGENT STATUS UNCONFIRMED')+ expect(flat).toContain('Every other agent row names its state: WORKING, IDLE (its turn ended; it waits for input) or NEEDS YOU')expect(flat).toContain('you start it with the `run` verb')// What is refused.expect(flat).toContain('the pull request must exist in the repository this project\'s kanban board syncs with')diff --git a/src/renderer/lib/controlRouting.test.ts b/src/renderer/lib/controlRouting.test.tsindex a0c91e186..cdbebabaf 100644--- a/src/renderer/lib/controlRouting.test.ts+++ b/src/renderer/lib/controlRouting.test.ts@@ -477,14 +477,14 @@ it('lists held, failed and unconfirmed launches without claiming an agent is heafailed: { kind: 'failed', attempts: 5, at: 1 },stalled: { kind: 'stalled', since: 1 }})- expect(rows.map((r) => r.launchState)).toEqual(['queued', 'failed', 'stalled', 'dropped', 'unconfirmed', undefined, undefined])+ expect(rows.map((r) => r.launchState)).toEqual(['queued', 'failed', 'stalled', 'dropped', 'unconfirmed', 'idle', undefined])const text = controlListingText(rows)expect(text).toContain('queued [terminal] — QUEUED')expect(text).toContain('failed [terminal] — LAUNCH FAILED')expect(text).toContain('stalled [terminal] — QUEUED (terminal not ready)')expect(text).toContain('dead [terminal] — DROPPED')expect(text).toContain('unknown [terminal] — AGENT STATUS UNCONFIRMED')- expect(text).toContain('errored [terminal] — LAST TURN ERRORED')+ expect(text).toContain('errored [terminal] — IDLE — LAST TURN ERRORED')expect(text).not.toContain('RUNNING')})@@ -549,7 +549,7 @@ it('lists every station’s own report, and where a success wait stands (--afterexpect(byId.go.launchState).toBe('blocked-failure')expect(byId.lint.outcome).toBe('failed')const text = controlListingText(rows)- expect(text).toContain('lint [terminal] Linter — REPORTED FAILURE ("eslint red")')+ expect(text).toContain('lint [terminal] Linter — IDLE — REPORTED FAILURE ("eslint red")')expect(text).toContain('rev [terminal] Reviewer — WAITING FOR SUCCESS — needs success from: build "Builder" (no outcome reported yet)')@@ -565,7 +565,7 @@ it('lists every station’s own report, and where a success wait stands (--afterconst r2 = Object.fromEntries(after.map((r) => [r.id, r]))expect(r2.rev.launchState).toBe('queued')expect(r2.rev.successWait).toBeUndefined()- expect(controlListingText(after)).toContain('build [terminal] Builder — REPORTED SUCCESS')+ expect(controlListingText(after)).toContain('build [terminal] Builder — IDLE — REPORTED SUCCESS')})it('a report made before queued new work is listed as not counting, and the wait keeps waiting', () => {@@ -580,7 +580,7 @@ it('a report made before queued new work is listed as not counting, and the wait{ build: { nodeId: 'build', outcome: 'succeeded', at: 1, workPending: true } })const text = controlListingText(rows)- expect(text).toContain('build [terminal] Builder — REPORTED SUCCESS (before new work queued for it; not counted until it reports again)')+ expect(text).toContain('build [terminal] Builder — IDLE — REPORTED SUCCESS (before new work queued for it; not counted until it reports again)')expect(text).toContain('rev [terminal] Reviewer — WAITING FOR SUCCESS — needs success from: build "Builder" (new work is queued for it; waiting for its next report)')})@@ -596,3 +596,30 @@ it('a hostile success hold in a stored project neither throws nor reads as met',)expect(rows.map((r) => r.launchState)).toEqual(['success-expired', 'success-expired'])})++it('names every agent row\'s state, so a station waiting on a person does not read as finished', () => {+ const rows = storedNodeListing(+ [+ { id: 'idle', agentId: 'claude' },+ { id: 'asks', agentId: 'claude' },+ { id: 'gated', agentId: 'codex' },+ { id: 'busy', agentId: 'claude' },+ { id: 'shell' }+ ],+ {+ idle: { state: 'done' },+ asks: { state: 'waiting' },+ gated: { state: 'blocked' },+ busy: { state: 'working' },+ shell: { state: 'done' }+ }+ )+ expect(rows.map((r) => r.launchState)).toEqual(['idle', 'needs-you', 'needs-you', 'working', undefined])+ expect(controlListingText(rows).split('\n')).toEqual([+ 'idle [terminal] — IDLE',+ 'asks [terminal] — NEEDS YOU',+ 'gated [terminal] — NEEDS YOU',+ 'busy [terminal] — WORKING',+ 'shell [terminal] '+ ])+})diff --git a/src/renderer/lib/controlRouting.ts b/src/renderer/lib/controlRouting.tsindex f2062fdca..e8771f41a 100644--- a/src/renderer/lib/controlRouting.ts+++ b/src/renderer/lib/controlRouting.ts@@ -219,8 +219,10 @@ export function storedNodeListing(const successFacts = (d: string) =>successDepFacts(d, statuses, live, outcomes, handovers)const successState = successHold ? successWaitStatus(successHold, successFacts, now) : undefined+ // Every agent row names its state: an unlabelled row used to mean idle, waiting on a person, or+ // not an agent at all, so an orchestrator read a station stuck on a permission prompt as finished.const launchState = controlLaunchState(!!n.pendingLaunch, deliveries[n.id] ?? ((n.pendingLaunch as { manualOnly?: boolean } | undefined)?.manualOnly ? { kind: 'failed', attempts: 1, at: 0 } : undefined), status, prExpired, successState) ??- (n.agentId && !status?.state ? 'unconfirmed' as const : undefined)+ (n.agentId ? agentRowState(status?.state) : undefined)// A session started on an issue is told so on its OWN row, so `list` is enough for an agent to// learn it is bound (and which card to move). Only a reference `formatIssueRef` vouches for.const issue = formatIssueRef(n.issueRef)@@ -275,7 +277,16 @@ export function storedNodeListing(})}+/** An agent row with no launch or drop to report: its live state, in the canvas badge's words. */+function agentRowState(state: string | undefined): 'idle' | 'needs-you' | 'unconfirmed' {+ if (state === 'done') return 'idle'+ if (state === 'waiting' || state === 'blocked') return 'needs-you'+ return 'unconfirmed'+}+const launchLabels = {+ idle: 'IDLE',+ 'needs-you': 'NEEDS YOU',queued: 'QUEUED',failed: 'LAUNCH FAILED',stalled: 'QUEUED (terminal not ready)',diff --git a/src/renderer/lib/turnInterrupt.test.ts b/src/renderer/lib/turnInterrupt.test.tsindex ec694b69c..471e23a8c 100644--- a/src/renderer/lib/turnInterrupt.test.ts+++ b/src/renderer/lib/turnInterrupt.test.ts@@ -110,8 +110,8 @@ describe('--after holds on an interrupted upstream', () => {})const text = controlListingText(rows)- expect(text).toContain('i [terminal] — LAST TURN INTERRUPTED')- expect(text).toContain('e [terminal] — LAST TURN ERRORED')+ expect(text).toContain('i [terminal] — IDLE — LAST TURN INTERRUPTED')+ expect(text).toContain('e [terminal] — IDLE — LAST TURN ERRORED')expect(text).not.toMatch(/e \[terminal\].*INTERRUPTED/)})})