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
feat(core): one local-spawn option builder for headless starts
reviewc4e8ba6a92b4
diff --git a/src/server/headless-node-factory.ts b/src/server/headless-node-factory.tsindex c9b16c9e3..1e121cd27 100644--- a/src/server/headless-node-factory.ts+++ b/src/server/headless-node-factory.ts@@ -18,6 +18,7 @@ import {type NodeColor} from '../shared/node-colors'import { applyStickyWrite, parseStickyArgs, resolveStickyRef } from '../shared/sticky-write'+import { localNodePtyOptions } from '../shared/node-pty-options'import type { WorkspaceStore } from '../core/workspace-store'import {AGENT_CONFIG,@@ -481,16 +482,7 @@ function ungroupPersistedNodes(}function ptyOptions(project: Project, node: CanvasNodeState): PtyCreateOptions {- return {- cwd: node.cwd || project.cwd,- cols: TERMINAL_COLS,- rows: TERMINAL_ROWS,- persistKey: node.id,- ownerProjectId: project.id,- ...(node.agentId ? { agentId: node.agentId } : {}),- ...(node.agentModel ? { agentModel: node.agentModel } : {}),- ...(node.accountId ? { accountId: node.accountId } : {})- }+ return localNodePtyOptions(project, node, { cols: TERMINAL_COLS, rows: TERMINAL_ROWS })}/**diff --git a/src/shared/node-pty-options.test.ts b/src/shared/node-pty-options.test.tsnew file mode 100644index 000000000..dd616c711--- /dev/null+++ b/src/shared/node-pty-options.test.ts@@ -0,0 +1,51 @@+import { describe, expect, it } from 'vitest'+import { HEADLESS_COLS, HEADLESS_ROWS, localNodePtyOptions } from './node-pty-options'++const project = { id: 'p1', cwd: '/repo' }++describe('localNodePtyOptions', () => {+ it('builds the local spawn a node gets, falling back to the project cwd', () => {+ expect(localNodePtyOptions(project, { id: 'n1' }, { cols: 80, rows: 24 })).toEqual({+ cwd: '/repo',+ cols: 80,+ rows: 24,+ persistKey: 'n1',+ ownerProjectId: 'p1'+ })+ })++ it('carries shell, agent, model and account only when set, and prefers the node cwd', () => {+ expect(+ localNodePtyOptions(+ project,+ { id: 'n2', cwd: '/repo/sub', shell: '/bin/zsh', agentId: 'claude', agentModel: 'm', accountId: 'a1' },+ { cols: HEADLESS_COLS, rows: HEADLESS_ROWS }+ )+ ).toEqual({+ cwd: '/repo/sub',+ cols: 120,+ rows: 36,+ persistKey: 'n2',+ ownerProjectId: 'p1',+ shell: '/bin/zsh',+ agentId: 'claude',+ agentModel: 'm',+ accountId: 'a1'+ })+ })++ // The key set IS the contract with TerminalNode's local create (see the module comment): a key+ // added there and forgotten here makes a headless-started session differ from a mounted one.+ it('never emits keys beyond the local-spawn set', () => {+ const keys = Object.keys(+ localNodePtyOptions(+ project,+ { id: 'n3', cwd: '/x', shell: 's', agentId: 'codex', agentModel: 'm', accountId: 'a' },+ { cols: 1, rows: 1 }+ )+ ).sort()+ expect(keys).toEqual(+ ['accountId', 'agentId', 'agentModel', 'cols', 'cwd', 'ownerProjectId', 'persistKey', 'rows', 'shell'].sort()+ )+ })+})diff --git a/src/shared/node-pty-options.ts b/src/shared/node-pty-options.tsnew file mode 100644index 000000000..b4c190139--- /dev/null+++ b/src/shared/node-pty-options.ts@@ -0,0 +1,40 @@+import type { CanvasNodeState, Project, PtyCreateOptions } from './types'++/** Size of a headless spawn until a real viewer attaches and resizes it (tmux redraws then). */+export const HEADLESS_COLS = 120+export const HEADLESS_ROWS = 36++type NodeSpawnFields = Pick<CanvasNodeState, 'id' | 'cwd' | 'shell' | 'agentId' | 'agentModel' | 'accountId'>++/**+ * The PtyCreateOptions a LOCAL spawn of `node` uses when no viewer initiates it: the desktop+ * headless launcher (#925) and the Server Edition's canvas factory.+ *+ * It mirrors the local fields of TerminalNode's own `transport.create`: `shell`, `cwd`,+ * `persistKey`, `ownerProjectId`, `agentId`, `agentModel` and `accountId`. The session a viewer later+ * warm-attaches to therefore carries the env it would have had if the viewer had spawned it. Two+ * deliberate differences:+ * - `cwd` falls back to the project root. A headless spawn has no mounted node to inherit a+ * working directory from, and the Server Edition always did this.+ * - No `sshRemote` / `requireRemote` / `clearEnv`. Headless starts are local-only in v1, and+ * clearEnv is a one-shot restart flag.+ * TerminalNode itself is NOT moved onto this builder: its create also serves warm and SSH attaches,+ * and a cwd-less node there spawns in $HOME today.+ */+export function localNodePtyOptions(+ project: Pick<Project, 'id' | 'cwd'>,+ node: NodeSpawnFields,+ size: { cols: number; rows: number }+): PtyCreateOptions {+ return {+ cwd: node.cwd || project.cwd,+ cols: size.cols,+ rows: size.rows,+ persistKey: node.id,+ ownerProjectId: project.id,+ ...(node.shell ? { shell: node.shell } : {}),+ ...(node.agentId ? { agentId: node.agentId } : {}),+ ...(node.agentModel ? { agentModel: node.agentModel } : {}),+ ...(node.accountId ? { accountId: node.accountId } : {})+ }+}