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.

fix(control): name every agent's state in `list`

Fabricio Casalibd7d8ef99a5e
diff --git a/CLAUDE.md b/CLAUDE.md
index 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 terminal
delivery 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-time
cold-restore relaunch (`fresh && agentId && canResume(...)`) carries a second, independent
diff --git a/src/core/canvas-control-core.ts b/src/core/canvas-control-core.ts
index 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 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, because the prompt is passed as an
argument on the agent CLI's launch command line and that line is typed into the pane. Two
diff --git a/src/main/canvas-control-core.test.ts b/src/main/canvas-control-core.test.ts
index 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.ts
index 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 hea
failed: { 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 (--after
expect(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 (--after
const 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.ts
index 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.ts
index 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/)
})
})