Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
import fs from 'fs'
import path from 'path'
import { initPlatform, resetPlatformForTests } from './platform'
import { fakePlatform, type FakePlatform } from './platform-fake'
import { testTmpDir } from './test-tmp'
import { IPC } from '../shared/ipc'
import { DEFAULT_SETTINGS } from '../shared/types'
import { MODEL_GATEWAY_SECRET_REF } from '../shared/agents/model-gateway'
import { TMUX_SOCKET, sessionName } from './tmux-naming'
/**
* SINGLE-USER REGRESSION.
*
* The co-attach machinery (subscriber set, smallest-subscriber-wins size negotiation, per-client
* flow-control ledger, in-flight create guard) exists for a SECOND person. For the person working
* ALONE — which is everybody, most of the time — it must be INVISIBLE: one spawn with the same
* tmux args / env / cwd, the same `fresh` flag (it drives scrollback replay + agent resume), the
* same coalesced output, the same resize ioctl, the same pause/resume, and a `kill` that detaches
* the tmux client WITHOUT killing the tmux session (that is the whole continuity story).
*
* min(one element) == your own size. Everything below pins that.
*/
/** One fake pty per spawn, recording exactly what the manager did to it. */
interface FakePty {
onDataCb?: (d: string) => void
onExitCb?: (e: { exitCode: number }) => void
/** Everything written into the tmux client pty (the headless write tests read it). */
writes: string[]
resizes: Array<{ cols: number; rows: number }>
paused: boolean
killed: boolean
}
const spawned: FakePty[] = []
const spawnArgs: Array<{
file: string
args: string[]
cols: number
rows: number
cwd: string
env: Record<string, string>
}> = []
// Pin the persistence backend: `sessionHostSupported()` only asks whether
// out/session-host/host.cjs exists on disk, so whether this suite exercises the mocked
// `node-pty` spawn below or a real session-host shim depended on whether anyone had run
// `npm run build` (or `npm run host:build`). See src/core/__fixtures__/no-session-host.ts.
vi.mock('./session-host-backend', async () =>
(await import('./__fixtures__/no-session-host')).noSessionHost()
)
vi.mock('node-pty', () => ({
spawn: (
file: string,
args: string[],
opts: { cols: number; rows: number; cwd: string; env: Record<string, string> }
) => {
const p: FakePty = { writes: [], resizes: [], paused: false, killed: false }
spawned.push(p)
spawnArgs.push({ file, args, cols: opts.cols, rows: opts.rows, cwd: opts.cwd, env: opts.env })
return {
onData: (cb: (d: string) => void) => {
p.onDataCb = cb
},
onExit: (cb: (e: { exitCode: number }) => void) => {
p.onExitCb = cb
},
write: (d: string) => {
p.writes.push(d)
},
resize: (cols: number, rows: number) => p.resizes.push({ cols, rows }),
pause: () => {
p.paused = true
},
resume: () => {
p.paused = false
},
kill: () => {
p.killed = true
},
pid: 1
}
}
}))
/**
* Every tmux side-call the manager makes (has-session / capture-pane / kill-session) goes through
* child_process, so mocking it lets us (a) decide whether a tmux session already exists — which is
* exactly what the `fresh` flag is computed from — and (b) SEE which tmux commands ran, so we can
* prove `kill` never issues `kill-session` while `destroy` does.
*/
const execCalls: Array<{ file: string; args: string[] }> = []
const liveTmuxSessions = new Set<string>()
let paneProcessReply = ''
let processGroupReply = ''
vi.mock('child_process', () => {
type Cb = (err: Error | null, res?: { stdout: string; stderr: string }) => void
const execFile = (file: string, args: string[], a?: unknown, b?: unknown): unknown => {
const cb = (typeof a === 'function' ? a : b) as Cb | undefined
execCalls.push({ file, args })
const ok = (stdout: string): void => cb?.(null, { stdout, stderr: '' })
if (args.includes('has-session')) {
// Production asks with the EXACT form (`=nt-…` / `=nt-…:`); tmux matches it against the name.
const raw = args[args.indexOf('-t') + 1]
const target = raw.startsWith('=') ? raw.slice(1).replace(/:$/, '') : raw
if (liveTmuxSessions.has(target)) ok('')
// Real execFile carries tmux's exit status on err.code — 1 is what probeSaysAbsent
// reads as genuine absence (vs a spawn failure, which has a string/no code).
else cb?.(Object.assign(new Error('no such session'), { code: 1 }))
} else if (args[0] === '-ilc') {
// The login-shell PATH probe (`resolveShellPath`).
ok('__NT_PATH_START__/usr/bin:/bin__NT_PATH_END__')
} else if (args.includes('capture-pane')) {
ok('PANE SNAPSHOT')
} else if (args.includes('#{pane_pid}|#{pane_current_command}')) {
ok(paneProcessReply)
} else if (file === 'ps' && args.includes('tpgid=')) {
ok(processGroupReply)
} else {
ok('')
}
return {}
}
return { execFile, execFileSync: (): string => '' }
})
const SOLO = 42
/** The real timer, captured before any test installs fake timers (see `drainRealIo`). */
const realSetTimeout = globalThis.setTimeout
/**
* Hermetic tmux resolution (issue #160). Without this, `init()` → `ensureTmux()` → `findTmux()`
* probes the REAL machine: `fs.existsSync` on the fixed install paths, then the login-shell PATH,
* then the bundled binary. Two ways that made this file's answer depend on the host:
* - a machine with no tmux installed never actually tested the tmux-backed manager (every
* `tmuxManager()` silently exercised the plain-shell fallback instead);
* - under ~16 parallel workers a transient EMFILE makes `existsSync` swallow the error and
* answer FALSE for a tmux that IS installed — every candidate misses, the manager silently
* falls back to a plain shell, and all of this file's "expected 1 tmux call, got 0"
* assertions fail at once. That is issue #160's run A (44 failures), unreproducible alone.
* Pinning the first fixed candidate makes tmux resolution a function of the code under test, not
* of the host's fd budget. No real tmux is ever invoked: node-pty and child_process are mocked
* above, and ensureTmux's `source-file` push goes through the mocked execFileSync.
*/
vi.mock('./tmux-hint', async (importOriginal) => ({
...(await importOriginal<typeof import('./tmux-hint')>()),
findFixedTmux: () => '/usr/bin/tmux'
}))
/**
* A machine with pty devices to spare, always.
*
* Without this the real probe runs a `readdir('/dev')` against the DEVELOPER's host, and
* `spawnSession`'s pre-flight refuses every create once that host is within `PTY_DEVICE_HEADROOM`
* of its own `kern.tty.ptmx_max` — which a machine running this app all day genuinely reaches (511
* on macOS; this one sits in the 480s). Nothing below is about device pressure, so it is pinned
* healthy rather than left to depend on who is running the suite and how many terminals they have
* open. The pressure behaviour itself is tested in pty-spawn-preflight.test.ts.
*/
vi.mock('./pty-devices', async (importOriginal) => ({
...(await importOriginal<typeof import('./pty-devices')>()),
readPtyDevices: () => ({ ceiling: 511, inUse: 8 })
}))
describe('SINGLE-USER REGRESSION: co-attach must not change the solo path', () => {
let fake: FakePlatform
let userDataDir: string
beforeEach(() => {
spawned.length = 0
spawnArgs.length = 0
execCalls.length = 0
liveTmuxSessions.clear()
paneProcessReply = ''
processGroupReply = ''
userDataDir = testTmpDir('nt-solo-')
fake = fakePlatform({ userDataDir })
initPlatform(fake)
vi.useFakeTimers()
})
afterEach(() => {
vi.useRealTimers()
vi.restoreAllMocks()
resetPlatformForTests()
// BEST EFFORT, and it must stay that way. This races a write it cannot wait for: the scrollback
// snapshot is fired and forgotten by design (`snapshotScrollback` is best-effort and nothing
// awaits it), so a test that triggered one can reach here while the file is still landing and
// the rmdir fails with ENOTEMPTY. Measured at roughly one full-suite run in six.
//
// `maxRetries` alone was not enough — it only narrows the window, and the write can land after
// the last retry. The catch is what actually fixes it, and it is safe precisely because this
// line is HOUSEKEEPING: the directory is per-test (`mkdtemp`) and lives in the OS temp dir, so
// failing to remove it cannot indicate a defect in anything under test. A cleanup that can fail
// the suite is worse than a leftover directory. It does not stay left over: the dir comes from
// `testTmpDir`, which removes it again when the file ends, after the late write has landed.
try {
fs.rmSync(userDataDir, { recursive: true, force: true, maxRetries: 10, retryDelay: 20 })
} catch {
/* a temp dir we could not remove is not a test result */
}
})
/** A manager WITHOUT init(): no tmux (plain-shell fallback), as the co-attach suite runs it. */
async function manager() {
const { PtyManager } = await import('./pty-manager')
const m = new PtyManager()
m.registerIpc()
return m
}
/** A manager WITH init(): tmux-backed, which is what a real user always gets. */
async function tmuxManager() {
const { PtyManager } = await import('./pty-manager')
const m = new PtyManager()
m.init(() => DEFAULT_SETTINGS)
m.registerIpc()
return m
}
const create = (cols: number, rows: number, persistKey = 'solo-1', extra = {}) =>
fake.handlers[IPC.ptyCreate](SOLO, { cols, rows, persistKey, ...extra }) as Promise<{
sessionId: string
fresh: boolean
/** Set when the node was deleted (tombstoned) and this create is refused. */
closed?: { by: number | null }
}>
const resize = (sessionId: string, cols: number | null, rows: number | null) =>
fake.senderListeners[IPC.ptyResize](SOLO, sessionId, cols, rows)
const flow = (sessionId: string, resume: boolean) =>
fake.senderListeners[IPC.ptyFlow](SOLO, sessionId, resume)
const kill = (sessionId: string) => fake.senderListeners[IPC.ptyKill](SOLO, sessionId)
const tmuxCalls = (verb: string) => execCalls.filter((c) => c.args.includes(verb))
// ── One create → exactly one spawn, at the caller's own size ──────────────────────────────
it('one create → one spawn, fresh:true, spawned at the caller s own size', async () => {
await manager()
const r = await create(100, 30)
expect(spawned).toHaveLength(1)
expect(spawnArgs[0].cols).toBe(100)
expect(spawnArgs[0].rows).toBe(30)
expect(r.fresh).toBe(true)
})
// ── The spawn itself: same tmux args, same cwd, same env ──────────────────────────────────
it('spawns ONE tmux client with the unchanged attach flags, cwd and session name', async () => {
const m = await tmuxManager()
const cwd = testTmpDir('nt-cwd-')
await create(80, 24, 'solo-1', { cwd })
expect(spawned).toHaveLength(1)
const { file, args, env } = spawnArgs[0]
expect(file).toBe(m.getTmuxBin())
// The dedicated socket + generated conf, then attach-or-create with -D: the app has exactly
// ONE tmux client per session, so tmux's own multi-client size negotiation never engages.
expect(args.slice(0, 7)).toEqual([
'-L',
TMUX_SOCKET,
'-f',
path.join(userDataDir, 'tmux.conf'),
'new-session',
'-A',
'-D'
])
expect(args.filter((a) => a === 'new-session')).toHaveLength(1)
expect(args[args.indexOf('-c') + 1]).toBe(cwd)
expect(args.slice(-2)).toEqual(['-s', sessionName('solo-1')])
// The spawned process env is the pre-co-attach env: forced TERM, no inherited TMUX nesting,
// and the real login-shell PATH. The CLIENT runs from a stable dir, never the node's: the
// pane's directory is the `-c` above (issue #1131 — a client in the project dir can start the
// shared server there, and tmux 3.7 then drops every later pane's `-c` once that dir is gone).
const { localTmuxClientCwd } = await import('./pty-manager')
expect(spawnArgs[0].cwd).toBe(localTmuxClientCwd())
expect(spawnArgs[0].cwd).not.toBe(cwd)
expect(env.TERM).toBe('xterm-256color')
expect(env.TMUX).toBeUndefined()
expect(env.TMUX_PANE).toBeUndefined()
expect(env.PATH).toBe('/usr/bin:/bin')
})
it('injects the shared gateway into both the PTY and its tmux session environment', async () => {
const inherited = process.env.NODETERM_TEST_GATEWAY_KEY
process.env.NODETERM_TEST_GATEWAY_KEY = 'vk-secret'
try {
const { PtyManager } = await import('./pty-manager')
const m = new PtyManager()
m.init(() => ({
...DEFAULT_SETTINGS,
modelGateway: {
baseUrl: 'https://bifrost.example.test',
apiKey: '${env:NODETERM_TEST_GATEWAY_KEY}'
}
}))
m.registerIpc()
await create(80, 24, 'gateway-node', { agentId: 'claude' })
expect(spawnArgs[0].env.ANTHROPIC_BASE_URL).toBe(
'https://bifrost.example.test/anthropic'
)
expect(spawnArgs[0].env.ANTHROPIC_AUTH_TOKEN).toBe('vk-secret')
// NEVER on argv: the tmux client's command line is world-readable in /proc/<pid>/cmdline
// for the whole session on a multi-user host (the PR #195 leak class). The session gets the
// values through the conf's update-environment list reading this client's process env.
expect(spawnArgs[0].args.join(' ')).not.toContain('vk-secret')
expect(spawnArgs[0].args.join(' ')).not.toContain('ANTHROPIC_AUTH_TOKEN')
expect(spawnArgs[0].args.join(' ')).not.toContain('${env:')
} finally {
if (inherited === undefined) delete process.env.NODETERM_TEST_GATEWAY_KEY
else process.env.NODETERM_TEST_GATEWAY_KEY = inherited
}
})
it('maps Copilot provider metadata into the spawn environment without exposing credentials on argv', async () => {
const { PtyManager } = await import('./pty-manager')
const m = new PtyManager()
m.init(() => ({
...DEFAULT_SETTINGS,
modelGateway: { baseUrl: 'https://bifrost.example.test', apiKey: 'vk-secret' }
}))
m.registerIpc()
await create(80, 24, 'copilot-gateway-node', {
agentId: 'copilot',
agentModel: 'openai/gpt-5.5'
})
expect(spawnArgs[0].env).toMatchObject({
COPILOT_PROVIDER_BASE_URL: 'https://bifrost.example.test/openai/v1',
COPILOT_PROVIDER_TYPE: 'openai',
COPILOT_PROVIDER_API_KEY: 'vk-secret',
COPILOT_PROVIDER_MODEL_ID: 'gpt-5.5',
COPILOT_PROVIDER_WIRE_MODEL: 'openai/gpt-5.5',
COPILOT_PROVIDER_WIRE_API: 'responses'
})
// The BYOK env — key included — reaches the session via the client env + update-environment,
// never the argv (see the claude case above for why).
expect(spawnArgs[0].args.join(' ')).not.toContain('vk-secret')
expect(spawnArgs[0].args.join(' ')).not.toContain('COPILOT_PROVIDER')
// This is the tmux client's argv. Copilot's --model selection is delivered later by the
// shared launch/resume command assembler, using this provider's internal model id.
})
it('reads a stored gateway key through the shell-owned secret cache', async () => {
const { PtyManager } = await import('./pty-manager')
const m = new PtyManager()
m.init(
() => ({
...DEFAULT_SETTINGS,
modelGateway: {
baseUrl: 'https://bifrost.example.test',
apiKey: MODEL_GATEWAY_SECRET_REF
}
}),
() => 'stored-gateway-key'
)
m.registerIpc()
await create(80, 24, 'stored-gateway-node', { agentId: 'codex' })
expect(spawnArgs[0].env).toMatchObject({
OPENAI_BASE_URL: 'https://bifrost.example.test/openai/v1',
OPENAI_API_KEY: 'stored-gateway-key'
})
// The stored key must not surface on the tmux client's argv either — same #195 class.
expect(spawnArgs[0].args.join(' ')).not.toContain('stored-gateway-key')
})
it('never exposes gateway credentials to a plain terminal', async () => {
const inherited = process.env.ANTHROPIC_AUTH_TOKEN
process.env.ANTHROPIC_AUTH_TOKEN = 'preexisting-shell-token'
// A pty inherits this process's environment, so the two assertions below are about what
// `buildPtyEnv` ADDS — and they can only say that if the ambient value is absent. nodeterm is
// developed inside nodeterm: a suite run from an agent pane inherits that pane's own
// NODETERM_AGENT_ID=claude / NODETERM_CANVAS_CONTROL=1, and the test then failed for the
// developer while passing in CI, which is the worst way round.
const inheritedAgent = process.env.NODETERM_AGENT_ID
const inheritedControl = process.env.NODETERM_CANVAS_CONTROL
delete process.env.NODETERM_AGENT_ID
delete process.env.NODETERM_CANVAS_CONTROL
try {
const { PtyManager } = await import('./pty-manager')
const m = new PtyManager()
m.init(() => ({
...DEFAULT_SETTINGS,
modelGateway: { baseUrl: 'https://bifrost.example.test', apiKey: 'vk-secret' }
}))
m.registerIpc()
await create(80, 24, 'plain-terminal')
// Plain shells still inherit the user's ordinary process environment; the gateway neither
// overwrites it nor emits an explicit tmux session value.
expect(spawnArgs[0].env.ANTHROPIC_AUTH_TOKEN).toBe('preexisting-shell-token')
expect(spawnArgs[0].env.NODETERM_AGENT_ID).toBeUndefined()
expect(spawnArgs[0].env.NODETERM_CANVAS_CONTROL).toBeUndefined()
expect(spawnArgs[0].args.join(' ')).not.toContain('vk-secret')
expect(spawnArgs[0].args.join(' ')).not.toContain('bifrost.example.test')
} finally {
if (inherited === undefined) delete process.env.ANTHROPIC_AUTH_TOKEN
else process.env.ANTHROPIC_AUTH_TOKEN = inherited
if (inheritedAgent === undefined) delete process.env.NODETERM_AGENT_ID
else process.env.NODETERM_AGENT_ID = inheritedAgent
if (inheritedControl === undefined) delete process.env.NODETERM_CANVAS_CONTROL
else process.env.NODETERM_CANVAS_CONTROL = inheritedControl
}
})
it.each([
{ vanillaLaunchDefault: true, clearEnv: undefined },
{ vanillaLaunchDefault: false, clearEnv: true }
])('preserves a plain terminal environment in subscription mode: %j', async (mode) => {
const inherited = {
ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY,
ANTHROPIC_BASE_URL: process.env.ANTHROPIC_BASE_URL
}
process.env.ANTHROPIC_API_KEY = 'plain-terminal-key'
process.env.ANTHROPIC_BASE_URL = 'https://plain-terminal-provider.example.test'
try {
const { PtyManager } = await import('./pty-manager')
const m = new PtyManager()
m.init(() => ({
...DEFAULT_SETTINGS,
agentLaunchMode: mode.vanillaLaunchDefault ? 'subscription' : 'gateway',
vanillaLaunchDefault: mode.vanillaLaunchDefault,
modelGateway: { baseUrl: 'https://bifrost.example.test', apiKey: 'vk-gateway' }
}))
m.registerIpc()
await create(80, 24, 'subscription-plain-terminal', { clearEnv: mode.clearEnv })
expect(spawnArgs[0].env.ANTHROPIC_API_KEY).toBe('plain-terminal-key')
expect(spawnArgs[0].env.ANTHROPIC_BASE_URL).toBe(
'https://plain-terminal-provider.example.test'
)
expect(spawnArgs[0].args.join(' ')).not.toContain('vk-gateway')
} finally {
for (const [key, value] of Object.entries(inherited)) {
if (value === undefined) delete process.env[key]
else process.env[key] = value
}
}
})
// "Restart on subscription": clearEnv spawns the session VANILLA — skip the gateway AND strip
// inherited provider vars (a LaunchAgent/zshrc export a GUI launch still inherits) so the agent
// falls back to its OWN default provider. Both moves are gated on the agent's vanillaEnvPattern
// (resolved through its base harness). The strip runs BEFORE custom-agent env, so a user who
// explicitly declares a provider var on a custom agent still wins.
it('clearEnv skips the gateway and strips inherited provider env for claude', async () => {
const inheritedBase = process.env.ANTHROPIC_BASE_URL
const inheritedKey = process.env.ANTHROPIC_API_KEY
const inheritedDir = process.env.CLAUDE_CONFIG_DIR
process.env.ANTHROPIC_BASE_URL = 'https://launchagent-gateway.example.test'
process.env.ANTHROPIC_API_KEY = 'sk-inherited'
process.env.CLAUDE_CONFIG_DIR = '/home/me/.nodeterm/claude-accounts/abc'
try {
const { PtyManager } = await import('./pty-manager')
const m = new PtyManager()
m.init(() => ({
...DEFAULT_SETTINGS,
modelGateway: {
baseUrl: 'https://bifrost.example.test',
apiKey: 'vk-gateway'
}
}))
m.registerIpc()
await create(80, 24, 'vanilla-claude', { agentId: 'claude', clearEnv: true })
const env = spawnArgs[0].env
// (1) the gateway is NOT injected …
expect(env.ANTHROPIC_BASE_URL).toBeUndefined()
expect(env.ANTHROPIC_AUTH_TOKEN).toBeUndefined()
// … and (2) the INHERITED provider vars are stripped too, so the session does not fall back
// to the LaunchAgent-set base URL instead of the subscription.
expect(env.ANTHROPIC_BASE_URL).toBeUndefined()
expect(env.ANTHROPIC_API_KEY).toBeUndefined()
// CLAUDE_CONFIG_DIR is the managed-account dir, NOT a provider credential — stripping it
// would break account isolation, so it survives a vanilla relaunch.
expect(env.CLAUDE_CONFIG_DIR).toBe('/home/me/.nodeterm/claude-accounts/abc')
} finally {
for (const [k, v] of [
['ANTHROPIC_BASE_URL', inheritedBase],
['ANTHROPIC_API_KEY', inheritedKey],
['CLAUDE_CONFIG_DIR', inheritedDir]
] as const) {
if (v === undefined) delete process.env[k]
else process.env[k] = v
}
}
})
it('clearEnv is one-directional: unset, the gateway is injected as usual', async () => {
const { PtyManager } = await import('./pty-manager')
const m = new PtyManager()
m.init(() => ({
...DEFAULT_SETTINGS,
modelGateway: { baseUrl: 'https://bifrost.example.test', apiKey: 'vk-gateway' }
}))
m.registerIpc()
await create(80, 24, 'gateway-claude', { agentId: 'claude' })
expect(spawnArgs[0].env.ANTHROPIC_BASE_URL).toBe('https://bifrost.example.test/anthropic')
expect(spawnArgs[0].env.ANTHROPIC_AUTH_TOKEN).toBe('vk-gateway')
})
it('clearEnv strips COPILOT_PROVIDER_* for copilot but keeps the home dir', async () => {
const inheritedHome = process.env.COPILOT_HOME
const inheritedProviderKey = process.env.COPILOT_PROVIDER_API_KEY
process.env.COPILOT_HOME = '/home/me/.copilot'
process.env.COPILOT_PROVIDER_API_KEY = 'sk-inherited'
try {
const { PtyManager } = await import('./pty-manager')
const m = new PtyManager()
m.init(() => ({
...DEFAULT_SETTINGS,
modelGateway: { baseUrl: 'https://bifrost.example.test', apiKey: 'vk-gateway' }
}))
m.registerIpc()
await create(80, 24, 'vanilla-copilot', { agentId: 'copilot', clearEnv: true })
const env = spawnArgs[0].env
// Gateway + inherited provider vars both gone.
expect(env.COPILOT_PROVIDER_API_KEY).toBeUndefined()
expect(env.COPILOT_PROVIDER_BASE_URL).toBeUndefined()
// Home dir is a config dir, not a credential — survives.
expect(env.COPILOT_HOME).toBe('/home/me/.copilot')
} finally {
for (const [k, v] of [
['COPILOT_HOME', inheritedHome],
['COPILOT_PROVIDER_API_KEY', inheritedProviderKey]
] as const) {
if (v === undefined) delete process.env[k]
else process.env[k] = v
}
}
})
// The global "Launch on subscription" default is the counterpart to the per-node `clearEnv`
// recycle: read LIVE at spawn, so a fresh launch strips the gateway + inherited provider env
// WITHOUT a per-node flag (and survives a reboot, since the setting is the source of truth, not
// a one-shot data field that is cleared after its single use).
it('subscription launch mode strips the gateway + inherited env on a fresh spawn', async () => {
const inheritedBase = process.env.ANTHROPIC_BASE_URL
const inheritedDir = process.env.CLAUDE_CONFIG_DIR
process.env.ANTHROPIC_BASE_URL = 'https://launchagent-gateway.example.test'
process.env.CLAUDE_CONFIG_DIR = '/home/me/.nodeterm/claude-accounts/abc'
try {
const { PtyManager } = await import('./pty-manager')
const m = new PtyManager()
m.init(() => ({
...DEFAULT_SETTINGS,
// The three-way successor to the boolean. (`vanillaLaunchDefault` is now a mirror kept in
// lockstep by the settings read path; tests that build settings inline must set the mode.)
agentLaunchMode: 'subscription',
vanillaLaunchDefault: true,
modelGateway: { baseUrl: 'https://bifrost.example.test', apiKey: 'vk-gateway' }
}))
m.registerIpc()
// No `clearEnv` on the node — the SETTING is what strips. This is the new-session case the
// per-node action could not serve (it recycles, which needs a session with turns to resume).
await create(80, 24, 'vanilla-default-claude', { agentId: 'claude' })
const env = spawnArgs[0].env
expect(env.ANTHROPIC_BASE_URL).toBeUndefined()
expect(env.ANTHROPIC_AUTH_TOKEN).toBeUndefined()
// Inherited provider var stripped too — no fall-back to the LaunchAgent gateway.
expect(env.ANTHROPIC_BASE_URL).toBeUndefined()
// Account isolation survives (config dir is not a provider credential).
expect(env.CLAUDE_CONFIG_DIR).toBe('/home/me/.nodeterm/claude-accounts/abc')
} finally {
for (const [k, v] of [
['ANTHROPIC_BASE_URL', inheritedBase],
['CLAUDE_CONFIG_DIR', inheritedDir]
] as const) {
if (v === undefined) delete process.env[k]
else process.env[k] = v
}
}
})
it('subscription is a no-op without a strip pattern, while both gateway modes keep the gateway', async () => {
const { PtyManager } = await import('./pty-manager')
const m = new PtyManager()
m.init(() => ({
...DEFAULT_SETTINGS,
agentLaunchMode: 'subscription',
vanillaLaunchDefault: true,
modelGateway: { baseUrl: 'https://bifrost.example.test', apiKey: 'vk-gateway' }
}))
m.registerIpc()
// gemini has no vanillaEnvPattern (and no gateway route at all) → the setting strips nothing
// and the spawn proceeds normally. A global toggle must not change an agent it does not cover:
// a non-provider env var (PATH) survives the strip pass untouched. (A provider var inherited
// from the host env is NOT stripped either — gemini has no pattern — which is the no-op.)
await create(80, 24, 'vanilla-default-gemini', { agentId: 'gemini' })
expect(typeof spawnArgs[0].env.PATH).toBe('string')
// And with the setting OFF (the default), a claude spawn keeps the gateway — the non-disruptive
// upgrade guarantee for existing users. (spawnArgs accumulates within a test: this is [1].)
const m2 = new PtyManager()
m2.init(() => ({
...DEFAULT_SETTINGS,
agentLaunchMode: 'gateway',
vanillaLaunchDefault: false,
modelGateway: { baseUrl: 'https://bifrost.example.test', apiKey: 'vk-gateway' }
}))
m2.registerIpc()
await create(80, 24, 'gateway-claude-default-off', { agentId: 'claude' })
expect(spawnArgs[1].env.ANTHROPIC_BASE_URL).toBe('https://bifrost.example.test/anthropic')
expect(spawnArgs[1].env.ANTHROPIC_AUTH_TOKEN).toBe('vk-gateway')
// Gateway (default model) changes the renderer's launch command, not PTY credential injection.
const m3 = new PtyManager()
m3.init(() => ({
...DEFAULT_SETTINGS,
agentLaunchMode: 'gateway-model',
modelGateway: { baseUrl: 'https://bifrost.example.test', apiKey: 'vk-gateway' }
}))
m3.registerIpc()
await create(80, 24, 'gateway-claude-default-model', { agentId: 'claude' })
expect(spawnArgs[2].env.ANTHROPIC_BASE_URL).toBe('https://bifrost.example.test/anthropic')
expect(spawnArgs[2].env.ANTHROPIC_AUTH_TOKEN).toBe('vk-gateway')
})
// ── `fresh` drives scrollback replay + agent resume: it must still be computed from tmux ──
it('fresh:false on a WARM reattach (tmux session already exists) — no cold restore', async () => {
await tmuxManager()
liveTmuxSessions.add(sessionName('solo-1')) // the app restarted; tmux kept the session
const r = await create(80, 24)
expect(r.fresh).toBe(false)
expect(tmuxCalls('has-session')).toHaveLength(1)
})
it('fresh:true after a reboot killed the tmux server (cold restore + agent resume)', async () => {
await tmuxManager()
const r = await create(80, 24) // no live tmux session → cold start
expect(r.fresh).toBe(true)
})
// ── Output: one subscriber, one coalesced message, never a broadcast ──────────────────────
it('output goes to exactly one client, never broadcast', async () => {
await manager()
const { sessionId } = await create(80, 24)
spawned[0].onDataCb?.('out')
vi.advanceTimersByTime(20)
const data = fake.sent.filter((s) => s.channel === IPC.ptyData(sessionId))
expect(data).toHaveLength(1)
expect(data[0].to).toBe(SOLO)
expect(data[0].args[0]).toBe('out')
expect(fake.sent.some((s) => s.to === 'broadcast')).toBe(false)
})
it('many chunks in one flush window still collapse into ONE IPC message (unchanged coalescing)', async () => {
await manager()
const { sessionId } = await create(80, 24)
spawned[0].onDataCb?.('a')
spawned[0].onDataCb?.('b')
spawned[0].onDataCb?.('c')
vi.advanceTimersByTime(20)
const data = fake.sent.filter((s) => s.channel === IPC.ptyData(sessionId))
expect(data).toHaveLength(1)
expect(data[0].args[0]).toBe('abc')
})
it('exit reaches the one subscriber (and only it)', async () => {
await manager()
const { sessionId } = await create(80, 24)
spawned[0].onExitCb?.({ exitCode: 3 })
const exits = fake.sent.filter((s) => s.channel === IPC.ptyExit(sessionId))
expect(exits).toHaveLength(1)
expect(exits[0].to).toBe(SOLO)
expect(exits[0].args[0]).toBe(3)
})
// ── Size: min(one) is your own size, and you are never told what you already render ───────
it('a resize applies the caller s OWN size verbatim (min of one) — no clamping', async () => {
await manager()
const { sessionId } = await create(80, 24)
resize(sessionId, 132, 50)
expect(spawned[0].resizes).toEqual([{ cols: 132, rows: 50 }])
// …and the same-size fit that the ResizeObserver fires right after mount is a no-op:
// no second pty.resize, so tmux does not redraw the pane twice on a bulk project load.
// This is the ONE intended delta from the pre-co-attach behavior (which re-ioctl'd), and it
// is pinned here so it stays a decision rather than an accident.
resize(sessionId, 132, 50)
expect(spawned[0].resizes).toHaveLength(1)
})
it('a SOLO user receives ZERO pty:size broadcasts — he already renders his own fit', async () => {
await manager()
const { sessionId } = await create(80, 24)
fake.sent.length = 0
resize(sessionId, 100, 30)
resize(sessionId, 61, 17)
expect(spawned[0].resizes).toEqual([
{ cols: 100, rows: 30 },
{ cols: 61, rows: 17 }
])
expect(fake.sent.filter((s) => s.channel === IPC.ptySize(sessionId))).toEqual([])
})
// ── Flow control: his pause, his resume, nobody else's ────────────────────────────────────
it('the solo client s pause pauses the pty and his resume resumes it', async () => {
await manager()
const { sessionId } = await create(80, 24)
flow(sessionId, false)
expect(spawned[0].paused).toBe(true)
flow(sessionId, true)
expect(spawned[0].paused).toBe(false)
})
it('nothing else can cancel the solo client s pause (a second node s traffic does not touch it)', async () => {
await manager()
const { sessionId } = await create(80, 24, 'solo-1')
const other = await create(80, 24, 'solo-2')
flow(sessionId, false)
expect(spawned[0].paused).toBe(true)
// Activity on an unrelated session (resize, flow, kill) must not resume the paused one.
resize(other.sessionId, 100, 30)
flow(other.sessionId, false)
flow(other.sessionId, true)
kill(other.sessionId)
expect(spawned[0].paused).toBe(true)
flow(sessionId, true)
expect(spawned[0].paused).toBe(false)
})
// ── kill = detach (continuity!), destroy = end the tmux session ───────────────────────────
it('kill by the only subscriber releases the pty and frees the persistKey for a respawn', async () => {
await manager()
const { sessionId } = await create(80, 24)
kill(sessionId)
expect(spawned[0].killed).toBe(true)
const again = await create(80, 24)
expect(spawned).toHaveLength(2) // no stale index entry handed back
expect(again.sessionId).not.toBe(sessionId)
})
it('kill detaches the tmux CLIENT and never kills the tmux session (this is the continuity)', async () => {
await tmuxManager()
const { sessionId } = await create(80, 24)
kill(sessionId)
expect(spawned[0].killed).toBe(true) // the pty (tmux client) is released
expect(tmuxCalls('kill-session')).toEqual([]) // the session keeps running
})
it('terminates an agent foreground process group without typing into its pane', async () => {
await tmuxManager()
await create(80, 24)
paneProcessReply = '33293|codex\n'
processGroupReply = '33319\n'
// sig 0 is the post-SIGTERM grace probe: ESRCH means the group has already exited, so the
// bounded wait breaks on its first iteration (no fake-timer setTimeout is reached).
const signal = vi
.spyOn(process, 'kill')
.mockImplementation(((_pid: number, sig?: string | number) => {
if (sig === 0) throw Object.assign(new Error('ESRCH'), { code: 'ESRCH' })
return true
}) as typeof process.kill)
execCalls.length = 0
// No expectedAgentId here — the legacy shell-only guard path (an SSH/codex node's own
// model switch passes its id; this asserts the base kill mechanism stays intact).
await expect(fake.handlers[IPC.ptyTerminateForeground]('solo-1')).resolves.toBe(true)
expect(signal).toHaveBeenCalledWith(-33319, 'SIGTERM')
expect(tmuxCalls('send-keys')).toEqual([])
expect(execCalls.some((call) => call.file === 'ps' && call.args.includes('tpgid='))).toBe(true)
})
it('refuses to terminate the pane login shell', async () => {
await tmuxManager()
await create(80, 24)
paneProcessReply = '33293|-zsh\n'
processGroupReply = '33293\n'
const signal = vi.spyOn(process, 'kill').mockImplementation(() => true)
await expect(fake.handlers[IPC.ptyTerminateForeground]('solo-1')).resolves.toBe(false)
expect(signal).not.toHaveBeenCalled()
})
it('the detach path still snapshots the scrollback (cold restore after a reboot)', async () => {
await tmuxManager()
const { sessionId } = await create(80, 24)
spawned[0].onDataCb?.('some output') // marks the session dirty
vi.advanceTimersByTime(20)
execCalls.length = 0
kill(sessionId)
const captures = tmuxCalls('capture-pane')
expect(captures).toHaveLength(1)
// Exact (`=name:`): a bare target prefix-matches a longer session (tmux-naming `exactPaneTarget`).
expect(captures[0].args[captures[0].args.indexOf('-t') + 1]).toBe(`=${sessionName('solo-1')}:`)
})
it('killAll (app quit) detaches the client but never kills the tmux session', async () => {
const m = await tmuxManager()
await create(80, 24)
spawned[0].onDataCb?.('output')
vi.advanceTimersByTime(20)
await m.killAll()
expect(spawned[0].killed).toBe(true)
expect(tmuxCalls('kill-session')).toEqual([])
})
it('destroy (the × button) DOES kill the tmux session', async () => {
const m = await tmuxManager()
await create(80, 24)
await m.destroySession(SOLO, 'solo-1')
const kills = tmuxCalls('kill-session')
// ONE kill: we hold this session, so we know which socket it is on and the destroy aims only
// there. A destroy with NO live session cannot know, and fans out over both sockets
// (`localKillSockets`) — this length is what keeps that off the solo path.
expect(kills).toHaveLength(1)
expect(kills[0].args[kills[0].args.indexOf('-L') + 1]).toBe('node-terminal')
// `=` forces an EXACT tmux target. Node ids end in a counter, so `nt-a-1` is a prefix of
// `nt-a-12`, and tmux falls back to prefix matching whenever the exact name is not found.
expect(kills[0].args[kills[0].args.indexOf('-t') + 1]).toBe(`=${sessionName('solo-1')}`)
})
// Destroying a name we hold NOTHING for is how the session-memory panel ends an ORPHAN row — a
// tmux session with no node on any canvas. We cannot know which socket carries it, and on this
// machine a `nt-<id>` may be on `nodeterm-rmt`: that is where ANOTHER machine's nodeterm puts the
// sessions it SSHes in to spawn, and the panel sweeps (and offers to end) both sockets. Aiming
// only at `node-terminal` meant a confirm reading "this stops its tmux session" that killed
// nothing at all.
it('destroying a session we do not hold tries EVERY socket when the caller asks', async () => {
const m = await tmuxManager()
await m.destroySession(SOLO, 'never-opened-here', { everySocket: true })
const kills = tmuxCalls('kill-session')
expect(kills.map((c) => c.args[c.args.indexOf('-L') + 1]).sort()).toEqual([
'node-terminal',
'nodeterm-rmt'
])
for (const k of kills) {
expect(k.args[k.args.indexOf('-t') + 1]).toBe(`=${sessionName('never-opened-here')}`)
}
})
// ...but the fan-out is OPT-IN, and the unheld branch is not rare: an ordinary node-× on a node
// that was never mounted in this process takes it every time (the common case after an app
// restart, and every non-active project's node). Those callers know their own node and have no
// business speculating at `nodeterm-rmt`, which holds another machine's sessions.
it('destroying a session we do not hold stays on ONE socket by default', async () => {
const m = await tmuxManager()
await m.destroySession(SOLO, 'never-opened-here')
const kills = tmuxCalls('kill-session')
expect(kills.map((c) => c.args[c.args.indexOf('-L') + 1])).toEqual(['node-terminal'])
})
// The flag arrives verbatim from a renderer, so the wire path must demand a real `true` — and it
// must reach `endSession`, which is the half a `destroySession`-only test cannot see.
it('honours everySocket off the wire, and only for a literal true', async () => {
await tmuxManager()
await (fake.handlers[IPC.ptyDestroy](
SOLO,
'never-opened-here',
true
) as unknown as Promise<void>)
expect(tmuxCalls('kill-session').map((c) => c.args[c.args.indexOf('-L') + 1]).sort()).toEqual([
'node-terminal',
'nodeterm-rmt'
])
execCalls.length = 0
await (fake.handlers[IPC.ptyDestroy](
SOLO,
'never-opened-2',
'yes' as unknown as boolean
) as unknown as Promise<void>)
expect(tmuxCalls('kill-session').map((c) => c.args[c.args.indexOf('-L') + 1])).toEqual([
'node-terminal'
])
})
// ── recycle (move into worktree) = destroy, minus the "someone closed it" fan-out ─────────
// The solo user's node keeps its id and respawns in the new cwd: the tmux session must die
// exactly as the × kills it (otherwise `new-session -A` reattaches the OLD working directory),
// and — with nobody else watching — not a single extra message may go out.
it('recycle (move into worktree) kills the tmux session exactly like the × does', async () => {
await tmuxManager()
const { sessionId } = await create(80, 24)
fake.sent.length = 0
await (fake.handlers[IPC.ptyRecycle](SOLO, 'solo-1') as unknown as Promise<void>)
const kills = tmuxCalls('kill-session')
expect(kills).toHaveLength(1) // we hold the session; one socket, one kill
expect(kills[0].args[kills[0].args.indexOf('-t') + 1]).toBe(`=${sessionName('solo-1')}`)
expect(spawned[0].killed).toBe(true) // the old pty client is released
expect(fake.sent).toEqual([]) // solo: nobody to tell, so nothing is sent
// …and the respawn under the same node id gets a BRAND-NEW session (it never joins the dead one).
const again = await create(80, 24)
expect(spawned).toHaveLength(2)
expect(again.sessionId).not.toBe(sessionId)
expect(again.fresh).toBe(true)
})
// ── persistentSpawnAvailable (#925) ────────────────────────────────────────────────────────
// Nested here, not at top level: `tmuxManager()` and the platform/userData harness it needs are
// scoped to this describe.
describe('persistentSpawnAvailable (#925)', () => {
it('is true with tmux found and enabled', async () => {
const m = await tmuxManager()
expect(m.persistentSpawnAvailable()).toBe(true)
})
it('is false when tmux persistence is switched off (and no session-host applies on this platform)', async () => {
const { PtyManager } = await import('./pty-manager')
const m = new PtyManager()
m.init(() => ({ ...DEFAULT_SETTINGS, tmuxEnabled: false }))
m.registerIpc()
expect(m.persistentSpawnAvailable()).toBe(false)
})
})
// ── Headless client 0 on a TMUX-backed session (#925) ──────────────────────────────────────
// The plain-shell suite (pty-headless-taps.test.ts) cannot tell "detach client 0" from "destroy
// the session": there, releasing the last client kills the shell either way. Here the tmux
// session is what must survive, and `tmuxCalls('kill-session')` is the instrument that proves it.
describe('headless client 0 on a tmux-backed session (#925)', () => {
/**
* Let REAL I/O settle before asserting that no kill-session went out. An end path
* (`destroySession` → `runEndSession`) awaits real fs work (`deleteScrollback`) before it runs
* kill-session, so neither a synchronous look nor advancing the fake clock would ever see it.
* `realSetTimeout` is captured at module load, before `vi.useFakeTimers()` replaces the global.
*/
const drainRealIo = (): Promise<void> => new Promise((res) => realSetTimeout(res, 50))
it('write + output tap round-trip, then release detaches the tmux client and never kills the session', async () => {
const m = await tmuxManager()
const r = await m.createHeadless({ cols: 80, rows: 24, persistKey: 'n1' })
expect(r.sessionId).toBeTruthy()
expect(spawned).toHaveLength(1)
// It really is the tmux client for `nt-n1`, not a plain shell.
expect(spawnArgs[0].args).toContain('new-session')
expect(spawnArgs[0].args.slice(-2)).toEqual(['-s', sessionName('n1')])
const seen: string[] = []
const off = m.onOutput('n1', (c) => seen.push(c))
expect(m.writeHeadless('n1', 'echo hi\r')).toBe(true)
expect(spawned[0].writes).toEqual(['echo hi\r'])
spawned[0].onDataCb?.('hi')
vi.advanceTimersByTime(20) // past FLUSH_MS
expect(seen.join('')).toBe('hi')
off()
execCalls.length = 0
m.releaseHeadless('n1')
await drainRealIo()
expect(spawned[0].killed).toBe(true) // the tmux CLIENT pty is released
expect(tmuxCalls('kill-session')).toEqual([]) // the tmux session keeps running
expect(m.writeHeadless('n1', 'x')).toBe(false) // client 0 no longer holds anything
expect(spawned[0].writes).toEqual(['echo hi\r'])
// The node is detached, not deleted: when the user later opens its project, the renderer's
// create WARM-attaches to the still-running tmux session (a destroy would have tombstoned
// the node and refused this create with `closed`).
liveTmuxSessions.add(sessionName('n1'))
const again = await create(80, 24, 'n1')
expect(again.closed).toBeUndefined()
expect(again.fresh).toBe(false)
expect(spawned).toHaveLength(2) // a new tmux client for the same session
})
it('with a real client co-attached, release drops ONLY client 0: the viewer stays subscribed', async () => {
const m = await tmuxManager()
const headless = await m.createHeadless({ cols: 80, rows: 24, persistKey: 'n1' })
const viewer = await create(80, 24, 'n1') // the renderer's create joins via co-attach
expect(spawned).toHaveLength(1) // ONE tmux client, two subscribers
expect(viewer.sessionId).toBe(headless.sessionId)
execCalls.length = 0
m.releaseHeadless('n1')
await drainRealIo()
expect(spawned[0].killed).toBe(false) // the viewer still holds the tmux client
expect(tmuxCalls('kill-session')).toEqual([])
expect(m.writeHeadless('n1', 'x')).toBe(false) // client 0 is gone …
expect(spawned[0].writes).toEqual([])
// … while the viewer still gets the output,
fake.sent.length = 0
spawned[0].onDataCb?.('still here')
vi.advanceTimersByTime(20)
const data = fake.sent.filter((s) => s.channel === IPC.ptyData(viewer.sessionId))
expect(data.map((s) => s.to)).toEqual([SOLO])
expect(data.map((s) => s.args[0])).toEqual(['still here'])
// … and is the last subscriber: its own detach is what releases the client, still without
// touching the tmux session.
kill(viewer.sessionId)
expect(spawned[0].killed).toBe(true)
expect(tmuxCalls('kill-session')).toEqual([])
})
})
})