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.

feat(server): run verb and --run-now on the Server Edition (#925)

review7e97614b4fa5
diff --git a/src/server/canvas-control.ts b/src/server/canvas-control.ts
index 918d45132..91e336758 100644
--- a/src/server/canvas-control.ts
+++ b/src/server/canvas-control.ts
@@ -229,6 +229,7 @@ export async function initServerCanvasControl(
rename: (sourceNodeId, args) => factory.rename(sourceNodeId, args),
color: (sourceNodeId, args) => factory.color(sourceNodeId, args),
sticky: (sourceNodeId, args) => factory.sticky(sourceNodeId, args),
+ run: (sourceNodeId, args, verified) => factory.run(sourceNodeId, args, verified),
settings: async (sourceNodeId, args) =>
serverSettingsControl(
{
diff --git a/src/server/control-unsupported.test.ts b/src/server/control-unsupported.test.ts
index 0a55c664b..511deace9 100644
--- a/src/server/control-unsupported.test.ts
+++ b/src/server/control-unsupported.test.ts
@@ -183,9 +183,22 @@ describe('the enabled Server Edition handler parses and dispatches the v1 surfac
color: vi.fn(async () => ({ ok: true as const, result: { colored: ['term-target'] } })),
sticky: vi.fn(async () => ({ ok: true as const, result: { id: 'sticky-new' } })),
settings: vi.fn(async () => ({ ok: true as const, message: 'settings' })),
+ run: vi.fn(async () => ({ ok: true as const })),
deliver: vi.fn(async () => ({ ok: true as const, message: 'queued' }))
})
+ it('routes run to the factory (#925)', async () => {
+ const a = actions()
+ const handler = createServerEditionControlHandler(a)
+ await handler({ verb: 'run', nodeId: 'src', args: { node: 'n1' }, verified: true })
+ expect(a.run).toHaveBeenCalledWith('src', { node: 'n1' }, true)
+ // The shared parser still requires --node before the action is reached.
+ await expect(
+ handler({ verb: 'run', nodeId: 'src', args: {}, verified: true })
+ ).resolves.toEqual({ ok: false, error: 'run requires --node <id>' })
+ expect(a.run).toHaveBeenCalledTimes(1)
+ })
+
it('routes settings to its action, after the shared allowlist parse', async () => {
const a = actions()
const handler = createServerEditionControlHandler(a)
diff --git a/src/server/control-unsupported.ts b/src/server/control-unsupported.ts
index 84dab76af..73d655ccf 100644
--- a/src/server/control-unsupported.ts
+++ b/src/server/control-unsupported.ts
@@ -95,6 +95,8 @@ export interface ServerEditionControlActions {
sticky(sourceNodeId: string, args: Record<string, string>): Promise<ServerControlReply>
/** Reads only; `--set` is refused by name (src/server/settings-control.ts). */
settings(sourceNodeId: string, args: Record<string, string>): Promise<ServerControlReply>
+ /** `run --node <id>` (#925): deliver a retained launch for the node's creator. */
+ run(sourceNodeId: string, args: Record<string, string>, verified: boolean): Promise<ServerControlReply>
deliver(input: {
verb: 'send' | 'reply' | 'notify'
sourceNodeId: string
@@ -116,7 +118,8 @@ const SERVER_V1_VERBS: ReadonlySet<string> = new Set([
'reply',
'notify',
'sticky',
- 'settings'
+ 'settings',
+ 'run'
])
/** A permanent, verb-specific refusal used only while canvas control itself is enabled. */
@@ -181,6 +184,8 @@ export function createServerEditionControlHandler(actions: ServerEditionControlA
return actions.sticky(nodeId, command.args)
case 'settings':
return actions.settings(nodeId, command.args)
+ case 'run':
+ return actions.run(nodeId, command.args, verified)
case 'send':
case 'reply':
case 'notify':
diff --git a/src/server/headless-node-factory.test.ts b/src/server/headless-node-factory.test.ts
index 3d18d4e35..6ed5cb0fb 100644
--- a/src/server/headless-node-factory.test.ts
+++ b/src/server/headless-node-factory.test.ts
@@ -1311,4 +1311,123 @@ describe('HeadlessNodeFactory', () => {
const node = (await store.load({ sideline: false })).projects[0].nodes.find((n) => n.id === id)
expect(node?.pendingLaunch).toMatchObject({ command: 'printf hello', manualOnly: true })
})
+
+ 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)
+ const id = (reply.result as { id: string }).id
+ expect(pty.sends).toEqual([{ nodeId: id, text: 'printf hi' }])
+ })
+
+ it('accepts --run-now on open-agent as the same no-op (#925)', async () => {
+ const reply = await factory.openAgent('term-source', { agent: 'claude', prompt: 'brief', 'run-now': '' }, true)
+ expect(reply.ok).toBe(true)
+ const id = (reply.result as { id: string }).id
+ expect(pty.sends).toEqual([{ nodeId: id, text: "claude 'brief'" }])
+ })
+
+ it('run delivers a retained launch for the node owner (#925)', async () => {
+ const spy = vi.spyOn(pty, 'writeHeadless').mockReturnValue(false)
+ const opened = await factory.openTerminal('term-source', { cwd: projectDir, cmd: 'printf hi' }, true)
+ const id = (opened.result as { id: string }).id
+ spy.mockRestore()
+ pty.sends.length = 0
+ const reply = await factory.run('term-source', { node: id }, true)
+ expect(reply).toMatchObject({ ok: true, result: { started: true, startedIds: [id] } })
+ expect(pty.sends).toEqual([{ nodeId: id, text: 'printf hi' }])
+ const node = (await store.load({ sideline: false })).projects[0].nodes.find((n) => n.id === id)
+ expect(node?.pendingLaunch).toBeUndefined()
+ })
+
+ it('run saves its claim before typing; a failed delivery stays queued and names the reason (#925)', async () => {
+ // An --after arm is the one held launch that has never been attempted, so the claim below is
+ // run's own write-ahead and not one left behind by the open.
+ states['term-upstream'] = 'working'
+ const opened = await factory.openTerminal(
+ 'term-source',
+ { cwd: projectDir, cmd: 'printf hi', after: 'term-upstream' },
+ true
+ )
+ const id = (opened.result as { id: string }).id
+ expect((await store.load({ sideline: false })).projects[0].nodes.find((n) => n.id === id)?.pendingLaunch)
+ .toMatchObject({ attempted: false })
+ expect(pty.sends).toEqual([])
+ let durableAtFirstWrite: ReturnType<WorkspaceStore['load']> | undefined
+ const refuse = vi.spyOn(pty, 'writeHeadless').mockImplementation(() => {
+ durableAtFirstWrite ??= store.load({ sideline: false })
+ return false
+ })
+ const reply = await factory.run('term-source', { node: id }, true)
+ refuse.mockRestore()
+ expect(reply).toMatchObject({
+ ok: true,
+ result: { started: false, startedIds: [], queued: true, queuedIds: [id], reason: 'cancelled' }
+ })
+ const claimed = (await durableAtFirstWrite!).projects[0].nodes.find((n) => n.id === id)
+ expect(claimed?.pendingLaunch).toMatchObject({ command: 'printf hi', attempted: true, manualOnly: true })
+ expect(pty.sends).toEqual([])
+ const node = (await store.load({ sideline: false })).projects[0].nodes.find((n) => n.id === id)
+ expect(node?.pendingLaunch).toMatchObject({ command: 'printf hi', attempted: true, manualOnly: true })
+ // manualOnly: the dependency finishing never replays it.
+ await factory.refreshArmed({ nodeId: 'term-upstream', state: 'done' })
+ expect(pty.sends).toEqual([])
+ })
+
+ it('run refuses a non-owner, an unknown node and a node with nothing queued (#925)', async () => {
+ const opened = await factory.openTerminal('term-source', { cwd: projectDir, cmd: 'printf hi' }, true)
+ const id = (opened.result as { id: string }).id
+ expect((await factory.run('someone-else', { node: id }, true)).error).toMatch(/^run-not-owner:/)
+ expect((await factory.run('term-source', { node: id }, true)).error).toMatch(/^run-nothing-queued:/)
+ expect((await factory.run('term-source', { node: id, cmd: 'x' }, true)).error).toMatch(/not supported/)
+ expect((await factory.run('term-source', { node: id }, false)).error).toMatch(/^run-identity-refused:/)
+ // Owned by this caller but gone from the canvas: the desktop's own wording.
+ ownership.record('term-vanished', { sourceNodeId: 'term-source', projectId: 'project-1' })
+ expect((await factory.run('term-source', { node: 'term-vanished' }, true)).error)
+ .toBe('run: no node with id term-vanished')
+ })
+
+ it('run marks an agent it freshly spawned as awaiting its first working turn, as open does (#925)', async () => {
+ // The open's spawn fails, so the node has no session and was never marked; run spawns it fresh.
+ const spawn = vi.spyOn(pty, 'createHeadless').mockResolvedValueOnce({ sessionId: '', fresh: true })
+ const opened = await factory.openAgent('term-source', { agent: 'claude', prompt: 'brief' }, true)
+ spawn.mockRestore()
+ expect(opened.ok).toBe(false)
+ const agentNode = (opened.result as { id: string }).id
+ expect(await factory.run('term-source', { node: agentNode }, true))
+ .toMatchObject({ ok: true, result: { started: true } })
+ // A dependent armed now must not be released by the fresh CLI's boot `done` blip.
+ const dependent = await factory.openTerminal(
+ 'term-source',
+ { cwd: projectDir, cmd: 'printf after', after: agentNode },
+ true
+ )
+ const depId = (dependent.result as { id: string }).id
+ pty.sends.length = 0
+ await factory.refreshArmed({ nodeId: agentNode, state: 'done' })
+ expect(pty.sends).toEqual([])
+ await factory.refreshArmed({ nodeId: agentNode, state: 'working' })
+ await factory.refreshArmed({ nodeId: agentNode, state: 'done' })
+ expect(pty.sends).toEqual([{ nodeId: depId, text: 'printf after' }])
+ })
+
+ it('run refuses an SSH node before any claim (#925)', async () => {
+ const held = { after: [], command: 'printf hi', executor: 'server' as const, attempted: false }
+ const workspace = await store.load({ sideline: false })
+ workspace.projects[0].nodes.push({
+ ...terminal('term-remote', 'Remote'),
+ sshRemoteTmux: true,
+ pendingLaunch: held
+ })
+ await store.save(workspace)
+ ownership.record('term-remote', { sourceNodeId: 'term-source', projectId: 'project-1' })
+ const reply = await factory.run('term-source', { node: 'term-remote' }, true)
+ expect(reply).toEqual({
+ ok: false,
+ error: 'run-remote-unsupported: term-remote is an SSH node; the Server Edition cannot start it'
+ })
+ expect(pty.creates).toEqual([])
+ expect(pty.sends).toEqual([])
+ const node = (await store.load({ sideline: false })).projects[0].nodes.find((n) => n.id === 'term-remote')
+ expect(node?.pendingLaunch).toEqual(held)
+ })
})
diff --git a/src/server/headless-node-factory.ts b/src/server/headless-node-factory.ts
index ee71a13c4..ba470c2de 100644
--- a/src/server/headless-node-factory.ts
+++ b/src/server/headless-node-factory.ts
@@ -36,6 +36,7 @@ import {
import { assembleLaunchCommand } from '../shared/agents/launch'
import type { AgentState, NormalizedAgentEvent } from '../shared/agents/normalize'
import { oneLine } from '../shared/one-line'
+import { isRemoteSessionNode } from '../shared/worktree'
import { UNKNOWN_CODEX_CLI_CAPS } from '../shared/types'
import type {
BridgeLink,
@@ -1041,6 +1042,55 @@ export class HeadlessNodeFactory {
})
}
+ /** `run --node <id>` (#925): deliver a node's retained launch now. Server v1 ownership applies:
+ * only nodes the caller spawned during this server run. */
+ run(sourceNodeId: string, args: Record<string, string>, verified: boolean): Promise<ServerControlReply> {
+ return this.runExclusive(async () => {
+ if (!verified) {
+ return { ok: false, error: 'run-identity-refused: Server Edition canvas control requires verified node identity' }
+ }
+ const flagError = unsupportedFlags(args, new Set(['node', 'project']))
+ if (flagError) return { ok: false, error: `run: ${flagError}` }
+ const id = (args.node ?? '').trim()
+ if (!this.ownsSpawn(sourceNodeId, id)) return this.ownershipRefusal('run', sourceNodeId, id)
+ const workspace = await this.deps.workspaceStore.load({ sideline: false })
+ const project = workspace.projects.find((p) => p.nodes.some((n) => n.id === id))
+ const node = project?.nodes.find((n) => n.id === id)
+ if (!project || !node) return { ok: false, error: `run: no node with id ${id}` }
+ const held = node.pendingLaunch
+ if (!held?.command) return { ok: false, error: `run-nothing-queued: ${id} has no queued launch` }
+ // A remote node is NEVER spawned locally, and this launcher only spawns locally. Refuse
+ // before the claim, leaving the held launch untouched (the desktop's startHeadless guard).
+ if (isRemoteSessionNode(node)) {
+ return {
+ ok: false,
+ error: `run-remote-unsupported: ${id} is an SSH node; the Server Edition cannot start it`
+ }
+ }
+ // Write-ahead, exactly as open() does before its own delivery.
+ node.pendingLaunch = { ...held, attempted: true, manualOnly: true }
+ await this.deps.workspaceStore.save(workspace)
+ const launched = await this.launch(project, node, held.command)
+ // As open() does: an agent this spawned fresh has not had its first real turn yet, so a
+ // later `--after` on it must not be released by the CLI's boot `done` blip.
+ if (node.agentId && launched.fresh) this.awaitingFirstWorking.add(id)
+ if (launched.outcome === 'delivered') node.pendingLaunch = undefined
+ await this.deps.workspaceStore.save(workspace)
+ this.publish(project, [node])
+ return launched.outcome === 'delivered'
+ ? {
+ ok: true,
+ message: `started ${id}; agent startup is not confirmed`,
+ result: { ids: [id], id, started: true, startedIds: [id], queued: false, queuedIds: [] }
+ }
+ : {
+ ok: true,
+ message: `${id} stays queued (${launched.reason}); launch retained for Run now`,
+ result: { ids: [id], id, started: false, startedIds: [], queued: true, queuedIds: [id], reason: launched.reason }
+ }
+ })
+ }
+
color(sourceNodeId: string, args: Record<string, string>): Promise<ServerControlReply> {
return this.runExclusive(async () => {
const flagError = unsupportedFlags(args, new Set(['node', 'color']))
@@ -1088,9 +1138,10 @@ export class HeadlessNodeFactory {
return this.runExclusive(async () => {
const flagError = unsupportedFlags(
args,
+ // `run-now` (#925) is accepted and ignored: a server open already delivers immediately.
verb === 'open-terminal'
- ? new Set(['count', 'cwd', 'cmd', 'after', 'project'])
- : new Set(['agent', 'count', 'cwd', 'prompt', 'after', 'project', 'model'])
+ ? new Set(['count', 'cwd', 'cmd', 'after', 'project', 'run-now'])
+ : new Set(['agent', 'count', 'cwd', 'prompt', 'after', 'project', 'model', 'run-now'])
)
if (flagError) return { ok: false, error: `${verb}: ${flagError}` }
if (!verified) {