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, vi } from 'vitest'
import {
assembleDevPorts,
collectLocalDevPorts,
decodeProcAddress,
devPortsProbeCommand,
fetchRemoteDevPorts,
forwardTarget,
parseDevPortsProbe,
parseLsofListeners,
parseProcFdSockets,
parseProcNetTcp,
parseProcRows,
parseSsListeners,
splitHostPort
} from './dev-ports'
// Captured from a real Ubuntu 24.04 host (iproute2 6.1) — note the glued `PortProcess` header.
const SS_REAL = `State Recv-Q Send-Q Local Address:Port Peer Address:PortProcess
LISTEN 0 511 127.0.0.1:5173 0.0.0.0:* users:(("node",pid=210,fd=26))
LISTEN 0 511 [::1]:5173 [::]:* users:(("node",pid=210,fd=27))
LISTEN 0 4096 0.0.0.0:6543 0.0.0.0:* users:(("docker-proxy",pid=7799,fd=8))
LISTEN 0 128 *:3000 *:* users:(("ruby",pid=300,fd=9),("ruby",pid=301,fd=9))
LISTEN 0 128 [::]:8080 [::]:*
LISTEN 0 128 127.0.0.53%lo:53 0.0.0.0:*`
describe('splitHostPort', () => {
it('reads every spelling ss and lsof print', () => {
expect(splitHostPort('127.0.0.1:5173')).toEqual({ address: '127.0.0.1', port: 5173 })
expect(splitHostPort('[::1]:5173')).toEqual({ address: '::1', port: 5173 })
expect(splitHostPort('[::]:80')).toEqual({ address: '::', port: 80 })
expect(splitHostPort(':::8080')).toEqual({ address: '::', port: 8080 })
expect(splitHostPort('*:3000')).toEqual({ address: '*', port: 3000 })
expect(splitHostPort('127.0.0.53%lo:53')).toEqual({ address: '127.0.0.53', port: 53 })
// An IPv4-mapped bind is its IPv4 address (it used to make forwardTarget answer null).
expect(splitHostPort('[::ffff:127.0.0.1]:5173')).toEqual({ address: '127.0.0.1', port: 5173 })
})
it('refuses a peer column and out-of-range ports', () => {
expect(splitHostPort('0.0.0.0:*')).toBeNull()
expect(splitHostPort('1.2.3.4:0')).toBeNull()
expect(splitHostPort('1.2.3.4:70000')).toBeNull()
expect(splitHostPort('LISTEN')).toBeNull()
})
})
describe('parseSsListeners', () => {
it('takes the local address, every owning pid and the command', () => {
const l = parseSsListeners(SS_REAL)
expect(l[0]).toEqual({ owners: [{ pid: 210, command: 'node' }], address: '127.0.0.1', port: 5173 })
expect(l[1]).toEqual({ owners: [{ pid: 210, command: 'node' }], address: '::1', port: 5173 })
expect(l[3]).toEqual({ owners: [{ pid: 300, command: 'ruby' }, { pid: 301, command: 'ruby' }], address: '*', port: 3000 })
// Another user's socket carries no process column: listed, but owned by nobody we know.
expect(l[4]).toEqual({ owners: [], address: '::', port: 8080 })
expect(l).toHaveLength(6)
})
})
describe('parseSsListeners — the owner column is attacker-influenced', () => {
// Reproduced (review of #1063): a process owned by `nobody` renamed itself `vite",pid=12345` and
// ss printed its name raw. Collecting every `pid=` on the line handed the port to pid 12345.
const forged = 'LISTEN 0 5 0.0.0.0:8000 0.0.0.0:* users:(("vite",pid=12345",pid=219072,fd=3))'
it('takes only the LAST pid of a group, and keeps the forged text as the name', () => {
expect(parseSsListeners(forged)[0].owners).toEqual([{ pid: 219072, command: 'vite",pid=12345' }])
})
it('never attributes the forged port to the node whose tree holds the named pid', () => {
const out = assembleDevPorts(
[{ session: 'nt-a', panePid: 12345, command: 'zsh' }],
[
{ pid: 12345, ppid: 1, command: 'zsh' },
{ pid: 219072, ppid: 1, command: 'vite",pid=12345' }
],
parseSsListeners(forged)
)
expect(out).toEqual({})
})
it('a pid whose ps name disagrees with the tool\'s name is not trusted', () => {
const out = assembleDevPorts(
[{ session: 'nt-a', panePid: 100, command: 'zsh' }],
[
{ pid: 100, ppid: 1, command: 'zsh' },
{ pid: 101, ppid: 100, command: 'node' }
],
[{ owners: [{ pid: 101, command: 'postgres' }], address: '127.0.0.1', port: 5432 }]
)
expect(out).toEqual({})
})
it('truncated names still agree (lsof prints 9 chars, macOS ps the full basename)', () => {
const out = assembleDevPorts(
[{ session: 'nt-a', panePid: 100, command: 'zsh' }],
[
{ pid: 100, ppid: 1, command: 'zsh' },
{ pid: 101, ppid: 100, command: 'com.docker.backend' }
],
[{ owners: [{ pid: 101, command: 'com.docke' }], address: '127.0.0.1', port: 3000 }]
)
expect(out.a.map((p) => p.port)).toEqual([3000])
})
})
describe('parseLsofListeners', () => {
it('groups n-fields under the preceding p/c', () => {
const out = parseLsofListeners('p210\ncnode\nf26\nn127.0.0.1:5173\nf27\nn[::1]:5173\np300\ncruby\nn*:3000\n')
expect(out).toEqual([
{ owners: [{ pid: 210, command: 'node' }], address: '127.0.0.1', port: 5173 },
{ owners: [{ pid: 210, command: 'node' }], address: '::1', port: 5173 },
{ owners: [{ pid: 300, command: 'ruby' }], address: '*', port: 3000 }
])
})
})
describe('/proc parsing', () => {
it('decodes little-endian IPv4 and IPv6 words', () => {
expect(decodeProcAddress('0100007F')).toBe('127.0.0.1')
expect(decodeProcAddress('00000000')).toBe('0.0.0.0')
expect(decodeProcAddress('00000000000000000000000001000000')).toBe('::1')
expect(decodeProcAddress('00000000000000000000000000000000')).toBe('::')
expect(decodeProcAddress('0000000000000000FFFF00000100007F')).toBe('127.0.0.1')
expect(decodeProcAddress('zz')).toBeNull()
})
it('keeps only LISTEN rows, keyed by inode', () => {
const tcp = ` sl local_address rem_address st tx_queue rx_queue tr tm->when retrnsmt uid timeout inode
0: 0100007F:1435 00000000:0000 0A 00000000:00000000 00:00000000 00000000 1000 0 4242 1
1: 0100007F:1435 0100007F:C001 01 00000000:00000000 00:00000000 00000000 1000 0 9999 1
0: 00000000000000000000000001000000:1F90 00000000000000000000000000000000:0000 0A 0 0 0 1000 0 777 1`
const m = parseProcNetTcp(tcp)
expect([...m.entries()]).toEqual([
['4242', { address: '127.0.0.1', port: 5173 }],
['777', { address: '::1', port: 8080 }]
])
})
it('maps socket inodes to pids from ls -l over several fd dirs', () => {
const ls = `/proc/210/fd:
total 0
lrwx------ 1 u u 64 Sep 30 12:00 0 -> /dev/pts/1
lrwx------ 1 u u 64 Sep 30 12:00 26 -> socket:[4242]
/proc/211/fd:
lrwx------ 1 u u 64 Sep 30 12:00 3 -> socket:[4242]
lrwx------ 1 u u 64 Sep 30 12:00 4 -> socket:[777]`
const m = parseProcFdSockets(ls)
expect(m.get('4242')).toEqual([210, 211])
expect(m.get('777')).toEqual([211])
})
it('parses ps rows and keeps the command basename', () => {
expect(parseProcRows(' 1 0 /sbin/launchd\n 42 1 node\n x\n')).toEqual([
{ pid: 1, ppid: 0, command: 'launchd' },
{ pid: 42, ppid: 1, command: 'node' }
])
})
})
describe('assembleDevPorts — ownership by process tree', () => {
const panes = [
{ session: 'nt-a', panePid: 100, command: 'zsh' },
{ session: 'nt-b', panePid: 200, command: 'zsh' },
{ session: 'someone-else', panePid: 900, command: 'bash' }
]
const procs = [
{ pid: 1, ppid: 0, command: 'init' },
{ pid: 100, ppid: 1, command: 'zsh' },
{ pid: 101, ppid: 100, command: 'npm' },
{ pid: 102, ppid: 101, command: 'node' }, // vite, two levels below the pane
{ pid: 200, ppid: 1, command: 'zsh' },
{ pid: 900, ppid: 1, command: 'bash' },
{ pid: 901, ppid: 900, command: 'python3' },
{ pid: 500, ppid: 1, command: 'postgres' }
]
it('attributes a descendant listener to its node, merges families, sorts', () => {
const out = assembleDevPorts(panes, procs, [
{ owners: [{ pid: 102, command: '' }], address: '::1', port: 5173 },
{ owners: [{ pid: 102, command: 'node' }], address: '127.0.0.1', port: 5173 },
{ owners: [{ pid: 102, command: 'node' }], address: '127.0.0.1', port: 4000 },
{ owners: [{ pid: 102, command: 'node' }], address: '127.0.0.1', port: 40001 }
])
expect(out).toEqual({
a: [
{ port: 4000, addresses: ['127.0.0.1'], command: 'node', ephemeral: false },
{ port: 5173, addresses: ['::1', '127.0.0.1'], command: 'node', ephemeral: false },
{ port: 40001, addresses: ['127.0.0.1'], command: 'node', ephemeral: true }
]
})
})
it('never reports a port owned outside every nt- pane tree', () => {
const out = assembleDevPorts(panes, procs, [
{ owners: [{ pid: 500, command: 'postgres' }], address: '0.0.0.0', port: 5432 },
{ owners: [{ pid: 901, command: 'python3' }], address: '0.0.0.0', port: 8000 },
{ owners: [], address: '::', port: 8080 }
])
expect(out).toEqual({})
})
it('takes the command from ps when the listener tool did not name it', () => {
const out = assembleDevPorts(panes, procs, [{ owners: [{ pid: 102, command: '' }], address: '127.0.0.1', port: 3000 }])
expect(out.a[0].command).toBe('node')
})
it('survives a cyclic ppid chain', () => {
const cyclic = [
{ pid: 100, ppid: 101, command: 'zsh' },
{ pid: 101, ppid: 100, command: 'node' }
]
const out = assembleDevPorts([{ session: 'nt-a', panePid: 100, command: 'zsh' }], cyclic, [
{ owners: [{ pid: 101, command: 'node' }], address: '127.0.0.1', port: 3000 }
])
expect(out.a.map((p) => p.port)).toEqual([3000])
})
})
const probeOut = (listen: string, panes = "##SOCK node-terminal\nnt-a|100|zsh\n##SOCKRC 0\n##SOCK nodeterm-rmt\nno server running on /tmp/x\n##SOCKRC 1"): string =>
['##PANES', panes, '##PROCS', ' 100 1 zsh', ' 102 100 node', '##LISTEN', listen, '##END', ''].join('\n')
describe('parseDevPortsProbe', () => {
it('reads an ss answer', () => {
const r = parseDevPortsProbe(probeOut('##VIA ss\n' + SS_REAL.replace(/pid=210/g, 'pid=102') + '\n##LISTENRC 0'))
expect(r.ok).toBe(true)
expect(r.nodes.a.map((p) => p.port)).toEqual([5173])
})
it('reads an lsof answer, and lsof exit 1 with no output is "no listeners"', () => {
expect(parseDevPortsProbe(probeOut('##VIA lsof\np102\ncnode\nn*:3000\n##LISTENRC 0')).nodes.a[0].port).toBe(3000)
expect(parseDevPortsProbe(probeOut('##VIA lsof\n##LISTENRC 1'))).toEqual({ ok: true, nodes: {} })
})
it('reads the /proc answer', () => {
const r = parseDevPortsProbe(
probeOut(
'##VIA proc\n 0: 0100007F:1435 00000000:0000 0A 0 0 0 1000 0 4242 1\n##FD\n/proc/102/fd:\nl 1 -> socket:[4242]\n/proc/1/fd:\n##LISTENRC 0'
)
)
expect(r).toEqual({ ok: true, nodes: { a: [{ port: 5173, addresses: ['127.0.0.1'], command: 'node', ephemeral: false }] } })
})
it('never turns a failure into "no ports"', () => {
expect(parseDevPortsProbe('').ok).toBe(false)
// cut short: no ##END
expect(parseDevPortsProbe(probeOut('##VIA ss\n##LISTENRC 0').replace('##END', '')).reason).toBe('unreachable')
// no socket answered (broken tmux client on both)
const broken = '##SOCK node-terminal\ntmux: error while loading shared libraries\n##SOCKRC 127\n##SOCK nodeterm-rmt\ntmux: error\n##SOCKRC 127'
expect(parseDevPortsProbe(probeOut('##VIA ss\n##LISTENRC 0', broken)).reason).toBe('unreachable')
// ss failed
expect(parseDevPortsProbe(probeOut('##VIA ss\n##LISTENRC 1')).reason).toBe('unreachable')
// lsof failed WITH output
expect(parseDevPortsProbe(probeOut('##VIA lsof\nlsof: WARNING\n##LISTENRC 1')).reason).toBe('unreachable')
// no tool
expect(parseDevPortsProbe(probeOut('##VIA none'))).toEqual({ ok: false, reason: 'no-listener-tool', nodes: {} })
// an rc file echoing a marker ahead of ours
expect(parseDevPortsProbe('##END\n' + probeOut('##VIA ss\n##LISTENRC 0').replace(/##END\n$/, '')).ok).toBe(false)
})
})
describe('forwardTarget', () => {
it('follows the bind', () => {
expect(forwardTarget(['::1', '127.0.0.1'])).toBe('127.0.0.1')
expect(forwardTarget(['*'])).toBe('127.0.0.1')
expect(forwardTarget(['0.0.0.0'])).toBe('127.0.0.1')
expect(forwardTarget(['::1'])).toBe('::1')
expect(forwardTarget(['::'])).toBe('::1')
expect(forwardTarget(['10.0.0.5'])).toBe('10.0.0.5')
expect(forwardTarget(['fe80::1'])).toBe('fe80::1')
})
it('refuses anything that is not an IP literal', () => {
expect(forwardTarget(['localhost'])).toBeNull()
expect(forwardTarget(['-oProxyCommand=x'])).toBeNull()
expect(forwardTarget([])).toBeNull()
})
})
describe('runners', () => {
it('local: Windows without the session host is unsupported, a throwing exec is unreachable', async () => {
const tmuxBin = (): string => '/usr/bin/tmux'
expect(await collectLocalDevPorts({ tmuxBin, exec: async () => '', platformName: 'win32' })).toEqual({
ok: false,
reason: 'unsupported',
nodes: {}
})
const exec = async (): Promise<string> => {
throw new Error('x')
}
expect((await collectLocalDevPorts({ tmuxBin, exec, platformName: 'linux' })).reason).toBe('unreachable')
})
it("local: asks the APP's tmux by absolute path, quoted — never whatever `tmux` is on PATH", async () => {
// A Mac whose only tmux is the bundled one has none on PATH; a bare `tmux` answered 127 twice.
let seen = ''
await collectLocalDevPorts({
tmuxBin: () => "/Applications/node term.app/Contents/Resources/tmux/bin/tm'ux",
exec: async (cmd) => ((seen = cmd), ''),
platformName: 'darwin'
})
expect(seen).toContain(`'/Applications/node term.app/Contents/Resources/tmux/bin/tm'\\''ux' -L node-terminal list-panes`)
expect(seen).not.toMatch(/^tmux -L/m)
})
it('local: no tmux at all is unsupported (plain shells own no pane tree)', async () => {
const exec = vi.fn(async () => '')
expect((await collectLocalDevPorts({ tmuxBin: () => null, exec, platformName: 'linux' })).reason).toBe('unsupported')
expect(exec).not.toHaveBeenCalled()
})
it('remote: a null (dead master) is unreachable, never empty', async () => {
expect(await fetchRemoteDevPorts('p', async () => null)).toEqual({ ok: false, reason: 'unreachable', nodes: {} })
let seen = ''
await fetchRemoteDevPorts('p', async (_id, cmd) => ((seen = cmd), null))
expect(seen).toBe(devPortsProbeCommand())
})
})