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.

fix(codex): refuse unsafe remote managed account launches

enes423e7eeaf72d
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0223794bd..45a88684a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -690,3 +690,10 @@ Two files, two audiences:
**If you change or discover something other contributors must know, update this file too.** An
invariant that only lives in a commit message is one refactor away from being violated by someone
who never saw it.
+
+Remote Codex account safety (#736): managed SSH Codex sessions and login terminals are refused
+until host-side account validation and per-account hooks are wired. Do not remove that gate merely
+to enable the picker. System SSH Codex sessions require a resolved absolute remote home and set
+`CODEX_HOME` plus an empty `NODETERM_CODEX_ACCOUNT_ID` explicitly via tmux. Remote account add,
+login, retry, removal and identity UI remain follow-up work; the Server browser still explicitly
+rejects managed Codex account management.
diff --git a/src/core/pty-manager.ts b/src/core/pty-manager.ts
index f2651bb85..d885b2d64 100644
--- a/src/core/pty-manager.ts
+++ b/src/core/pty-manager.ts
@@ -94,7 +94,8 @@ import {
codexSessionEnv,
isCodexScopeRefusal,
needsCodexAccountScope,
- resolveCodexSessionScope
+ resolveCodexSessionScope,
+ remoteCodexTmuxEnvArgs
} from './codex-accounts-core'
import { NODE_ID_MAX, isSafeNodeId } from './remote-safety'
import { presenceHub } from './presence/hub'
@@ -2145,18 +2146,26 @@ export class PtyManager {
if (options.requireRemote && !(options.sshRemote && options.persistKey && findSsh())) {
return { sessionId: '', fresh: false, unavailable: 'ssh' }
}
- // FAIL-CLOSED Codex account scope (S6 §5 property 4 / Decision 2, the carried PR-1 obligation).
- // A LOCAL Codex spawn that EXPLICITLY selected a managed account whose home is missing REFUSES
- // here — it must never fall through and spawn against the SYSTEM `~/.codex` (silently acting as
- // the wrong login is a worse failure for an explicit switch than for a first spawn). This is
- // deliberately STRICTER than the Claude account path below, which falls back with a warning
- // chip. `resolveCodexSessionScope` returns `{ unavailable: 'codex-account' }` for exactly that
- // case; we map it straight through to a real refusal and spawn NOTHING. The system account (no
- // id) always resolves. Remote (ssh) Codex sessions carry their account env via tmux `-e`.
- if (needsCodexAccountScope(options.agentId, options.accountId, (id) => this.isCodexAccount(id)) && !options.sshRemote) {
- const scope = resolveCodexSessionScope(platform().userDataDir, options.accountId)
- if (isCodexScopeRefusal(scope)) {
- return { sessionId: '', fresh: false, unavailable: 'codex-account' }
+ // Managed remote Codex accounts are not launchable yet: host-side account validation
+ // and per-account hook installation are not wired. Refuse agents AND login terminals;
+ // treating their id as Claude scope silently runs Codex against the host's system login.
+ if (needsCodexAccountScope(options.agentId, options.accountId, (id) => this.isCodexAccount(id))) {
+ if (options.sshRemote) {
+ if (
+ options.accountId ||
+ !options.sshRemote.remoteHome ||
+ !path.posix.isAbsolute(options.sshRemote.remoteHome)
+ ) {
+ return { sessionId: '', fresh: false, unavailable: 'codex-account' }
+ }
+ if (!options.persistKey || !findSsh()) {
+ return { sessionId: '', fresh: false, unavailable: 'ssh' }
+ }
+ } else {
+ const scope = resolveCodexSessionScope(platform().userDataDir, options.accountId)
+ if (isCodexScopeRefusal(scope)) {
+ return { sessionId: '', fresh: false, unavailable: 'codex-account' }
+ }
}
}
// A tmux-backed session is "fresh" (cold start) when no live session exists to reattach to
@@ -3062,10 +3071,14 @@ export class PtyManager {
// ABSOLUTE — tmux copies `-e` values verbatim (no `$HOME`/`~` expansion) — so we build it from
// the connection's resolved remote $HOME. Fail-open: an unknown remoteHome (home resolution
// failed on connect) skips the account env and the session runs under the remote `~/.claude`.
+ // Codex system scope must overwrite a managed scope inherited by the remote tmux
+ // server. spawnNew has already refused managed Codex and unresolved remote homes.
const remoteAccountEnv =
- options.accountId && options.sshRemote.remoteHome
- ? accountTmuxEnvArgs(remoteAccountConfigDirAbs(options.sshRemote.remoteHome, options.accountId))
- : []
+ needsCodexAccountScope(options.agentId, options.accountId, (id) => this.isCodexAccount(id))
+ ? remoteCodexTmuxEnvArgs(options.sshRemote.remoteHome!)
+ : options.accountId && options.sshRemote.remoteHome
+ ? accountTmuxEnvArgs(remoteAccountConfigDirAbs(options.sshRemote.remoteHome, options.accountId))
+ : []
// Custom-agent env for a REMOTE node: expand ${env:VAR} against the LOCAL process env (the
// key stays local; only the resolved VALUE travels over SSH). PATH is skipped — the local
// machine can't see the remote box's PATH, so a locally-resolved PATH would break CLI
diff --git a/src/core/pty-project-settings.test.ts b/src/core/pty-project-settings.test.ts
index 801338b94..65390aa08 100644
--- a/src/core/pty-project-settings.test.ts
+++ b/src/core/pty-project-settings.test.ts
@@ -370,6 +370,41 @@ describe('project settings at the spawn — SSH leg', () => {
const create = async (options: Record<string, unknown>): Promise<unknown> =>
fake.handlers[IPC.ptyCreate](1, { cols: 80, rows: 24, ...options })
+ it.each(['remote-account', '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('refuses an agent-less remote Codex login terminal', 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 })
+ expect(result).toMatchObject({ unavailable: 'codex-account' })
+ expect(spawns).toHaveLength(0)
+ })
+
+ it.each([undefined, '', 'relative/home', 'C:\\Users\\remote'])('refuses a remote Codex system scope with home %s', async (remoteHome) => {
+ await manager(null)
+ const result = await create({ agentId: 'codex', persistKey: NODE, sshRemote: { ...sshRemote, remoteHome } })
+ expect(result).toMatchObject({ unavailable: 'codex-account' })
+ expect(spawns).toHaveLength(0)
+ })
+
+ it('writes explicit remote system Codex scope into tmux, without Claude scope', async () => {
+ await manager(null)
+ await create({ agentId: 'codex', persistKey: NODE, sshRemote })
+ expect(spawns).toHaveLength(1)
+ const command = spawns[0].args.join(' ')
+ expect(command).toContain('CODEX_HOME=/home/u/.codex')
+ expect(command).toContain('NODETERM_CODEX_ACCOUNT_ID=')
+ expect(command).not.toContain('CLAUDE_CONFIG_DIR=')
+ })
+
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 })
diff --git a/src/renderer/components/kanban/ModalTerminal.tsx b/src/renderer/components/kanban/ModalTerminal.tsx
index 5ffc557c9..62a9cc3db 100644
--- a/src/renderer/components/kanban/ModalTerminal.tsx
+++ b/src/renderer/components/kanban/ModalTerminal.tsx
@@ -1,3 +1,4 @@
+import { ptyRefusal } from '@shared/pty-refusal'
import { useCallback, useEffect, useRef, useState } from 'react'
import { Terminal } from '@xterm/xterm'
import { FitAddon } from '@xterm/addon-fit'
@@ -314,8 +315,9 @@ export function ModalTerminal({ nodeId, spawn, searchOpen, onCloseSearch }: Moda
})
// Refused core-side (the master died inside our round-trip, or `ssh` is missing).
if (res.unavailable) {
- term.write('\r\n\x1b[90m[not connected — nothing was started locally]\x1b[0m\r\n')
- if (projectId) reportSshDrop(projectId, nodeId)
+ const refusal = ptyRefusal(res.unavailable)
+ term.write(`\r\n\x1b[90m[${refusal.message}]\x1b[0m\r\n`)
+ if (refusal.connectionLost && projectId) reportSshDrop(projectId, nodeId)
return
}
// Another client permanently deleted this node's session — never resurrect it (no live session
diff --git a/src/renderer/nodes/TerminalNode.tsx b/src/renderer/nodes/TerminalNode.tsx
index d7c01531f..2cee70a99 100644
--- a/src/renderer/nodes/TerminalNode.tsx
+++ b/src/renderer/nodes/TerminalNode.tsx
@@ -1,3 +1,4 @@
+import { ptyRefusal } from '@shared/pty-refusal'
import { Suspense, lazy, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react'
import { NODE_MIN_SIZES } from '../lib/nodeSizing'
import {
@@ -3138,10 +3139,15 @@ export function TerminalNode({
// round-trip, or `ssh` is missing). Nothing was spawned — land in the same offline state
// the near-side guard above produces, retry included.
if (unavailable) {
- setCo(termKey, { offline: true })
- if (!disposed)
- term.write('\r\n\x1b[90m[not connected — nothing was started locally]\x1b[0m\r\n')
- if (sshProjectId) reportSshDrop(sshProjectId, id)
+ const refusal = ptyRefusal(unavailable)
+ setCo(
+ termKey,
+ refusal.connectionLost
+ ? { offline: true }
+ : { offline: false, spawnError: refusal.message }
+ )
+ if (!disposed) term.write(`\r\n\x1b[90m[${refusal.message}]\x1b[0m\r\n`)
+ if (refusal.connectionLost && sshProjectId) reportSshDrop(sshProjectId, id)
return
}
// REFUSED: core's tombstone says another client deleted this node while we weren't
diff --git a/src/shared/pty-refusal.test.ts b/src/shared/pty-refusal.test.ts
new file mode 100644
index 000000000..934a709fe
--- /dev/null
+++ b/src/shared/pty-refusal.test.ts
@@ -0,0 +1,12 @@
+import { describe, expect, it } from 'vitest'
+import { ptyRefusal } from './pty-refusal'
+
+describe('PTY refusal presentation', () => {
+ it('does not disconnect a healthy SSH project for an account refusal', () => {
+ expect(ptyRefusal('codex-account')).toMatchObject({ connectionLost: false })
+ expect(ptyRefusal('codex-account').message).toContain('SSH managed accounts are not supported yet')
+ })
+ it('retains reconnect behavior for an SSH refusal', () => {
+ expect(ptyRefusal('ssh')).toEqual({ connectionLost: true, message: 'not connected — nothing was started locally' })
+ })
+})
diff --git a/src/shared/pty-refusal.ts b/src/shared/pty-refusal.ts
new file mode 100644
index 000000000..15892a33a
--- /dev/null
+++ b/src/shared/pty-refusal.ts
@@ -0,0 +1,15 @@
+import type { PtyCreateResult } from './types'
+
+/** Shared by canvas and board: account refusal is never an SSH connection failure. */
+export function ptyRefusal(unavailable: NonNullable<PtyCreateResult['unavailable']>): {
+ message: string
+ connectionLost: boolean
+} {
+ if (unavailable === 'codex-account') {
+ return {
+ message: 'Codex account scope is unavailable. Local managed homes must exist; SSH managed accounts are not supported yet, and SSH system accounts require a resolved remote home. Nothing was started.',
+ connectionLost: false
+ }
+ }
+ return { message: 'not connected — nothing was started locally', connectionLost: true }
+}
diff --git a/src/shared/types.ts b/src/shared/types.ts
index d05cad046..c09135462 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -307,7 +307,8 @@ export interface PtyCreateResult {
*
* `'codex-account'` is the S6 fail-closed twin: a LOCAL Codex node that explicitly selected a
* managed account whose home is missing refuses rather than spawning against the system login
- * (§5 property 4). Same contract — nothing spawned, the renderer shows the node's refusal.
+ * (§5 property 4). Remote managed Codex accounts (validation/hooks not wired) and remote
+ * system Codex with unresolved home also refuse. Nothing spawned; never use another account.
*/
unavailable?: 'ssh' | 'codex-account'
}