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(server): open failure reply names each node's launch reason (#925)
reviewdcc7e01b567f
diff --git a/src/server/headless-node-factory.test.ts b/src/server/headless-node-factory.test.tsindex d17f7c9cd..ca57b06a5 100644--- a/src/server/headless-node-factory.test.ts+++ b/src/server/headless-node-factory.test.ts@@ -8,6 +8,7 @@ import { fakePlatform } from '../core/platform-fake'import { initPlatform, resetPlatformForTests } from '../core/platform'import { WorkspaceStore } from '../core/workspace-store'import type { AgentState } from '../shared/agents/normalize'+import { MAX_LAUNCH_LINE_BYTES } from '../shared/canonical-line'import { RUN_NOW_AFTER_REFUSAL } from '../shared/control-verbs'import {DEFAULT_SETTINGS,@@ -20,6 +21,7 @@ import {import {createHeadlessNodeOwnership,HeadlessNodeFactory,+ launchFailedError,type HeadlessNodeOwnership,type HeadlessPty} from './headless-node-factory'@@ -122,6 +124,32 @@ const terminal = (agentId})+describe('launchFailedError (#925)', () => {+ it('groups ids by reason, says what each reason means, and keeps the launch-failed prefix', () => {+ const msg = launchFailedError(+ [+ { id: 'a', reason: 'no-shell', retained: true },+ { id: 'b', reason: 'line-too-long', retained: true },+ { id: 'c', reason: 'no-shell', retained: true },+ { id: 'd', reason: 'spawn-failed', retained: false }+ ],+ 'open-agent'+ )+ expect(msg).toMatch(/^launch-failed: node\(s\) a, b, c, d were persisted/)+ expect(msg).toContain('no-shell: a, c (launch retained for Run now in the node)')+ expect(msg).toContain('line-too-long: b (the launch line is longer than a terminal line takes, so Run now will fail the same way; shorten the prompt)')+ // A plain terminal that never spawned held no launch: promising Run now would be false.+ expect(msg).toContain('spawn-failed: d (no launch was held)')+ expect(msg).toMatch(/; do not repeat the open request$/)+ })++ it('an open-terminal --cmd that is too long is a command, not a prompt', () => {+ expect(launchFailedError([{ id: 't', reason: 'line-too-long', retained: true }], 'open-terminal')).toContain(+ 'shorten the command'+ )+ })+})+describe('HeadlessNodeFactory', () => {let dataDir = ''let projectDir = ''@@ -1313,6 +1341,63 @@ describe('HeadlessNodeFactory', () => {expect(node?.pendingLaunch).toMatchObject({ command: 'printf hello', manualOnly: true })})+ it('a failed open names each node\'s reason, per id and in the message (#925)', async () => {+ vi.spyOn(pty, 'writeHeadless').mockReturnValue(false)+ const reply = await factory.openTerminal('term-source', { cwd: projectDir, cmd: 'printf hello' }, true)+ const id = (reply.result as { id: string }).id+ expect(reply.ok).toBe(false)+ expect(reply.error).toMatch(/^launch-failed:/)+ expect(reply.error).toContain(`cancelled: ${id} (launch retained for Run now in the node)`)+ expect(reply.error).toContain('do not repeat the open request')+ // The result shape is unchanged; the per-id reasons ride beside it.+ expect(reply.result).toMatchObject({ failed: [id], deliveredIds: [], reasons: { [id]: 'cancelled' } })+ })++ it('line-too-long says Run now fails the same way and to shorten the prompt: --prompt-file is not a flag here (#925)', async () => {+ // A canonical-mode tty drops everything past its cap, so the echo never matches the command.+ const write = pty.writeHeadless.bind(pty)+ vi.spyOn(pty, 'writeHeadless').mockImplementation((key, data) =>+ write(key, data.length > MAX_LAUNCH_LINE_BYTES ? data.slice(0, MAX_LAUNCH_LINE_BYTES) : data)+ )+ // Only the delivery's timers are faked (3 x VERIFY_TIMEOUT_MS of real time otherwise); the+ // workspace store's file I/O stays real, so each step also yields to the event loop.+ vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] })+ let reply!: Awaited<ReturnType<HeadlessNodeFactory['openAgent']>>+ try {+ let settled = false+ const pending = factory+ .openAgent('term-source', { agent: 'claude', prompt: 'x'.repeat(1100) }, true)+ .finally(() => (settled = true))+ for (let i = 0; i < 400 && !settled; i++) {+ await new Promise((r) => setImmediate(r))+ await vi.advanceTimersByTimeAsync(100)+ }+ reply = await pending+ } finally {+ vi.useRealTimers()+ }+ const id = (reply.result as { id: string }).id+ expect(reply.ok).toBe(false)+ expect(reply.error).toMatch(/^launch-failed:/)+ expect(reply.error).toContain(`line-too-long: ${id}`)+ expect(reply.error).toContain('Run now will fail the same way')+ expect(reply.error).toContain('shorten the prompt')+ expect(reply.error).not.toContain('retained for Run now')+ expect(reply.error).not.toContain('--prompt-file')+ expect(reply.result).toMatchObject({ failed: [id], reasons: { [id]: 'line-too-long' } })+ expect(pty.sends).toEqual([]) // killed, never submitted+ // Still held, exactly as every other failure: the user can edit the node or delete it.+ const node = (await store.load({ sideline: false })).projects[0].nodes.find((n) => n.id === id)+ expect(node?.pendingLaunch).toMatchObject({ manualOnly: true })+ })++ it('--prompt-file is not an open-agent flag on the Server Edition (the reply above relies on it)', async () => {+ const reply = await factory.openAgent('term-source', { agent: 'claude', 'prompt-file': '/tmp/brief.md' }, true)+ expect(reply.ok).toBe(false)+ expect(reply.error).toMatch(/prompt-file/)+ expect(pty.creates).toEqual([])+ })+it('accepts --run-now on open verbs as a no-op: server opens are already immediate (#925)', async () => {const reply = await factory.openTerminal('term-source', { cwd: projectDir, cmd: 'printf hi', 'run-now': '' }, true)expect(reply.ok).toBe(true)diff --git a/src/server/headless-node-factory.ts b/src/server/headless-node-factory.tsindex 10ae6690a..11e0ed13f 100644--- a/src/server/headless-node-factory.ts+++ b/src/server/headless-node-factory.ts@@ -19,7 +19,7 @@ import {type NodeColor} from '../shared/node-colors'import { applyStickyWrite, parseStickyArgs, resolveStickyRef } from '../shared/sticky-write'-import type { HeadlessLaunchResult } from '../shared/headless-launch'+import type { HeadlessLaunchFailure, HeadlessLaunchResult } from '../shared/headless-launch'import { localNodePtyOptions } from '../shared/node-pty-options'import type { WorkspaceStore } from '../core/workspace-store'import {@@ -145,6 +145,46 @@ export function createHeadlessNodeOwnership(): HeadlessNodeOwnership {}}+/** One node an `open-*` persisted but could not start. */+export interface OpenLaunchFailure {+ id: string+ reason: HeadlessLaunchFailure+ /** The node still holds its launch (manualOnly), so the user's Run now can deliver it. */+ retained: boolean+}++/**+ * The `open-*` failure reply (#925). Each failed node is named with its own reason, grouped, so a+ * caller can tell a failure Run now may get past from one it repeats: `line-too-long` fails the+ * same way on every attempt, and this edition has no `--prompt-file` (the open flag allowlist),+ * so the only way past it is a shorter prompt or command. "Do not repeat the open request" holds+ * for every reason: the nodes are persisted, so the same request would open duplicates.+ */+export function launchFailedError(+ failures: readonly OpenLaunchFailure[],+ verb: 'open-terminal' | 'open-agent'+): string {+ const groups = new Map<string, OpenLaunchFailure & { ids: string[] }>()+ for (const f of failures) {+ const key = `${f.reason}:${f.retained}`+ const group = groups.get(key) ?? { ...f, ids: [] }+ group.ids.push(f.id)+ groups.set(key, group)+ }+ const what = (g: OpenLaunchFailure): string =>+ g.reason === 'line-too-long'+ ? 'the launch line is longer than a terminal line takes, so Run now will fail the same way; ' ++ `shorten the ${verb === 'open-terminal' ? 'command' : 'prompt'}`+ : g.retained+ ? 'launch retained for Run now in the node'+ : 'no launch was held'+ const clauses = [...groups.values()].map((g) => `${g.reason}: ${g.ids.join(', ')} (${what(g)})`)+ return (+ `launch-failed: node(s) ${failures.map((f) => f.id).join(', ')} were persisted but their PTY or ` ++ `initial command could not be delivered — ${clauses.join('; ')}; do not repeat the open request`+ )+}+const TERMINAL_LIMIT = 8const AGENT_LIMIT = 5const TERMINAL_COLS = 120@@ -1322,22 +1362,30 @@ export class HeadlessNodeFactory {this.publish(target, created)const failed: string[] = []+ // Why each one failed, reported per id (#925): a reply that says only "retained for Run now"+ // hides the reason Run now would repeat (`line-too-long`).+ const reasons: Record<string, HeadlessLaunchFailure> = {}+ const fail = (id: string, reason: HeadlessLaunchFailure): void => {+ failed.push(id)+ reasons[id] = reason+ }for (const node of created) {try {const command = commands.get(node.id)if (!command) {// Nothing to deliver now (a plain terminal, or a launch held for `--after`): spawn only.const result = await this.attach(target, node)- if (!result.sessionId) failed.push(node.id)+ if (!result.sessionId) fail(node.id, 'spawn-failed')else if (verb === 'open-agent' && result.fresh) this.awaitingFirstWorking.add(node.id)continue}const launched = await this.launch(target, node, command)if (verb === 'open-agent' && launched.fresh) this.awaitingFirstWorking.add(node.id)if (launched.outcome === 'delivered') node.pendingLaunch = undefined- else failed.push(node.id)+ else fail(node.id, launched.reason)} catch {- failed.push(node.id)+ // The launcher answers its own failures; only the spawn-only `attach` above throws.+ fail(node.id, 'spawn-failed')}}@@ -1359,10 +1407,13 @@ export class HeadlessNodeFactory {if (failed.length) {return {ok: false,- error:- `launch-failed: node(s) ${failed.join(', ')} were persisted but their PTY or initial ` +- 'command could not be delivered; launch retained for Run now in the node; do not repeat the open request',- result: { ids, id: ids[0], after, ...launchResult }+ error: launchFailedError(+ created+ .filter((node) => failed.includes(node.id))+ .map((node) => ({ id: node.id, reason: reasons[node.id], retained: !!node.pendingLaunch })),+ verb+ ),+ result: { ids, id: ids[0], after, ...launchResult, reasons }}}return {