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(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.ts
index 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.ts
index 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 = 8
const AGENT_LIMIT = 5
const 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 {