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
// The remote half of the desktop's "Share with team": every command it runs on the SSH host,
// generated here and run over the project's ControlMaster by src/main. Generated shell no compiler
// checks, so share-team-remote.test.ts runs each one under a real /bin/sh against a fake host.
// Rules:
// - every command is `sh -c '<script>'`. The login shell (sh, bash, zsh or fish) still parses that
// one line to find `sh` and its single-quoted argument; only the script itself runs under sh.
// Inside fish single quotes `\'` and `\\` are escapes, so a nested quote does not survive every
// login shell: a VALUE embedded in a script that contains `'` or `\` is refused, never
// nested-quoted, and the scripts' own text carries neither sequence;
// - fence markers are printed QUOTED, because an unquoted `#` starts a comment;
// - paths are quoted;
// - session names come only from `sessionName`, for safe node ids only;
// - kills target `=nt-<id>` exactly — the project's OWN node ids — on the host's `node-terminal`
// only, never the every-socket fan-out used elsewhere. Since the 2026-11 socket unification this
// is the same socket the server core resumes on: the kill runs BEFORE the resume, which is what
// keeps one process per conversation;
// - the probe never RUNS an installed server it has not first recognised as new enough: a build
// from before the `team` CLI ignores `team` and boots a whole second server.
import { posixQuote, quoteRemotePath, remoteTmuxPathPrologue } from '../../shared/ssh'
import type { ShareProbe } from '../../shared/share-team'
import { isSafeNodeId } from '../../shared/safe-id'
import { LEGACY_RMT_TMUX_SOCKET, RMT_TMUX_SOCKET } from './control-master'
import { sessionName } from '../tmux-naming'
import { CONTROL_RE } from '../relay/team-admin'
import { isRecord } from '../../shared/is-record'
export const SERVER_INSTALL_URL = 'https://raw.githubusercontent.com/eneskirca/nodeterm/main/scripts/install-server.sh'
/** Where a root-installed nodeterm-server's unit lives (the installer's system mode). */
const SYSTEM_UNIT_PATH = '/etc/systemd/system/nodeterm-server.service'
/** The most of `team status --json` the probe carries back; the reply is a few hundred bytes. */
const STATUS_MAX = 65536
/** The most of a non-JSON team reply quoted in an error. */
const SHOWN_MAX = 300
/** The longest the probe lets the installed server answer `team status`, in seconds. The CLI only
* asks the running server over a local socket, so a healthy answer takes well under a second. */
const STATUS_TIMEOUT_S = 10
/**
* Text that only a server bundle which knows `team bootstrap` carries: its usage row
* (`src/server/team-cli.ts`, pinned there by a test). The probe greps `main.cjs` for it instead of
* running `team --help`, because a bundle from before the `team` CLI ignores `team` and boots a
* full second server on the live data dir. The bundle is not minified, so the literal survives.
*/
export const BOOTSTRAP_MARKER = 'bootstrap --owner-key'
const CONTROL_G = new RegExp(CONTROL_RE.source, 'gu')
const sh = (script: string): string => `sh -c ${posixQuote(script)}`
const QUOTE_OR_BACKSLASH = /['\\]/
/** Refuse a value that cannot be nested inside `sh -c '…'` for every login shell (see the header). */
function refuseNested(value: string, what: string): void {
if (QUOTE_OR_BACKSLASH.test(value)) {
throw new Error(`${what} contains a quote or backslash, which cannot be passed safely to every login shell.`)
}
}
/** The official installer, downloaded first: `curl … | bash` runs an EMPTY script and exits 0 when
* the download fails (no pipefail), so a failed download would look like a successful install.
* The temp file goes on every exit: a hang-up or kill (the ssh session dropped, the runner's
* timeout) runs the EXIT trap through the signal traps, which sh does not do on its own. */
export const SHARE_INSTALL_SCRIPT = [
'f=$(mktemp) || exit 1',
`trap 'rm -f "$f"' EXIT`,
"trap 'exit 129' HUP",
"trap 'exit 130' INT",
"trap 'exit 143' TERM",
`if ! curl -fsSL ${posixQuote(SERVER_INSTALL_URL)} -o "$f"; then echo 'nodeterm: could not download the installer.' >&2; exit 1; fi`,
'bash "$f"; rc=$?',
'exit $rc'
].join('\n')
/**
* One round trip that tells `sharePlan` everything: the OS and login, whether git/curl exist, which
* unit runs nodeterm-server and with which node + main.cjs + data dir, the install meta, whether
* that build knows `team bootstrap`, whether the CLI answers `team status`, the real paths of the
* home directory and the project folder, and the live panes on this desktop's remote tmux socket.
* Read by `parseShareProbe`.
*
* Bootstrap support is read from main.cjs's text (`BOOTSTRAP_MARKER`), and the server is run only
* when that text is there: under `timeout`, with no stdin. A host with no `timeout` binary does
* not run it at all, and its status is reported unknown.
*
* `systemUnit` exists so a test can point the system-unit check at a fake host tree; the only
* production value is the default.
*/
export function shareProbeCommand(remoteCwd: string, systemUnit: string = SYSTEM_UNIT_PATH): string {
refuseNested(remoteCwd, 'The folder path')
refuseNested(systemUnit, 'The system unit path')
return sh(
[
// `set -- $X` below splits the unit's ExecStart into words; it must never glob them.
'set -f',
"echo '##NTP 1'",
`printf '##OS %s\\n' "$(uname -s 2>/dev/null)"`,
`printf '##UID %s\\n' "$(id -u 2>/dev/null)"`,
`printf '##USER %s\\n' "$(id -un 2>/dev/null)"`,
`printf '##HOME %s\\n' "$HOME"`,
// The home's REAL path: the plan refuses to share the home itself or anything above it.
`printf '##HOMEREAL %s\\n' "$(if [ -n "$HOME" ] && cd "$HOME" 2>/dev/null; then pwd -P; fi)"`,
`for t in git curl; do if command -v "$t" >/dev/null 2>&1; then printf '##HAVE %s yes\\n' "$t"; else printf '##HAVE %s no\\n' "$t"; fi; done`,
'U="$HOME/.config/systemd/user/nodeterm-server.service"',
"NODE=''; MAIN=''; DD=''",
'if [ -r "$U" ]; then',
" echo '##UNIT user'",
` X=$(sed -n 's/^ExecStart=//p' "$U" | head -n 1)`,
' set -- $X',
' NODE=${1:-}; MAIN=${2:-}',
` DD=$(sed -n 's/^Environment=NODETERM_DATA_DIR=//p' "$U" | head -n 1)`,
`elif [ -e ${posixQuote(systemUnit)} ]; then`,
" echo '##UNIT system'",
'else',
" echo '##UNIT none'",
'fi',
'[ -n "$DD" ] || DD="$HOME/.nodeterm-server"',
`printf '##NODE %s\\n' "$NODE"`,
`printf '##MAIN %s\\n' "$MAIN"`,
`printf '##DATADIR %s\\n' "$DD"`,
`if [ -r "$DD/install-meta.json" ]; then echo '##META'; head -c 4096 "$DD/install-meta.json"; echo; echo '##METAEND'; fi`,
`if [ -n "$NODE" ] && [ -x "$NODE" ] && [ -r "$MAIN" ] && grep -qF ${posixQuote(BOOTSTRAP_MARKER)} "$MAIN" 2>/dev/null; then`,
" echo '##BOOTSTRAP yes'",
' if command -v timeout >/dev/null 2>&1; then',
` S=$(timeout ${STATUS_TIMEOUT_S} "$NODE" "$MAIN" team --data-dir "$DD" status --json </dev/null 2>/dev/null); RC=$?`,
` printf '##STATUSRC %s\\n' "$RC"`,
` echo '##STATUS'; printf '%s\\n' "$S" | head -c ${STATUS_MAX}; echo; echo '##STATUSEND'`,
' fi',
'else',
" echo '##BOOTSTRAP no'",
'fi',
`if cd ${quoteRemotePath(remoteCwd)} 2>/dev/null; then printf '##CWD %s\\n' "$(pwd -P)"; else echo '##CWD'; fi`,
`${remoteTmuxPathPrologue()}echo '##PANES'; tmux -L ${LEGACY_RMT_TMUX_SOCKET} list-panes -a -F '#{session_name}|#{pane_current_command}' 2>/dev/null; tmux -L ${RMT_TMUX_SOCKET} list-panes -a -F '#{session_name}|#{pane_current_command}' 2>/dev/null; echo '##PANESEND'`,
"echo '##END'"
].join('\n')
)
}
const PROBE_CUT = 'The host did not finish the probe.'
const PANE_SESSION_RE = /^nt-[A-Za-z0-9_-]+$/
type ProbeBlock = 'meta' | 'status' | 'panes'
// A Map, not an object literal: a line like `constructor` must not find Object's own members.
const BLOCK_START = new Map<string, ProbeBlock>([
['##META', 'meta'],
['##STATUS', 'status'],
['##PANES', 'panes']
])
const BLOCK_END: Record<ProbeBlock, string> = { meta: '##METAEND', status: '##STATUSEND', panes: '##PANESEND' }
const parseJson = (text: string): unknown => {
try {
return JSON.parse(text)
} catch {
return undefined
}
}
/** Read `shareProbeCommand`'s reply. Login noise before `##NTP 1` is skipped; a reply that never
* reaches `##END` (a dropped channel, a timeout) is an error, never a half-filled probe that
* `sharePlan` would read as "nothing installed". */
export function parseShareProbe(stdout: string): ShareProbe | { error: string } {
const lines = stdout.split('\n')
const start = lines.indexOf('##NTP 1')
if (start < 0) return { error: PROBE_CUT }
const probe: ShareProbe = {
os: '',
uid: null,
user: '',
home: '',
have: { git: false, curl: false },
unit: 'none',
node: '',
main: '',
dataDir: '',
meta: null,
hasBootstrap: false,
statusRc: null,
teamExists: false,
adoptCwd: null,
homeReal: null,
panes: []
}
let unitSeen = false
let done = false
let block: ProbeBlock | null = null
let body: string[] = []
for (const line of lines.slice(start + 1)) {
if (block) {
if (line !== BLOCK_END[block]) {
body.push(line)
continue
}
if (block === 'meta') {
const m = parseJson(body.join('\n'))
probe.meta =
isRecord(m) && typeof m.version === 'string' && typeof m.commit === 'string'
? { version: m.version, commit: m.commit }
: null
} else if (block === 'status') {
const s = parseJson(body.join('\n').trim())
const off = isRecord(s) && isRecord(s.off) ? s.off : null
probe.teamExists = isRecord(s) && (s.enabled === true || (off !== null && off.reason !== undefined && off.reason !== 'no-team'))
} else {
for (const row of body) {
const bar = row.indexOf('|')
if (bar < 0) continue
const session = row.slice(0, bar)
if (PANE_SESSION_RE.test(session)) probe.panes.push({ session, command: row.slice(bar + 1) })
}
}
block = null
body = []
continue
}
if (line === '##END') {
done = true
break
}
const opens = BLOCK_START.get(line)
if (opens) {
block = opens
continue
}
const space = line.indexOf(' ')
const tag = space < 0 ? line : line.slice(0, space)
const value = space < 0 ? '' : line.slice(space + 1)
switch (tag) {
case '##OS':
probe.os = value
break
case '##UID': {
const n = Number.parseInt(value, 10)
probe.uid = Number.isNaN(n) ? null : n
break
}
case '##USER':
probe.user = value
break
case '##HOME':
probe.home = value
break
case '##HOMEREAL':
probe.homeReal = value === '' ? null : value
break
case '##HAVE': {
const m = /^(git|curl) (yes|no)$/.exec(value)
if (m) probe.have[m[1] as 'git' | 'curl'] = m[2] === 'yes'
break
}
case '##UNIT':
if (value !== 'user' && value !== 'system' && value !== 'none') return { error: `The host reported an unknown service kind: ${shown(value)}` }
probe.unit = value
unitSeen = true
break
case '##NODE':
probe.node = value
break
case '##MAIN':
probe.main = value
break
case '##DATADIR':
probe.dataDir = value
break
case '##BOOTSTRAP':
probe.hasBootstrap = value === 'yes'
break
case '##STATUSRC': {
const n = Number.parseInt(value, 10)
probe.statusRc = Number.isNaN(n) ? null : n
break
}
case '##CWD':
probe.adoptCwd = value === '' ? null : value
break
}
}
// `##UNIT` is printed unconditionally, so a reply without it was cut short however it ended.
if (!done || !unitSeen) return { error: PROBE_CUT }
return probe
}
/** Run `main.cjs team --data-dir <dir> <args…>` with every word quoted. Anything the caller pipes
* in reaches the CLI's stdin (the resume list travels there, never on argv). The reply is fenced
* so a login banner cannot be mistaken for it; the exit code rides its own marker line, after a
* newline so a reply without a trailing one cannot swallow it. */
export function teamCliCommand(p: Pick<ShareProbe, 'node' | 'main' | 'dataDir'>, args: readonly string[]): string {
for (const v of [p.node, p.main, p.dataDir]) refuseNested(v, 'The nodeterm-server install path')
for (const a of args) refuseNested(a, 'A team command argument')
const argv = [p.node, p.main, 'team', '--data-dir', p.dataDir, ...args].map(posixQuote).join(' ')
return sh(`echo '##NTB'; ${argv}; rc=$?; printf '\\n##NTRC %s\\n' "$rc"`)
}
/** Strip what must never reach the screen (controls, text-direction overrides) and bound it. */
const shown = (text: string): string => text.replace(CONTROL_G, ' ').slice(0, SHOWN_MAX)
/** Read `teamCliCommand`'s reply. The body is everything between the fences, parsed as ONE JSON
* value: a refusal is a single line, a success is pretty-printed over several. */
export function parseTeamCliOutput(stdout: string): { rc: number; body: unknown } | { error: string } {
const lines = stdout.split('\n')
const start = lines.indexOf('##NTB')
const end = start < 0 ? -1 : lines.findIndex((l, i) => i > start && l.startsWith('##NTRC '))
if (start < 0 || end < 0) return { error: 'The host did not finish running the team command.' }
const rc = Number.parseInt(lines[end].slice('##NTRC '.length), 10)
const text = lines.slice(start + 1, end).join('\n').trim()
try {
return { rc: Number.isNaN(rc) ? 1 : rc, body: JSON.parse(text) }
} catch {
const code = Number.isNaN(rc) ? '?' : String(rc)
return { error: `The team command printed no JSON (exit ${code}): ${shown(text) || '(nothing)'}` }
}
}
/**
* Reads a `has-session` exit code and its output. Exit 1 is "gone" only with one of tmux's own
* absence messages (measured on tmux 3.4: a missing session, no server behind the socket, no
* socket file; a refused connect is the same fact). tmux also exits 1 for a protocol-version
* mismatch and for a permission-denied socket, and in those cases the kill failed too: reading
* them as "gone" would resume a second agent beside a live one. Anything else is "unknown".
*/
const KILL_STATE_FN = [
'nt_state() {',
' case $1 in',
' 0) echo alive ;;',
` 1) case $2 in *"can't find session"*|*"no server running"*|*"error connecting to "*"(No such file or directory)"*|*"error connecting to "*"(Connection refused)"*) echo gone ;; *) echo unknown ;; esac ;;`,
' *) echo unknown ;;',
' esac',
'}'
].join('\n')
/**
* Stop each node's session on this desktop's remote tmux socket and check that it is gone. Every
* target is exact (`=nt-<id>`): without `=` tmux falls back to prefix matching on a miss, and
* `nt-…-1` is a prefix of `nt-…-12`. Only a `gone` node is resumed (see `KILL_STATE_FN`). Node
* ids must be safe ids; anything else is refused before a script is built.
*/
export function killVerifyCommand(nodeIds: readonly string[]): string {
for (const id of nodeIds) {
if (!isSafeNodeId(id)) throw new Error('A terminal node id is not a safe id (letters, digits, ".", "_" and "-" only).')
}
const body = nodeIds.map((id) => {
const t = posixQuote(`=${sessionName(id)}`)
const n = posixQuote(sessionName(id))
return [
// Both sockets: a node's session may be an ADOPTED one on the legacy socket
// (control-master.ts `sessionSocketProbe`), and "gone" must mean gone from wherever a
// reattach would find it — a survivor there is a second agent beside the resumed one.
`tmux -L ${RMT_TMUX_SOCKET} kill-session -t ${t} >/dev/null 2>&1`,
`tmux -L ${LEGACY_RMT_TMUX_SOCKET} kill-session -t ${t} >/dev/null 2>&1`,
`o=$(tmux -L ${RMT_TMUX_SOCKET} has-session -t ${t} 2>&1); r=$?`,
`if [ "$(nt_state "$r" "$o")" = gone ]; then o=$(tmux -L ${LEGACY_RMT_TMUX_SOCKET} has-session -t ${t} 2>&1); r=$?; fi`,
`printf '##K %s %s\\n' ${n} "$(nt_state "$r" "$o")"`
].join('\n')
})
return sh([KILL_STATE_FN, `${remoteTmuxPathPrologue()}echo '##NTK'`, ...body, "echo '##NTKEND'"].join('\n'))
}
export type KillVerifyState = 'gone' | 'alive' | 'unknown'
/** Read `killVerifyCommand`'s reply: one state per requested node, in request order. A node the
* reply does not mention is `unknown`; a reply that never reaches its end marker is an error. */
export function parseKillVerify(
stdout: string,
nodeIds: readonly string[]
): Array<{ nodeId: string; state: KillVerifyState }> | { error: string } {
const lines = stdout.split('\n')
const start = lines.indexOf('##NTK')
const end = start < 0 ? -1 : lines.indexOf('##NTKEND', start + 1)
if (start < 0 || end < 0) return { error: 'The host did not finish stopping the sessions.' }
const states = new Map<string, KillVerifyState>()
for (const l of lines.slice(start + 1, end)) {
const m = /^##K (\S+) (gone|alive|unknown)$/.exec(l)
if (m) states.set(m[1], m[2] as KillVerifyState)
}
return nodeIds.map((nodeId) => ({ nodeId, state: states.get(sessionName(nodeId)) ?? 'unknown' }))
}
/** Map probe panes onto node ids (session names come only from `sessionName`). Last row wins, and
* the probe lists the legacy socket FIRST — so a name on both resolves to the unified socket's
* pane, the same precedence `sessionSocketProbe` applies. */
export function paneCommandsByNode(panes: ShareProbe['panes'], nodeIds: readonly string[]): Record<string, string> {
const bySession = new Map(panes.map((p) => [p.session, p.command]))
const out: Record<string, string> = {}
for (const id of nodeIds) {
const c = bySession.get(sessionName(id))
if (c !== undefined) out[id] = c
}
return out
}