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): allow safely scoped managed SSH accounts

review7499aaad85c5
diff --git a/CLAUDE.md b/CLAUDE.md
index 05f446907..21ad1e053 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4904,8 +4904,10 @@ sessions is a hazard whatever kills it; this removes the hazard, not a proven ca
When a change is genuinely desktop-only (native menus, auto-update, Keychain), say so; the
point is to make the call consciously, not to leave the other surfaces to rot.
-Remote Codex safety (#736): `spawnNew` refuses managed SSH Codex accounts (including custom
-Codex harnesses and known agent-less login terminals) until remote validation and per-account
-hooks are wired. System Codex retains the host environment through `remoteAccountScopeEnvArgs`,
-even before remoteHome discovery during early attach. Never guess HOME/CODEX_HOME. Desktop and
-Server share this core gate; remote account management remains unavailable.
+Remote Codex safety (#736): `spawnNew` requires managed SSH Codex accounts (including custom
+Codex harnesses and known agent-less login terminals) to have a safe id in the saved Codex account
+list and a safe resolved `remoteHome`. `remoteAccountScopeEnvArgs` then supplies the private
+`CODEX_HOME` and account marker. An unresolved or unsafe home must refuse before env staging/spawn,
+not fall back to the host's system login. System Codex retains the host environment even before
+home discovery during early attach. Never guess HOME/CODEX_HOME. Desktop and Server share this
+core gate; Desktop supports the remote lifecycle, while Server account management remains unavailable.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index f9f775140..74976ac02 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -796,12 +796,12 @@ Two files, two audiences:
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 retain the remote host’s environment, including during early attach
-before remote home discovery; never inject a guessed `HOME` or `CODEX_HOME`. Custom Codex
-harnesses use the same account guard. Remote account add,
-login, retry, removal and identity UI remain follow-up work; the Server browser still explicitly
+Remote Codex account safety (#736): managed SSH Codex sessions and agent-less login terminals
+require a known safe account id and a safe resolved remote home before spawning. The remote env
+builder supplies their private `CODEX_HOME`; never fall back to the system login when that scope
+is unavailable. System SSH Codex retains the host environment, including during early attach
+before home discovery; never inject a guessed `HOME` or `CODEX_HOME`. Custom Codex harnesses use
+the same guard. Desktop supports remote account lifecycle; the Server browser still explicitly
rejects managed Codex account management.
Managed Codex login terminals are agent-less: core identifies their provider from the saved
diff --git a/src/core/pty-manager.ts b/src/core/pty-manager.ts
index 365d91ea4..2fe0dabd6 100644
--- a/src/core/pty-manager.ts
+++ b/src/core/pty-manager.ts
@@ -92,10 +92,11 @@ import {
AUTH_ENV_STRIP as CODEX_AUTH_ENV_STRIP,
codexSessionEnv,
isCodexScopeRefusal,
+ isSafeAccountId,
needsCodexAccountScope,
resolveCodexSessionScope
} from './codex-accounts-core'
-import { NODE_ID_MAX, isSafeNodeId } from './remote-safety'
+import { NODE_ID_MAX, isSafeNodeId, isSafeRemoteHome } from './remote-safety'
import { remoteAccountScopeEnvArgs } from './remote-account-env'
import { presenceHub } from './presence/hub'
import {
@@ -2149,12 +2150,17 @@ export class PtyManager {
if (options.requireRemote && !(options.sshRemote && options.persistKey && findSsh())) {
return { sessionId: '', fresh: false, unavailable: 'ssh' }
}
- // 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.
+ // A managed remote Codex account needs a known id and a safe resolved home so the
+ // remote env builder can supply its private CODEX_HOME. Otherwise a fresh spawn would
+ // silently use the host's system login. Agent-less login terminals use this same gate.
if (needsCodexAccountScope(options.agentId, options.accountId, (id) => this.isCodexAccount(id))) {
if (options.sshRemote) {
- if (options.accountId) {
+ if (
+ options.accountId &&
+ (!isSafeAccountId(options.accountId) ||
+ !this.isCodexAccount(options.accountId) ||
+ !isSafeRemoteHome(options.sshRemote.remoteHome))
+ ) {
return { sessionId: '', fresh: false, unavailable: 'codex-account' }
}
if (!options.persistKey || !findSsh()) {
diff --git a/src/core/pty-project-settings.test.ts b/src/core/pty-project-settings.test.ts
index f8b231561..5de1028fd 100644
--- a/src/core/pty-project-settings.test.ts
+++ b/src/core/pty-project-settings.test.ts
@@ -17,6 +17,7 @@ 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'
@@ -373,7 +374,7 @@ 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'])(
+ 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 })
@@ -383,12 +384,36 @@ describe('project settings at the spawn — SSH leg', () => {
}
)
- it('refuses an agent-less remote Codex login terminal', async () => {
+ 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' }] }))
- const result = await create({ accountId: 'remote-account', persistKey: NODE, sshRemote })
+ // 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) => {
@@ -396,11 +421,33 @@ describe('project settings at the spawn — SSH leg', () => {
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()
diff --git a/src/shared/types.ts b/src/shared/types.ts
index 16a8be585..962c763f2 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -307,7 +307,7 @@ 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). Remote managed Codex accounts also refuse until validation/hooks are wired.
+ * (§5 property 4). Remote managed Codex accounts refuse unknown/unsafe ids or unresolved/unsafe homes.
* System SSH Codex may attach before remote home discovery. Nothing spawned on refusal.
*/
unavailable?: 'ssh' | 'codex-account'