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 tmux naming helpers shared by the PTY manager and the context-link backend.
// No native/electron imports, so this module is safe to import from unit tests.
import { randomBytes } from 'crypto'
import { sanitizePasteText } from './paste-injection'
import { nodeSessionName } from '../shared/session-name'
export const TMUX_SOCKET = 'node-terminal'
/** Per-node tmux session name. Must stay stable — it is the persistence key. */
export function sessionName(persistKey: string): string {
return nodeSessionName(persistKey)
}
/**
* Is this a tmux target THIS app generated (i.e. the output of `sessionName` for some node id)?
*
* The check exists for the one caller that cannot quote: a tmux control-mode command is a single
* text line and `encodeSendKeysHex` interpolates its target into it UNQUOTED, so a target carrying
* a space would split into the wrong arguments and one carrying a newline would run a second
* command. `sessionName` already sanitizes everything outside `[A-Za-z0-9_-]` away, so this can only
* fail on a name that did not come from it — an empty node id, or a raw target somebody passed in.
* Refusing there is cheap; the alternative is a shell-grade escaping problem on a line that reaches
* a tmux server with every session on it.
*/
export function isSessionName(target: string): boolean {
return /^nt-[A-Za-z0-9_-]+$/.test(target)
}
/**
* ── EXACT TARGETS: every node id that becomes a tmux `-t` goes through one of these two ─────────
*
* tmux resolves a BARE target by exact name, then fnmatch, then PREFIX on a miss. Node ids end in a
* counter or a random tail, so `nt-x-1` is a prefix of `nt-x-12`: a bare `-t nt-x-1` whose own
* session is gone (or never existed) reaches the LONGER, unrelated session. Measured on tmux 3.4
* with only `nt-term-abc-12` alive:
* display-message -p -t nt-term-abc-1 '#{session_name}' → nt-term-abc-12, exit 0 (the trap)
* has-session -t nt-term-abc-1 → exit 0 (the trap)
* send-keys / capture-pane / paste-buffer -t =nt-term-abc-1: → "can't find session", exit 1
* display-message -p -t =nt-term-abc-1: '<fmt>' → exit 0, every format EMPTY
* so a miss is a failed command, or an empty read that every parser here answers null for. A relay
* peer that could name a PREFIX of another project's node id reached that terminal through every
* node-keyed pty verb (security audit F1/F2, 2026-10).
*
* For an EXISTING session `=name:` resolves exactly like the bare name did: the session's current
* window, its active pane (re-measured with three windows and a split, the selection moved between
* reads — `pty-exact-target.realtmux.test.ts`).
*
* Both throw for a name this app did not generate: the result is spliced UNQUOTED into tmux command
* text (`if-shell` bodies, control-mode lines). On a REMOTE command line it must still be
* single-quoted (`posixQuote`): zsh's EQUALS option expands a word that STARTS with `=` as a command
* path (`=nt-x:` → "nt-x: not found").
*/
export function exactPaneTarget(session: string): string {
if (!isSessionName(session)) throw new Error(`not a session name of ours: ${JSON.stringify(session)}`)
return `=${session}:`
}
/** The session-target form (`has-session`, `attach-session`, `kill-session`): `=name`, exact. */
export function exactSessionTarget(session: string): string {
if (!isSessionName(session)) throw new Error(`not a session name of ours: ${JSON.stringify(session)}`)
return `=${session}`
}
/**
* ── DELETED: `localTmuxSendKeysArgs` ────────────────────────────────────────────────────────────
*
* It built `send-keys -t <t> -l -- <body>`, and the `--` was load-bearing: `-l` means "literal
* characters" but does NOT stop tmux reading further arguments as options, so a payload beginning
* with `-` was taken as FLAGS. Measured on tmux 3.4, every one of `-R -K -l -- -H -F -N 3`
* exited 0 while typing nothing — the delivery reported success and then sent its Enter, which
* submitted whatever the human had already composed in that pane (and `-R` had wiped it off the
* screen first).
*
* `sendText` no longer puts the payload in an argument at all: it goes down `load-buffer -`'s
* stdin. The entire leading-dash class is structurally gone rather than defended against, which
* is why the builder is gone with it. `local-send-keys.realtmux.test.ts` still runs the `-R`
* payload through the CURRENT delivery, and still runs the pre-fix argv as a control.
*/
/**
* A bare Enter. One caller left: `sendText('', { enter: true })`, i.e. "submit whatever is
* composed". It cannot ride the paste command list, because `load-buffer -` given zero bytes
* creates no buffer, the `paste-buffer` after it fails, and tmux abandons the rest of the list —
* the Enter with it (measured). Every non-empty write puts the text and the Enter in ONE tmux
* invocation, which is also what makes "the Enter can never fire after a failed text send"
* structural rather than a rule the caller has to remember.
*
* Asserts its target like every other builder in this delivery, even though this one quotes
* nothing: the rule is "every splice is checked at the splice", and the two builders that had no
* buffer of their own were the two that quietly opted out of it.
*/
export function localTmuxEnterArgs(socket: string, target: string, opts?: { cursorLeftFirst?: boolean }): string[] {
assertPasteTarget(target)
// `cursorLeftFirst`: a typed message ending in `\` (core/typed-input.ts `endsWithBackslash`).
const keys = opts?.cursorLeftFirst === true ? ['Left', 'Enter'] : ['Enter']
return ['-L', socket, 'send-keys', '-t', exactPaneTarget(target), ...keys]
}
/**
* ── WHY THE DELIVERY BELOW EXISTS, AND WHAT IT REPLACED ─────────────────────────────────────────
*
* A multi-line write must reach a paste-aware TUI INSIDE a bracketed-paste frame. Framed, the app
* reads the whole thing as one pasted block; unframed, every `\n` is a submit, so a three-line
* note push becomes three turns (herdr :260) and the last one races the Enter that follows it.
*
* The previous design asked tmux WHETHER to frame — `display-message -p '#{bracket_paste_flag}'`
* — and framed the body itself. Measured: that format FIRST SHIPPED IN TMUX 3.7 (2026-06-26,
* CHANGES "FROM 3.6b TO 3.7"). On every earlier tmux it is an unknown name that expands to the
* empty string, so the probe answered false for EVERY pane. And a false answer did not refuse —
* it fell through to the legacy two-step, which delivered `line1\nline2\nline3` + `\r` raw into
* the app. Measured on this host (tmux 3.4): exactly those bytes. Ubuntu 24.04 ships 3.4, 22.04
* → 3.2a, Debian 12/13 → 3.3a/3.5a, Ubuntu 26.04 → 3.6a — plus every SSH target, where the
* REMOTE host's tmux decides. So the mangle was the norm, not the exception.
*
* `paste-buffer -p` removes the question. tmux inserts the bracket codes "if the application has
* requested bracketed paste mode" — it consults the pane's REAL DECSET 2004 state itself, the
* state it has tracked since long before it could format it. Introduced 2012-03-03, shipped in
* TMUX 1.7. There is no version floor left to hit.
*
* Measured on tmux 3.4, against a raw-mode reader that records the bytes its stdin actually got:
* - app requested 2004 → `ESC[200~ … ESC[201~` then the Enter's `\r`
* - app did not → the text, unframed, byte-identical to the legacy two-step
* - a NON-ACTIVE pane → still framed correctly
* - `-r` → `\n` survives as `\n` (WITHOUT it tmux rewrites every `\n` to `\r`,
* which is the per-line submit this whole thing exists to avoid)
* - `-d` + a private buffer name → the user's own numbered buffer stack is untouched
*/
/**
* A tmux buffer name owned by ONE delivery.
*
* Unique per call, not a constant: tmux interleaves command lists from DIFFERENT clients, so two
* concurrent `sendText`s sharing one buffer name would have the second `load-buffer` overwrite
* the first's payload before its `paste-buffer` ran — one pane gets the other's text, and the
* loser's write vanishes. The name is `[a-z0-9-]` only, because it is spliced into a tmux command
* string and (on the SSH leg) a remote shell line.
*/
export function pasteBufferName(rand: () => string = () => randomBytes(6).toString('hex')): string {
return `nt-paste-${rand()}`
}
/**
* The ONE tmux invocation that delivers `sendText`'s payload: load the buffer from STDIN, leave
* copy mode if the pane is in it, let tmux paste-and-frame it, then Enter. The text itself is not
* here — it goes over stdin, which is both the ARG_MAX fix and this repo's standing rule.
*
* ARG_MAX, measured on this host: `set-buffer -- "$text"` with a 300 KB payload dies with
* "Argument list too long" (a single argument is capped at MAX_ARG_STRLEN = 128 KB, well under
* the 2 MB `getconf ARG_MAX`). The same 300 KB through `load-buffer -` lands intact and framed.
*
* ── COPY MODE, AND WHY THE CANCEL IS GATED INSIDE TMUX ──────────────────────────────────────────
*
* With `#{pane_in_mode}` = 1 (a wheel scroll is enough — nodeterm's tmux has the mouse on),
* `paste-buffer -p` delivers UNFRAMED: tmux checks the copy-mode screen rather than the app. So
* the per-line-submit bug comes straight back for a user who happened to be scrolled up. Worse,
* measured: the trailing `send-keys Enter` is eaten by the copy-mode key table and never reaches
* the app at all. `send-keys -X cancel` first restores both.
*
* The cancel is NOT unconditional. Measured on 3.4: `send-keys -X cancel` against a pane that is
* NOT in a mode FAILS ("not in a mode", exit 1) and ABORTS THE REST OF THE COMMAND LIST — nothing
* is pasted, no Enter, and the delivery reports failure. An unconditional cancel would therefore
* break every ordinary write, which is the opposite of the bug being fixed.
*
* `if-shell -F` evaluates a FORMAT (no shell, no fork) and runs its command only when the format
* is non-zero, so the gate rides inside the same single invocation: no extra round trip, and no
* probe of ours that a future tmux could change the answer to.
*
* The user-visible cost is real but bounded to the case that already misbehaved: a human reading
* scrollback is scrolled back to the live view. It is not a regression, because TODAY that same
* pane gets NOTHING — measured: `send-keys -l --` + `send-keys Enter` into a copy-mode pane exits
* 0 and delivers zero bytes, so `sendText` returns true having written nothing at all.
*
* The target is spliced UNQUOTED into the `if-shell` command string (tmux's own lexer parses it),
* so it must be a name this app generated; `isSessionName` is asserted rather than assumed.
*/
export function localTmuxPasteArgs(
socket: string,
target: string,
buffer: string,
enter: boolean
): string[] {
assertPasteTarget(target, buffer)
// `target` is the session NAME (asserted above); tmux is handed the EXACT form, never the bare
// name, which prefix-matches a longer session on a miss (see `exactPaneTarget`).
const t = exactPaneTarget(target)
const args = [
'-L',
socket,
// stdin, so no payload on a command line and no ARG_MAX ceiling
'load-buffer',
'-b',
buffer,
'-',
';',
'if-shell',
'-F',
'-t',
t,
'#{pane_in_mode}',
`send-keys -t ${t} -X cancel`,
';',
// -d: drop our private buffer afterwards, so the user's paste stack is untouched
// -p: tmux decides framing from the pane's REAL bracketed-paste state
// -r: keep `\n` as `\n` instead of tmux's default `\n`→`\r` rewrite
'paste-buffer',
'-d',
'-p',
'-r',
'-b',
buffer,
'-t',
t
]
// Same invocation as the paste, so the Enter can never be re-chunked into it — and, because
// tmux aborts a command list at the first failure, a paste that did not happen can never leave
// a lone Enter behind to submit whatever the human had composed.
if (enter) args.push(';', 'send-keys', '-t', t, 'Enter')
return args
}
/**
* Shared by the local argv builder and the remote command builder so the two cannot drift on the
* rule that makes the unquoted splices safe. Throws rather than sanitizing: a caller holding a
* target this app did not generate is a bug, and `sendText` already turns a throw into `false`.
*/
export function assertPasteTarget(target: string, buffer?: string): void {
if (!isSessionName(target)) throw new Error(`unsafe tmux paste target: ${JSON.stringify(target)}`)
if (buffer !== undefined) assertPasteBuffer(buffer)
}
/** The buffer half on its own, for the one builder that has a buffer and no pane target. */
export function assertPasteBuffer(buffer: string): void {
if (!/^nt-paste-[a-z0-9-]+$/.test(buffer))
throw new Error(`unsafe tmux buffer name: ${JSON.stringify(buffer)}`)
}
/** `delete-buffer` for a delivery whose paste never ran. See `runPasteDelivery`. */
export function localTmuxDeleteBufferArgs(socket: string, buffer: string): string[] {
assertPasteBuffer(buffer)
return ['-L', socket, 'delete-buffer', '-b', buffer]
}
/**
* ── EVERYTHING `sendText` DECIDES, IN ONE TESTED PLACE ──────────────────────────────────────────
*
* A plan is what to run, what to put on its stdin, and how to clean up if it fails. `sendText` is
* a two-line dispatcher over this; a test drives THIS, not a copy of it.
*
* That split is not decoration. The first version of this change left the composition — sanitize,
* empty-body, buffer name — inlined in `sendText`, and the real-tmux test rebuilt the same three
* steps in its own helper before calling the argv builder. Both halves were green, and TWO
* mutations survived a full suite run: deleting the empty-body branch, and deleting
* `sanitizePasteText` at the caller. A test that re-implements the thing it tests cannot see the
* thing it tests being deleted. It is a weakening against the version this replaces, where the
* sanitize was structural inside `bracketedInjection`; now it is structural here instead.
*/
export interface PasteDelivery {
/** argv for the delivery process (tmux locally, ssh remotely). */
args: string[]
/** what goes on its stdin — the payload, or '' when there is none. */
body: string
/**
* argv that removes the private buffer this delivery created, or null when it created none.
*
* MEASURED LEAK, and the reason this field exists: `load-buffer` succeeds, then `paste-buffer`
* fails (a node closed while the write was in flight — "can't find pane"), tmux abandons the
* rest of the command list, and the `-d` that would have dropped the buffer never runs. The
* payload then sits in the tmux server's buffer stack, which is USER-VISIBLE (`prefix-=`,
* `list-buffers`, a phone attaching), for as long as the server lives — days, on a host with
* dozens of sessions. `buffer-limit` does not save it: named buffers are not reaped (measured —
* 60 named buffers under `buffer-limit 50`, all 60 survived). The payload can be a note push or
* a 300 KB scrollback paste. Same story on an SSH host's server.
*/
cleanup: string[] | null
}
/**
* The plan for a LOCAL delivery, or null when there is nothing to run at all.
*
* Three decisions live here and nowhere else:
* - `sanitizePasteText`, so no payload byte can express paste structure. tmux writing the markers
* does not change that: a payload-supplied `ESC[201~` would still close the frame early and
* turn its tail into KEY INPUT.
* - the EMPTY body. `load-buffer -` given zero bytes creates no buffer, so the `paste-buffer`
* after it fails and tmux abandons the list — the Enter with it. `sendText('', { enter: true })`
* is a live call (`Canvas.tsx`'s write verb, `args.text ?? ''`) and means "submit whatever is
* composed", which is what the legacy two-step did, so it becomes a bare Enter.
* - a per-call buffer name, so two concurrent deliveries cannot overwrite each other's payload.
*/
export function localPasteDelivery(
socket: string,
target: string,
text: string,
enter: boolean
): PasteDelivery | null {
const body = sanitizePasteText(text)
if (body.length === 0) {
if (!enter) return null
return { args: localTmuxEnterArgs(socket, target), body: '', cleanup: null }
}
const buffer = pasteBufferName()
return {
args: localTmuxPasteArgs(socket, target, buffer, enter),
body,
cleanup: localTmuxDeleteBufferArgs(socket, buffer)
}
}
/**
* ── DELETED: `assertFramedPayload` / `localTmuxFramedPasteArgs` / `localFramedDelivery` ─────────
*
* The framed-plan trio delivered the agent-messaging envelope as a payload that CARRIED its own
* `ESC[200~ … ESC[201~ \r` frame, pasted with `paste-buffer -r` and no `-p` ("tmux must not
* re-frame bytes that already carry their frame") and no separate Enter ("text and submit are one
* write"). Both premises died with tmux 3.7 (issue #453, measured on 3.7b — the version the macOS
* app bundles): `paste-buffer` now passes the buffer content through vis(3)
* (`utf8_stravisx(VIS_SAFE|VIS_NOSLASH)`, CHANGES: "Pass paste buffer through vis(3) when
* pasting…"), which rewrites every ESC byte into the printable pair `^[` — so the hand-rolled
* frame arrived as LITERAL TEXT (`^[[200~…^[[201~`) in the target's composer, and the `\r` riding
* inside the now-frameless burst was absorbed as pasted content instead of a submit. On tmux ≤ 3.6
* the same bytes passed through verbatim and worked, which is why every Linux CI run stayed green
* while the bundled-tmux macOS build was broken.
*
* The envelope now rides the SAME plan as every other write (`localPasteDelivery` above, enter
* always true — see `PtyManager.sendEnvelope`): tmux inserts the frame from the pane's real
* bracketed-paste state (`-p`; vis(3) is applied to buffer CONTENT only, never to tmux's own
* markers — measured on 3.7b: the markers arrive as real ESC bytes, the content untouched), and
* the Enter is its own key event AFTER the close marker, which a paste-aware composer cannot
* re-chunk into the paste (the herdr :48 race only existed for UNMARKED bursts). Do not resurrect
* a plan that puts an ESC byte into a paste buffer: on tmux ≥ 3.7 it cannot arrive as an escape.
*/
/**
* Run a plan. The runner is injected so this is the same code in production and under a real tmux.
*
* The sweep is fire-and-forget: the delivery has already failed, the caller is already on its
* error path, and awaiting a second call would double the worst-case stall (a dead ControlMaster
* takes the full `PROC_TIMEOUT_MS` to fail, twice). Its own failure is ignored — `delete-buffer`
* against a buffer `-d` already dropped is an expected error, not a problem.
*/
export async function runPasteDelivery(
plan: PasteDelivery,
run: (args: string[], input: string) => Promise<unknown>
): Promise<boolean> {
try {
await run(plan.args, plan.body)
return true
} catch {
if (plan.cleanup) {
void Promise.resolve(run(plan.cleanup as string[], '')).catch(() => {
// best effort: the buffer outliving one failed write is bad, throwing here is worse
})
}
return false
}
}