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 os from 'os'
import { describe, expect, it } from 'vitest'
import {
SESSION_SOCKET_REF,
sessionSocketProbe,
controlPathFor,
masterArgs,
childArgs,
remoteTmuxPasteArgs,
remoteTmuxEnterArgs,
probeSaysAbsent,
remoteCapturePaneArgs,
remoteCaptureVisibleArgs,
remotePaneCommandArgs,
remotePaneCwdArgs,
remotePaneProcessArgs,
remoteTerminateForegroundArgs,
remoteListSessionsArgs,
parseRemoteSessionNames,
remoteTmuxPtyArgs,
listDirArgs,
mkDirArgs,
RMT_TMUX_SOCKET,
KILL_TMUX_SOCKETS,
localKillSockets,
localTmuxKillArgs,
remoteTmuxKillArgs,
remoteTmuxKillEverySocketArgs,
hookForwardArgs,
hookForwardCancelArgs,
hookTcpForwardArgs,
hookTcpForwardCancelArgs,
remoteHookEnvArgs,
remoteEndpointFileContents,
remoteTcpEndpointFileContents,
scpArgs,
scpDownArgs,
remoteScpPath
} from './control-master'
import { remoteTmuxPathPrologue } from '../../shared/ssh'
import { VISIBLE_CAPTURE_FORMAT } from '../capture-route'
/** The PATH-append prologue every remote tmux line now starts with (issue #449). */
const TP = remoteTmuxPathPrologue()
// Every command about ONE session probes which socket holds it first (`sessionSocketProbe`).
const SX = `${TP}${sessionSocketProbe('nt-x')}`
const conn = { host: 'h.example.com', user: 'deploy', port: 2222, identityFile: '/k/id' }
/** The option prefix every child ssh shares: self-healing mux (auto + persist, so the first
* child after a cleanly-gone master rebuilds it), keepalives for when the child owns the
* transport, and the identity key (auth matters exactly when mux is unavailable), pinned with
* IdentitiesOnly so a fallback connect can't burn MaxAuthTries on unrelated agent keys. */
const childPrefix = [
'-o', 'ControlMaster=auto',
'-o', 'ControlPath=/s.sock',
'-o', 'ControlPersist=300',
'-o', 'StrictHostKeyChecking=accept-new',
'-o', 'ServerAliveInterval=15',
'-o', 'ServerAliveCountMax=4',
'-p', '2222',
'-o', 'IdentitiesOnly=yes',
'-i', '/k/id'
]
describe('mkDirArgs', () => {
it('mkdir -p the quoted remote path, leaving a leading ~ unquoted', () => {
expect(mkDirArgs(conn, '/s.sock', '~/new dir').join(' ')).toContain(`mkdir -p ~/'new dir'`)
})
})
describe('controlPathFor', () => {
it('returns a SHORT, space-free socket path under ~/.nodeterm/ssh-cm (not the long/spaced userData)', () => {
// Regression: macOS userData is `~/Library/Application Support/<app>` — too long for a unix
// socket (sun_path 104, minus ssh's ~17-char bind suffix) AND has a space ssh's `-o` rejects.
const cp = controlPathFor('a-fairly-long-project-id-0123456789')
expect(cp.startsWith(`${os.homedir()}/.nodeterm/ssh-cm/`)).toBe(true)
expect(cp.endsWith('.sock')).toBe(true)
expect(cp).not.toContain(' ')
// Must stay well under 104 even after ssh appends its ~17-char temp suffix while binding.
expect(cp.length).toBeLessThan(87)
})
it('is deterministic and distinct per project id', () => {
expect(controlPathFor('proj1')).toBe(controlPathFor('proj1'))
expect(controlPathFor('proj1')).not.toBe(controlPathFor('proj2'))
})
})
describe('masterArgs', () => {
it('builds a backgrounded multiplexing master with the control path + identity + port', () => {
expect(masterArgs(conn, '/ud/ssh-cm/p.sock')).toEqual([
'-M', '-N',
'-o', 'ControlMaster=auto',
'-o', 'ControlPath=/ud/ssh-cm/p.sock',
'-o', 'ControlPersist=300',
'-o', 'BatchMode=no',
'-o', 'StrictHostKeyChecking=accept-new',
'-o', 'ServerAliveInterval=15',
'-o', 'ServerAliveCountMax=4',
'-o', 'ConnectTimeout=15',
'-o', 'PasswordAuthentication=no',
'-o', 'KbdInteractiveAuthentication=no',
'-o', 'AddKeysToAgent=yes',
'-p', '2222',
'-o', 'IdentitiesOnly=yes',
'-i', '/k/id',
'[email protected]'
])
})
it('loads unlocked keys into the agent: the agent, not the app, is the passphrase cache', () => {
// Measured against a real sshd: with this option the second connect (fresh master, fresh
// pid) authenticates through the agent with ZERO askpass invocations; without it every
// single connect re-prompted. Deleting ssh-passphrase-cache.ts rides on this line.
expect(masterArgs(conn, '/s.sock')).toContain('AddKeysToAgent=yes')
})
it('pins the offer to the configured key (IdentitiesOnly) so agent keys cannot burn MaxAuthTries', () => {
// Measured: 8 junk agent keys + `-i` ended the connection with "Too many authentication
// failures" (server default MaxAuthTries=6) before the configured key was ever offered.
// The agent still SIGNS the pinned key, so prompt-free reconnects are unaffected.
const args = masterArgs(conn, '/s.sock').join(' ')
expect(args).toContain('-o IdentitiesOnly=yes -i /k/id')
})
it('omits IdentitiesOnly (not just -i) when no identityFile is configured: agent keys must stay usable', () => {
// IdentitiesOnly with NO -i would stop ssh from offering agent keys at all, which would
// break the very reconnect path AddKeysToAgent provides. It must ride with -i or not at all.
const bare = { host: 'h.example.com', user: 'deploy', port: 2222 }
const args = masterArgs(bare, '/s.sock')
expect(args).not.toContain('-i')
expect(args.join(' ')).not.toContain('IdentitiesOnly')
})
})
describe('agent pin (identityAgentSock, issue #427)', () => {
// A conn the `ssh -G` probe marked: this host's effective config says `IdentityAgent
// SSH_AUTH_SOCK` (or equivalent), so the ambient login-agent socket is pinned on argv — a
// command-line -o beats both the config line and the app-agent env override.
const pinned = { ...conn, identityAgentSock: '/tmp/launchd.abc/Listeners' }
it('masterArgs pins the login agent and drops the forced AddKeysToAgent', () => {
const args = masterArgs(pinned, '/s.sock')
expect(args.join(' ')).toContain('-o IdentityAgent=/tmp/launchd.abc/Listeners')
// Forcing AddKeysToAgent=yes at a LOGIN agent would load an askpass-unlocked key into it
// until logout — the exact leak the app-private agent exists to close. The user's own config
// decides for a pinned host.
expect(args).not.toContain('AddKeysToAgent=yes')
})
it('childArgs carries the pin too: the ControlMaster=auto fallback re-authenticates for real', () => {
const args = childArgs(pinned, '/s.sock', 'tmux ls')
expect(args.join(' ')).toContain('-o IdentityAgent=/tmp/launchd.abc/Listeners')
expect(args.at(-1)).toBe('tmux ls')
})
it('scp up AND down carry the pin: scp re-authenticates when the master socket is gone', () => {
expect(scpArgs(pinned, '/s.sock', '/l/f', '/r/f').join(' ')).toContain(
'-o IdentityAgent=/tmp/launchd.abc/Listeners'
)
expect(scpDownArgs(pinned, '/s.sock', '/r/f', '/l/f').join(' ')).toContain(
'-o IdentityAgent=/tmp/launchd.abc/Listeners'
)
})
it('an unpinned conn is byte-identical to the pre-#427 argv (the exact-array tests above are the pin)', () => {
// Belt and braces beside the toEqual pins: absence of the option, not just equality.
for (const args of [masterArgs(conn, '/s.sock'), childArgs(conn, '/s.sock'), scpArgs(conn, '/s.sock', '/l', '/r')]) {
expect(args.join(' ')).not.toContain('IdentityAgent=')
}
})
})
describe('childArgs', () => {
it('muxes over the master socket, self-healing (auto + persist), and appends a remote command', () => {
expect(childArgs(conn, '/s.sock', 'tmux ls')).toEqual([...childPrefix, '[email protected]', 'tmux ls'])
})
it('omits -i AND IdentitiesOnly when the connection has no identityFile', () => {
const bare = { host: 'h.example.com', user: 'deploy', port: 2222 }
const args = childArgs(bare, '/s.sock', 'tmux ls')
expect(args).not.toContain('-i')
expect(args.join(' ')).not.toContain('IdentitiesOnly') // would disable agent keys outright
expect(args.at(-2)).toBe('[email protected]')
})
it('regression: never ControlMaster=no — a dead master made every child a silent fresh direct connection', () => {
expect(childArgs(conn, '/s.sock')).not.toContain('ControlMaster=no')
})
})
describe('remoteTmuxPasteArgs', () => {
const TMUX = `tmux -L ${SESSION_SOCKET_REF}`
const BUF = 'nt-paste-deadbeef'
const cmd = (session: string, enter: boolean): string =>
remoteTmuxPasteArgs(conn, '/s.sock', session, BUF, enter).slice(-1)[0]
it('is ONE remote tmux invocation: buffer from stdin, gated copy-mode cancel, paste, Enter', () => {
expect(remoteTmuxPasteArgs(conn, '/s.sock', 'nt-x', BUF, true)).toEqual([
...childPrefix,
'[email protected]',
`${SX}${TMUX} load-buffer -b ${BUF} - ';' ` +
`if-shell -F -t '=nt-x:' '#{pane_in_mode}' 'send-keys -t =nt-x: -X cancel' ';' ` +
`paste-buffer -d -p -r -b ${BUF} -t '=nt-x:' ';' send-keys -t '=nt-x:' Enter`
])
})
it('omits the Enter for a dictation insert (enter:false)', () => {
expect(cmd('nt-x', false)).not.toContain('Enter')
expect(cmd('nt-x', false).endsWith(`paste-buffer -d -p -r -b ${BUF} -t '=nt-x:'`)).toBe(true)
})
// The rule this PR is here to enforce: the payload is not on the command line at all, so there
// is no `posixQuote` of an attacker-influenced body left to get wrong, and no MAX_ARG_STRLEN.
it('carries NO payload — the text reaches the remote tmux over stdin', () => {
const line = cmd('nt-x', true)
expect(line).toContain(`load-buffer -b ${BUF} -`)
expect(line).not.toContain(' -l')
expect(line).not.toContain('set-buffer')
})
// The version floor, stated as a negative. `#{bracket_paste_flag}` first shipped in tmux 3.7;
// on the REMOTE host's older tmux it expanded to '' and the old conditional took its `else`
// branch, delivering raw newlines. Nothing may reintroduce a dependency on it.
it('never probes #{bracket_paste_flag} — the framing decision belongs to `paste-buffer -p`', () => {
const line = cmd('nt-x', true)
expect(line).not.toContain('bracket_paste_flag')
expect(line).not.toContain('display-message')
expect(line).toContain('paste-buffer -d -p -r')
})
// `-r` is load-bearing: without it tmux rewrites every `\n` in the buffer to `\r`, which is a
// submit per line — the exact bug the frame exists to prevent.
it('keeps -r so a newline stays a newline', () => {
expect(cmd('nt-x', true)).toContain('-p -r')
})
// `#{...}` at the start of a word is a COMMENT to the remote sh; the inner command must arrive
// as one tmux argument. Both are single-quoted, and `control-master.realsh.test.ts`'s sibling
// (`tmux-paste.realtmux.test.ts`) runs this very line through a real sh into a real tmux.
it('quotes the format and the inner command so the remote shell passes them through', () => {
expect(cmd('nt-x', true)).toContain(`if-shell -F -t '=nt-x:' '#{pane_in_mode}' 'send-keys -t =nt-x: -X cancel'`)
})
it('refuses a session id this app did not generate — it is spliced unquoted', () => {
expect(() => remoteTmuxPasteArgs(conn, '/s.sock', 'nt-x; kill-server', BUF, true)).toThrow(
/unsafe tmux paste target/
)
expect(() => remoteTmuxPasteArgs(conn, '/s.sock', 'nt-x', "buf'; id; #", true)).toThrow(
/unsafe tmux buffer name/
)
})
})
describe('remoteTmuxEnterArgs', () => {
// `sendText('', { enter: true })` means "submit what is composed". It cannot ride the paste
// command list: `load-buffer -` with zero bytes creates no buffer, the paste fails, and tmux
// abandons the rest of the list — the Enter with it.
it('sends a bare Enter and nothing else', () => {
expect(remoteTmuxEnterArgs(conn, '/s.sock', 'nt-x')).toEqual([
...childPrefix,
'[email protected]',
`${SX}tmux -L ${SESSION_SOCKET_REF} send-keys -t '=nt-x:' Enter`
])
})
it('steps the cursor left first for a typed message ending in a backslash', () => {
const args = remoteTmuxEnterArgs(conn, '/s.sock', 'nt-x', { cursorLeftFirst: true })
expect(args[args.length - 1]).toBe(`${SX}tmux -L ${SESSION_SOCKET_REF} send-keys -t '=nt-x:' Left Enter`)
})
})
describe('remoteCapturePaneArgs', () => {
it('captures the whole scrollback (-S -) when full', () => {
const args = remoteCapturePaneArgs(conn, '/s.sock', 'nt-x', true)
expect(args[args.length - 1]).toBe(`${SX}tmux -L ${SESSION_SOCKET_REF} capture-pane -p -e -t '=nt-x:' -S -`)
})
it('captures the recent ~200 lines (-S -200) when not full', () => {
const args = remoteCapturePaneArgs(conn, '/s.sock', 'nt-x', false)
expect(args[args.length - 1]).toBe(`${SX}tmux -L ${SESSION_SOCKET_REF} capture-pane -p -e -t '=nt-x:' -S -200`)
})
})
describe('remoteCaptureVisibleArgs', () => {
it('the visible capture never asks for history', () => {
const args = remoteCaptureVisibleArgs({ host: 'h', user: 'u' } as never, '/tmp/cp', 'nt-abc')
const cmd = args.join(' ')
expect(cmd).toContain("capture-pane -p -e -t '=nt-abc:'")
expect(cmd).not.toMatch(/-S\b/)
})
it('captures and reads the cursor in ONE remote tmux invocation, exact targets on both', () => {
const args = remoteCaptureVisibleArgs(conn, '/s.sock', 'nt-x')
expect(args.slice(0, childPrefix.length)).toEqual(childPrefix)
expect(args[args.length - 1]).toBe(
`${SX}tmux -L ${SESSION_SOCKET_REF} capture-pane -p -e -t '=nt-x:' ';' ` +
`display-message -p -t '=nt-x:' '${VISIBLE_CAPTURE_FORMAT}'`
)
})
})
describe('remotePaneCommandArgs', () => {
it('asks the remote tmux for the pane_current_command of the session', () => {
const args = remotePaneCommandArgs(conn, '/s.sock', 'nt-x')
expect(args[args.length - 1]).toBe(
`${SX}tmux -L ${SESSION_SOCKET_REF} display-message -p -t '=nt-x:' '#{pane_current_command}'`
)
})
})
describe('remotePaneCwdArgs', () => {
it('asks the remote tmux for the pane_current_path of the session', () => {
const args = remotePaneCwdArgs(conn, '/s.sock', 'nt-x')
expect(args[args.length - 1]).toBe(
`${SX}tmux -L ${SESSION_SOCKET_REF} display-message -p -t '=nt-x:' '#{pane_current_path}'`
)
})
})
describe('remote foreground process termination', () => {
it('reads pane pid + command through the existing ControlMaster', () => {
const args = remotePaneProcessArgs(conn, '/s.sock', 'nt-x')
expect(args[args.length - 1]).toBe(
`${SX}tmux -L ${SESSION_SOCKET_REF} display-message -p -t '=nt-x:' '#{pane_pid}|#{pane_current_command}'`
)
})
it('revalidates the foreground group and never targets the pane shell group', () => {
const args = remoteTerminateForegroundArgs(conn, '/s.sock', 33293)
const command = args[args.length - 1]
expect(command).toContain('ps -o tpgid= -p 33293')
expect(command).toContain('[ "$tpgid" -ne 33293 ]')
expect(command).toContain('kill -TERM -- "-$tpgid"')
})
it('refuses an invalid pane pid before building a remote shell command', () => {
expect(() => remoteTerminateForegroundArgs(conn, '/s.sock', -1)).toThrow('invalid-pane-pid')
})
})
describe('remoteListSessionsArgs', () => {
it('asks the remote nodeterm tmux socket for session names only', () => {
const args = remoteListSessionsArgs(conn, '/cm/p1')
const cmd = args[args.length - 1]
expect(cmd).toContain('tmux -L node-terminal list-sessions')
expect(cmd).toContain('#{session_name}')
})
it('routes over the given control path', () => {
expect(remoteListSessionsArgs(conn, '/cm/p1').join(' ')).toContain('/cm/p1')
})
})
describe('parseRemoteSessionNames', () => {
it('returns one entry per non-empty line, trimmed', () => {
expect(parseRemoteSessionNames('nt-a\nnt-b\n')).toEqual(['nt-a', 'nt-b'])
})
it('ignores blank lines and surrounding whitespace', () => {
expect(parseRemoteSessionNames('\n nt-a \n\n')).toEqual(['nt-a'])
})
it('is empty for empty output — a host with no sessions is an answer, not a failure', () => {
expect(parseRemoteSessionNames('')).toEqual([])
})
})
describe('remoteTmuxPtyArgs', () => {
it('runs the remote tmux command as a forced-TTY child (-t then childArgs)', () => {
const args = remoteTmuxPtyArgs(conn, '/s.sock', 'nt-x', '/srv/app')
expect(args[0]).toBe('-t')
const cmd = args[args.length - 1]
expect(args.slice(1)).toEqual(childArgs(conn, '/s.sock', cmd))
})
it('splices extraEnv -e pairs right after new-session -A (before -s)', () => {
const args = remoteTmuxPtyArgs(conn, '/s.sock', 'nt-x', '/srv/app', undefined, undefined, [
'-e', 'NODETERM_HOOK_ENDPOINT=/r/ep.env',
'-e', 'NODETERM_NODE_ID=nt-x'
])
const cmd = args[args.length - 1]
// Each token is posix-quoted: this is ONE remote shell line, and the pair values carry the raw
// node id (see control-master.injection.test.ts for the injection this closes).
expect(cmd).toContain(
`new-session -A '-e' 'NODETERM_HOOK_ENDPOINT=/r/ep.env' '-e' 'NODETERM_NODE_ID=nt-x' -s`
)
})
it('threads confPath to remoteTmuxCommand as a `-f` source before new-session', () => {
const args = remoteTmuxPtyArgs(conn, '/s.sock', 'nt-x', '/srv/app', undefined, undefined, [], '/home/u/.nodeterm/tmux.conf')
const cmd = args[args.length - 1]
expect(cmd).toContain(`-f '/home/u/.nodeterm/tmux.conf' new-session -A`)
})
describe('sessionEnv prologue (argv-free credential delivery)', () => {
it('prepends a bounded wait + source + rm before the tmux command', () => {
const args = remoteTmuxPtyArgs(
conn, '/s.sock', 'nt-x', '/srv/app', undefined, undefined, [], '/home/u/.nodeterm/tmux.conf',
{ file: '/home/u/.nodeterm/env/nt-x.env', extraKeys: [] }
)
const cmd = args[args.length - 1]
// The credential file is SOURCED, then removed — never a value on the command line.
expect(cmd).toContain(". '/home/u/.nodeterm/env/nt-x.env'")
expect(cmd).toContain("rm -f '/home/u/.nodeterm/env/nt-x.env'")
expect(cmd).toMatch(/while \[ ! -f '\/home\/u\/\.nodeterm\/env\/nt-x\.env' \]/)
// The prologue runs BEFORE the tmux new-session it guards.
expect(cmd.indexOf(". '")).toBeLessThan(cmd.indexOf('new-session'))
})
it('appends custom (non-gateway) env NAMES to update-environment — names only, never values', () => {
const args = remoteTmuxPtyArgs(
conn, '/s.sock', 'nt-x', '/srv/app', undefined, undefined, [], undefined,
{ file: '/h/.nodeterm/env/nt-x.env', extraKeys: ['MY_CUSTOM_TOKEN'] }
)
const cmd = args[args.length - 1]
expect(cmd).toContain('set-option -ga update-environment MY_CUSTOM_TOKEN')
})
it('drops a non-identifier env name at the splice point (belt to session-env.ts braces)', () => {
const args = remoteTmuxPtyArgs(
conn, '/s.sock', 'nt-x', '/srv/app', undefined, undefined, [], undefined,
{ file: '/h/.nodeterm/env/nt-x.env', extraKeys: ['BAD;NAME', 'GOOD_ONE'] }
)
const cmd = args[args.length - 1]
expect(cmd).toContain('update-environment GOOD_ONE')
expect(cmd).not.toContain('BAD;NAME')
})
})
})
describe('hook forwarding', () => {
it('hookForwardArgs builds a reverse unix-socket forward over the master', () => {
expect(hookForwardArgs(conn, '/s.sock', '/home/u/.nodeterm/h.sock', 51234)).toEqual([
'-O', 'forward', '-R', '/home/u/.nodeterm/h.sock:127.0.0.1:51234',
'-o', 'ControlPath=/s.sock', '-p', '2222', '[email protected]'
])
})
it('hookForwardCancelArgs mirrors it with -O cancel', () => {
expect(hookForwardCancelArgs(conn, '/s.sock', '/r.sock', 51234)[1]).toBe('cancel')
})
it('remoteHookEnvArgs builds tmux -e pairs (endpoint + node id + version)', () => {
expect(remoteHookEnvArgs('/r/.nodeterm/ep.env', 'nt-x', '1')).toEqual([
'-e', 'NODETERM_HOOK_ENDPOINT=/r/.nodeterm/ep.env',
'-e', 'NODETERM_NODE_ID=nt-x',
'-e', 'NODETERM_HOOK_VERSION=1'
])
})
it('emits NODETERM_NODE_ID as the RAW persistKey (not the nt-<id> tmux session name)', () => {
// Cross-boundary contract: the remote hook env's NODETERM_NODE_ID MUST equal what the
// LOCAL path's hookServer.buildPtyEnv(persistKey, …) sets — i.e. the RAW React Flow node id.
// Canvas.tsx onAgentStatus keys agentStatus.byId / selection off that raw id with no `nt-`
// stripping, so passing the session name (`nt-<id>`) would orphan every remote event.
const persistKey = 'node-abc'
const env = remoteHookEnvArgs('/ep', persistKey, '1')
expect(env).toContain(`NODETERM_NODE_ID=${persistKey}`)
// Guard against a regression that passes sessionName(persistKey) = `nt-<id>`.
expect(env).not.toContain(`NODETERM_NODE_ID=nt-${persistKey}`)
})
it('arms canvas control on a remote grok session, and not on a plain terminal', () => {
// Same gate as the local hookServer.buildPtyEnv, so an SSH grok node gets the shim armed with
// no extra install: the skill is already written to the host's $HOME/.claude/skills, which grok
// scans by default.
expect(remoteHookEnvArgs('/ep', 'n1', '1', 'grok')).toEqual([
'-e', 'NODETERM_HOOK_ENDPOINT=/ep',
'-e', 'NODETERM_NODE_ID=n1',
'-e', 'NODETERM_HOOK_VERSION=1',
'-e', 'NODETERM_AGENT_ID=grok',
'-e', 'NODETERM_CANVAS_CONTROL=1'
])
expect(remoteHookEnvArgs('/ep', 'n1', '1')).not.toContain('NODETERM_CANVAS_CONTROL=1')
})
it('remoteEndpointFileContents writes SOCK/TOKEN/VERSION and the remote token dir, each quoted', () => {
expect(remoteEndpointFileContents('/r.sock', 'tok', '2', '/home/u/.nodeterm/node-tokens')).toBe(
"NODETERM_HOOK_SOCK='/r.sock'\nNODETERM_HOOK_TOKEN='tok'\nNODETERM_HOOK_VERSION='2'\n" +
"NODETERM_NODE_TOKEN_DIR='/home/u/.nodeterm/node-tokens'\n"
)
})
it('remoteEndpointFileContents quotes a spaced remote path so /bin/sh sources it cleanly', () => {
const body = remoteEndpointFileContents(
'/home/u/App Support/hook.sock',
'tok',
'2',
'/home/u/App Support/node-tokens'
)
expect(body).toContain("NODETERM_HOOK_SOCK='/home/u/App Support/hook.sock'\n")
expect(body).toContain("NODETERM_NODE_TOKEN_DIR='/home/u/App Support/node-tokens'\n")
})
it('hookTcpForwardArgs binds the host side to loopback only, and its cancel mirrors it', () => {
expect(hookTcpForwardArgs(conn, '/s.sock', 45001, 51234)).toEqual([
'-O', 'forward', '-R', '127.0.0.1:45001:127.0.0.1:51234',
'-o', 'ControlPath=/s.sock', '-p', '2222', '[email protected]'
])
const cancel = hookTcpForwardCancelArgs(conn, '/s.sock', 45001, 51234)
expect(cancel.slice(0, 4)).toEqual(['-O', 'cancel', '-R', '127.0.0.1:45001:127.0.0.1:51234'])
})
it('hookTcpForwardArgs refuses a non-port value instead of building an ssh argument from it', () => {
expect(() => hookTcpForwardArgs(conn, '/s.sock', 0, 51234)).toThrow()
expect(() => hookTcpForwardArgs(conn, '/s.sock', 70000, 51234)).toThrow()
expect(() => hookTcpForwardArgs(conn, '/s.sock', 1.5, 51234)).toThrow()
})
it('remoteTcpEndpointFileContents advertises the port and empties the socket', () => {
expect(remoteTcpEndpointFileContents(45001, 'tok', '2', '/home/u/.nodeterm/node-tokens')).toBe(
"NODETERM_HOOK_SOCK=''\nNODETERM_HOOK_PORT='45001'\nNODETERM_HOOK_TOKEN='tok'\nNODETERM_HOOK_VERSION='2'\n" +
"NODETERM_NODE_TOKEN_DIR='/home/u/.nodeterm/node-tokens'\n"
)
})
})
describe('scpArgs', () => {
it('reuses the master socket, uses scp -P for the port, and passes the RAW absolute remote path', () => {
const j = scpArgs(conn, '/s.sock', '/local/i m.png', '/home/u/.nodeterm/uploads/t/i m.png').join(' ')
expect(j).toContain('-o ControlPath=/s.sock')
expect(j).toContain('-o BatchMode=yes') // fail fast on a fallback connection (no tty prompt)
expect(j).toContain('-P 2222') // scp uses uppercase -P
expect(j).toContain('-i /k/id') // identityFile
// Modern scp uses SFTP (no remote shell), so the remote path must be RAW (NOT quoted) — a quoted
// path makes the SFTP server open a file literally named `'…'`. SFTP handles spaces literally.
expect(j).toContain(`/local/i m.png [email protected]:/home/u/.nodeterm/uploads/t/i m.png`)
})
})
describe('scpDownArgs', () => {
it('pulls remote → local over the master, with the remote side after host: (never an option)', () => {
const j = scpDownArgs(conn, '/s.sock', '/srv/app/notes.md', '/Users/e/Downloads/notes.md.part').join(' ')
expect(j).toContain('-o ControlPath=/s.sock')
expect(j).toContain('-o BatchMode=yes')
expect(j).toContain('-P 2222')
expect(j).toContain('[email protected]:/srv/app/notes.md /Users/e/Downloads/notes.md.part')
expect(j).not.toContain(' -r ')
})
it('adds -r for a directory tree', () => {
expect(scpDownArgs(conn, '/s.sock', '/srv/app/docs', '/d/docs.part', true)).toContain('-r')
})
it('a leading `-` in the remote path cannot become an scp option (it rides behind host:)', () => {
const args = scpDownArgs(conn, '/s.sock', '-oProxyCommand=touch /tmp/pwned', '/d/x')
expect(args).not.toContain('-oProxyCommand=touch /tmp/pwned')
expect(args).toContain('[email protected]:-oProxyCommand=touch /tmp/pwned')
})
it('sends a ~-relative path as RELATIVE — SFTP has no shell to expand the tilde', () => {
// The regression this guards: an SSH project's remoteCwd is home-relative, so the Explorer's
// paths are `~/…`; a literal `~` made scp look for a directory actually named `~`.
expect(remoteScpPath('~/work/report.pdf')).toBe('work/report.pdf')
expect(remoteScpPath('~')).toBe('.')
expect(remoteScpPath('/srv/app/x')).toBe('/srv/app/x')
expect(scpDownArgs(conn, '/s.sock', '~/a b.txt', '/d/x').join(' ')).toContain(
'[email protected]:a b.txt /d/x'
)
})
})
describe('listDirArgs', () => {
it('lists directory entries of a quoted absolute path', () => {
expect(listDirArgs(conn, '/s.sock', '/srv/app')).toEqual([
...childPrefix,
'[email protected]',
`ls -1Ap '/srv/app'`
])
})
it('leaves a bare ~ unquoted so the remote shell expands it', () => {
expect(listDirArgs(conn, '/s.sock', '~')).toEqual([
...childPrefix,
'[email protected]',
`ls -1Ap ~`
])
})
it('tilde-expands a home-relative path, quoting the remainder', () => {
expect(listDirArgs(conn, '/s.sock', '~/my dir')).toEqual([
...childPrefix,
'[email protected]',
`ls -1Ap ~/'my dir'`
])
})
})
describe('probeSaysAbsent (has-session probe discrimination)', () => {
it('only tmux\'s own exit 1 is evidence of absence', () => {
expect(probeSaysAbsent(Object.assign(new Error('exit 1'), { code: 1 }))).toBe(true)
})
it('transport/spawn failures are a failed READ, never absence', () => {
// ssh's own failure (dead or mid-reconnect ControlMaster).
expect(probeSaysAbsent(Object.assign(new Error('exit 255'), { code: 255 }))).toBe(false)
// tmux off the remote PATH.
expect(probeSaysAbsent(Object.assign(new Error('exit 127'), { code: 127 }))).toBe(false)
// spawn-level errors carry a string code, or none at all.
expect(probeSaysAbsent(Object.assign(new Error('spawn'), { code: 'EAGAIN' }))).toBe(false)
expect(probeSaysAbsent(new Error('plain'))).toBe(false)
expect(probeSaysAbsent(undefined)).toBe(false)
expect(probeSaysAbsent(null)).toBe(false)
})
})
describe('killing a session by name (both sockets, exact target)', () => {
// Two nodeterm tmux sockets can live on a host: `node-terminal` for every nodeterm (running ON
// the machine or SSH-ing INTO it — one socket since the 2026-11 unification), `nodeterm-rmt` for
// sessions a pre-unification build's SSH projects left behind. The session-memory sweep lists
// BOTH, so a kill routed to one of them promised something it could not do for every row off
// the other.
it('covers both sockets a nodeterm session can live on', () => {
expect([...KILL_TMUX_SOCKETS].sort()).toEqual(['node-terminal', 'nodeterm-rmt'])
})
it('targets the session EXACTLY — never tmux prefix matching', () => {
// A speculative kill misses by design, and a miss is when tmux falls back to fnmatch and then
// to prefix matching. Node ids end in a counter, so `nt-a-1` is a prefix of `nt-a-12`: without
// `=` a miss could kill a different session.
expect(localTmuxKillArgs('node-terminal', 'nt-a-1')).toEqual([
'-L', 'node-terminal', 'kill-session', '-t', '=nt-a-1'
])
expect(remoteTmuxKillArgs(conn, '/s.sock', 'nt-a-1').at(-1)).toContain("-t '=nt-a-1'")
})
it('aims a local destroy at the socket we hold, whatever the caller asked for', () => {
// Holding the session means we KNOW which socket it is on, so the fan-out flag is irrelevant:
// one kill either way. This is what keeps the ordinary node-x path at exactly one kill.
expect(localKillSockets('node-terminal')).toEqual(['node-terminal'])
expect(localKillSockets('node-terminal', true)).toEqual(['node-terminal'])
})
it('fans a socket-less kill out only when the caller opts in', () => {
// Holding nothing means the name is all we have — but the unheld branch is NOT rare (an
// ordinary node-x on a node never mounted in this process takes it), so the blast radius is
// the caller's to ask for. Only the session-memory panel, which swept BOTH sockets, does.
expect(localKillSockets(null)).toEqual(['node-terminal'])
expect([...localKillSockets(null, true)].sort()).toEqual(['node-terminal', 'nodeterm-rmt'])
})
it('kills on the socket that HOLDS the session by default, and on a named one explicitly', () => {
expect(remoteTmuxKillArgs(conn, '/s.sock', 'nt-x').at(-1)).toBe(
`${SX}tmux -L ${SESSION_SOCKET_REF} kill-session -t '=nt-x'`
)
expect(remoteTmuxKillArgs(conn, '/s.sock', 'nt-x', 'nodeterm-rmt').at(-1)).toBe(
`${TP}tmux -L nodeterm-rmt kill-session -t '=nt-x'`
)
})
it('kills a name on EVERY remote socket, one ssh invocation each', () => {
const runs = remoteTmuxKillEverySocketArgs(conn, '/s.sock', 'nt-x')
expect(runs).toHaveLength(2)
expect(runs.map((r) => r.at(-1)).sort()).toEqual([
`${TP}tmux -L node-terminal kill-session -t '=nt-x'`,
`${TP}tmux -L nodeterm-rmt kill-session -t '=nt-x'`
])
// Each is a complete child-ssh argv, not a bare command.
for (const r of runs) expect(r.slice(0, childPrefix.length)).toEqual(childPrefix)
})
})
// The `remoteFramedDelivery` suite that lived here is gone with the plan itself (issue #453) —
// the envelope now rides `remotePasteDelivery` (enter=true); see the tombstones in
// control-master.ts and tmux-naming.ts.
describe('sessionSocketProbe — adopting a session the pre-unification build left on the legacy socket', () => {
it('is pinned text: unified socket first, legacy only on a miss, stdin never read', () => {
expect(sessionSocketProbe('nt-x')).toBe(
'_nts=node-terminal; ' +
'tmux -L node-terminal has-session -t "=nt-x" </dev/null >/dev/null 2>&1 || ' +
'{ tmux -L nodeterm-rmt has-session -t "=nt-x" </dev/null >/dev/null 2>&1 && _nts=nodeterm-rmt; }; '
)
expect(SESSION_SOCKET_REF).toBe('"$_nts"')
})
it('never splices an id it did not expect: no probe, unified socket', () => {
for (const hostile of ['nt-x;id', 'nt-$(id)', 'nt-"x', "nt-'x", 'nt x', '']) {
expect(sessionSocketProbe(hostile)).toBe('_nts=node-terminal; ')
}
})
it('lists BOTH sockets for the warm/cold decision, keeping the unified exit code', () => {
const cmd = remoteListSessionsArgs(conn, '/cm/p1').at(-1)!
expect(cmd).toContain("tmux -L node-terminal list-sessions -F '#{session_name}'")
expect(cmd).toContain("tmux -L nodeterm-rmt list-sessions -F '#{session_name}' 2>/dev/null")
expect(cmd.endsWith('exit $r')).toBe(true)
})
})