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(windows): gate shared Codex identity off on Windows, visibly

review19219348e843
diff --git a/src/core/codex-identity-caps.test.ts b/src/core/codex-identity-caps.test.ts
index 4e294706b..922e45e37 100644
--- a/src/core/codex-identity-caps.test.ts
+++ b/src/core/codex-identity-caps.test.ts
@@ -17,6 +17,9 @@ import {
const remote = (yes: boolean) => () => Promise.resolve(yes)
/** Stand-in for the managed-runtime stat — "can this INSTALL run an app-server at all?". */
const appServer = (yes: boolean) => () => yes
+/** The probes only run off Windows; pinning the host keeps these rows meaning the same on a
+ * Windows CI runner (where the answer is the deliberate `unsupported-platform` gate below). */
+const POSIX = 'linux'
import {
resetCodexThreadIdentityAuthSecret,
setCodexThreadIdentityAuthSecret
@@ -44,7 +47,7 @@ afterEach(() => {
describe('codexIdentityCaps', () => {
it('says yes, and installs the launcher, once the secret is in and the CLI has --remote', async () => {
setCodexThreadIdentityAuthSecret(randomBytes(32))
- const caps = await refreshCodexIdentityCaps(remote(true), appServer(true))
+ const caps = await refreshCodexIdentityCaps(remote(true), appServer(true), POSIX)
expect(caps.shared).toBe(true)
expect(fs.existsSync(caps.launcherPath as string)).toBe(true)
})
@@ -52,7 +55,7 @@ describe('codexIdentityCaps', () => {
it('says no without the secret, and installs nothing', () => {
// Half-armed is the state to avoid: a launcher on PATH with no capability to present would
// reach the routes, be refused, and fall back one process later. Better to never name it.
- return refreshCodexIdentityCaps(remote(true), appServer(true)).then((caps) => {
+ return refreshCodexIdentityCaps(remote(true), appServer(true), POSIX).then((caps) => {
expect(caps).toEqual({
shared: false,
launcherPath: null,
@@ -68,7 +71,7 @@ describe('codexIdentityCaps', () => {
// app-server but no --remote dies on a usage error where nothing can fall back. Answering it
// here turns a dead node into a plain-codex node on every machine, not just the tester's.
setCodexThreadIdentityAuthSecret(randomBytes(32))
- const caps = await refreshCodexIdentityCaps(remote(false), appServer(true))
+ const caps = await refreshCodexIdentityCaps(remote(false), appServer(true), POSIX)
expect(caps).toEqual({
shared: false,
launcherPath: null,
@@ -88,7 +91,7 @@ describe('codexIdentityCaps', () => {
// not, and this row is what keeps it inert.
it('says no on an npm install — `--remote` in help, no standalone runtime — and writes no launcher', async () => {
setCodexThreadIdentityAuthSecret(randomBytes(32))
- const caps = await refreshCodexIdentityCaps(remote(true), appServer(false))
+ const caps = await refreshCodexIdentityCaps(remote(true), appServer(false), POSIX)
expect(caps).toEqual({
shared: false,
launcherPath: null,
@@ -106,7 +109,7 @@ describe('codexIdentityCaps', () => {
await refreshCodexIdentityCaps(() => {
asked += 1
return Promise.resolve(true)
- }, appServer(false))
+ }, appServer(false), POSIX)
expect(asked).toBe(0)
})
@@ -116,7 +119,7 @@ describe('codexIdentityCaps', () => {
setCodexThreadIdentityAuthSecret(randomBytes(32))
const threw = await refreshCodexIdentityCaps(remote(true), () => {
throw new Error('stat failed')
- })
+ }, POSIX)
expect(threw).toEqual({
shared: false,
launcherPath: null,
@@ -125,7 +128,8 @@ describe('codexIdentityCaps', () => {
})
resetCodexIdentityCapsForTests()
const rejected = await refreshCodexIdentityCaps(remote(true), () =>
- Promise.reject(new Error('probe timed out'))
+ Promise.reject(new Error('probe timed out')),
+ POSIX
)
expect(rejected.shared).toBe(false)
expect(fs.existsSync(path.join(dir, 'codex-bin', 'nodeterm-codex'))).toBe(false)
@@ -141,12 +145,12 @@ describe('codexIdentityCaps', () => {
await Promise.resolve()
expect(settled).toBe(false)
setCodexThreadIdentityAuthSecret(randomBytes(32))
- await refreshCodexIdentityCaps(remote(true), appServer(true))
+ await refreshCodexIdentityCaps(remote(true), appServer(true), POSIX)
expect((await asked).shared).toBe(true)
})
it('answers immediately once refreshed', async () => {
- await refreshCodexIdentityCaps(remote(false), appServer(true))
+ await refreshCodexIdentityCaps(remote(false), appServer(true), POSIX)
expect(await codexIdentityCaps()).toEqual({
shared: false,
launcherPath: null,
@@ -156,6 +160,42 @@ describe('codexIdentityCaps', () => {
})
})
+describe('codexIdentityCaps — Windows (phase 1: deliberately off, and saying so)', () => {
+ it('answers unsupported-platform without probing anything or writing a launcher', async () => {
+ setCodexThreadIdentityAuthSecret(randomBytes(32))
+ let probed = 0
+ const caps = await refreshCodexIdentityCaps(
+ () => {
+ probed += 1
+ return Promise.resolve(true)
+ },
+ () => {
+ probed += 1
+ return true
+ },
+ 'win32'
+ )
+ expect(probed).toBe(0)
+ expect(caps).toEqual({
+ shared: false,
+ launcherPath: null,
+ remoteFlag: false,
+ appServer: false,
+ unavailableReason: 'unsupported-platform'
+ })
+ expect(fs.existsSync(path.join(dir, 'codex-bin', 'nodeterm-codex'))).toBe(false)
+ expect(await codexIdentityCaps()).toEqual(caps)
+ })
+
+ it('every other platform carries no reason (unchanged shape)', async () => {
+ for (const p of ['darwin', 'linux']) {
+ resetCodexIdentityCapsForTests()
+ const caps = await refreshCodexIdentityCaps(remote(false), appServer(true), p)
+ expect(caps).not.toHaveProperty('unavailableReason')
+ }
+ })
+})
+
describe('codexManagedRuntimeInstalled', () => {
// The path is not inferred: `codex app-server daemon start` names it verbatim in its refusal, and
// `codex app-server daemon stop` reports it as `managedCodexPath` in JSON.
diff --git a/src/core/codex-identity-caps.ts b/src/core/codex-identity-caps.ts
index a60c8de57..d248fbc65 100644
--- a/src/core/codex-identity-caps.ts
+++ b/src/core/codex-identity-caps.ts
@@ -48,7 +48,7 @@ import { promisify } from 'util'
import { IPC } from '../shared/ipc'
import { directExecutableInvocation } from './exec-path'
import { platform } from './platform'
-import { type CodexIdentityCaps } from '../shared/types'
+import { UNKNOWN_CODEX_IDENTITY_CAPS, type CodexIdentityCaps } from '../shared/types'
import { installCodexLauncher, codexThreadIdentityAvailable } from './codex-identity-proxy'
import { codexHome } from './usage/codex-usage'
import { findInLoginPath } from './pty-manager'
@@ -171,15 +171,27 @@ let announce: ((c: CodexIdentityCaps) => void) | null = null
*/
export async function refreshCodexIdentityCaps(
probeRemote: () => Promise<boolean> = probeRemoteFlag,
- probeAppServer: () => boolean | Promise<boolean> = codexManagedRuntimeInstalled
+ probeAppServer: () => boolean | Promise<boolean> = codexManagedRuntimeInstalled,
+ platformName: NodeJS.Platform | string = process.platform
): Promise<CodexIdentityCaps> {
- const appServer = await Promise.resolve()
- .then(() => probeAppServer())
- .catch(() => false)
- const remoteFlag = appServer ? await probeRemote() : false
- const launcher =
- appServer && remoteFlag && codexThreadIdentityAvailable() ? installCodexLauncher() : null
- latest = { shared: !!launcher, launcherPath: launcher, remoteFlag, appServer }
+ if (platformName === 'win32') {
+ // Windows, phase 1: a DELIBERATE off, said out loud. It used to be off by accident — the stat
+ // looks for an extensionless `codex` (the Windows runtime would be `codex.exe`) and the launcher
+ // is an `sh` script PowerShell/cmd cannot resolve by name — with nothing telling the user. The
+ // early return also guarantees `installCodexLauncher` never drops an sh launcher onto a Windows
+ // PATH should a later release ship an extensionless `codex`. Lifting it needs device facts
+ // first (standalone `codex.exe` layout, the daemon's control channel, `--remote`) and a
+ // non-sh launcher; see docs/codex-shared-identity.md ("Windows").
+ latest = { ...UNKNOWN_CODEX_IDENTITY_CAPS, unavailableReason: 'unsupported-platform' }
+ } else {
+ const appServer = await Promise.resolve()
+ .then(() => probeAppServer())
+ .catch(() => false)
+ const remoteFlag = appServer ? await probeRemote() : false
+ const launcher =
+ appServer && remoteFlag && codexThreadIdentityAvailable() ? installCodexLauncher() : null
+ latest = { shared: !!launcher, launcherPath: launcher, remoteFlag, appServer }
+ }
if (announce) {
announce(latest)
announce = null
diff --git a/src/core/codex-identity-proxy.test.ts b/src/core/codex-identity-proxy.test.ts
index 5de37fc42..8425710d5 100644
--- a/src/core/codex-identity-proxy.test.ts
+++ b/src/core/codex-identity-proxy.test.ts
@@ -7,6 +7,7 @@ import {
accountScope,
bindCodexThreadIdentity,
codexLauncherDir,
+ codexLauncherPathDir,
codexThreadIdentityHasLiveConflict,
forgetCodexThreadIdentitiesForNode,
codexThreadIdentityRoot,
@@ -107,6 +108,12 @@ describe('codex thread identity store', () => {
expect(codexLauncherDir()).toBe(path.join(dir, 'codex-bin'))
})
+ it('puts the launcher dir on a session PATH everywhere but Windows (gated off there, phase 1)', () => {
+ expect(codexLauncherPathDir('darwin')).toBe(path.join(dir, 'codex-bin'))
+ expect(codexLauncherPathDir('linux')).toBe(path.join(dir, 'codex-bin'))
+ expect(codexLauncherPathDir('win32')).toBeNull()
+ })
+
it('round-trips a record and resolves its owning node', () => {
writeCodexThreadIdentity('thread-1', 'node-1', '/data/hook-endpoint.env', recordsRoot)
expect(resolveCodexThreadNodeIdentity('thread-1', recordsRoot)).toBe('node-1')
diff --git a/src/core/codex-identity-proxy.ts b/src/core/codex-identity-proxy.ts
index 59a73c68c..662d401d8 100644
--- a/src/core/codex-identity-proxy.ts
+++ b/src/core/codex-identity-proxy.ts
@@ -658,6 +658,16 @@ export function codexLauncherDir(): string {
return path.join(platform().userDataDir, 'codex-bin')
}
+/**
+ * The directory a LOCAL shared-identity session gets prepended to its PATH, or null where there is
+ * none to reach. Windows answers null: shared identity is gated off there (`refreshCodexIdentityCaps`
+ * returns `unsupported-platform`), the launcher is an extensionless sh script cmd/PowerShell could
+ * not resolve anyway, and a session's PATH should be exactly the user's.
+ */
+export function codexLauncherPathDir(platformName: NodeJS.Platform | string = process.platform): string | null {
+ return platformName === 'win32' ? null : codexLauncherDir()
+}
+
export const CODEX_LAUNCHER_NAME = 'nodeterm-codex'
export function codexLauncherPath(): string {
diff --git a/src/core/pty-manager.ts b/src/core/pty-manager.ts
index 0e7282b15..2ff535ecf 100644
--- a/src/core/pty-manager.ts
+++ b/src/core/pty-manager.ts
@@ -165,7 +165,7 @@ import { NODE_ID_MAX, isSafeNodeId, isSafeRemoteHome } from './remote-safety'
import { remoteAccountScopeEnvArgs } from './remote-account-env'
import { presenceHub } from './presence/hub'
import {
- codexLauncherDir,
+ codexLauncherPathDir,
forgetCodexThreadIdentitiesForNode,
installCodexLauncher
} from './codex-identity-proxy'
@@ -3806,14 +3806,19 @@ export class PtyManager {
// managed launcher by NAME, so its directory goes first on THIS session's PATH only. A plain
// terminal, and every other agent, sees the PATH it always saw. The launcher itself falls back
// to the bare CLI, so a session that gets the PATH but no identity is still a working session.
- if (options.agentId && hasSharedIdentity(options.agentId as AgentId) && !options.sshRemote) {
- // Windows exposes the inherited variable as `Path`; reading only the POSIX spelling
+ // `codexLauncherPathDir()` is null on Windows, where shared identity is gated off (phase 1).
+ const launcherDir =
+ options.agentId && hasSharedIdentity(options.agentId as AgentId) && !options.sshRemote
+ ? codexLauncherPathDir()
+ : null
+ if (launcherDir) {
+ // (Path-key aware for when Windows support lands — phase 2.) Windows exposes the inherited variable as `Path`; reading only the POSIX spelling
// silently drops the user's PATH and leaves the managed launcher unable to find `codex`.
// Prepend onto the key the environment ALREADY uses: a spread of Windows' `process.env` spells
// it `Path`, and adding a second `PATH` beside it hands the child two case-insensitively equal
// variables — which one it reads is up to the child's runtime.
const pathKey = envPathKey(env)
- env[pathKey] = `${codexLauncherDir()}${path.delimiter}${env[pathKey] ?? ''}`
+ env[pathKey] = `${launcherDir}${path.delimiter}${env[pathKey] ?? ''}`
}
// Managed Claude account: the whole session runs under the account's private config
diff --git a/src/renderer/components/settings/sections/AgentsSection.codexWindows.test.tsx b/src/renderer/components/settings/sections/AgentsSection.codexWindows.test.tsx
new file mode 100644
index 000000000..d144b2c3f
--- /dev/null
+++ b/src/renderer/components/settings/sections/AgentsSection.codexWindows.test.tsx
@@ -0,0 +1,51 @@
+// @vitest-environment jsdom
+//
+// Shared Codex identity is gated off on Windows (phase 1). The node works fine, so there is no
+// per-node chip — but Settings says so once, instead of leaving the feature silently missing.
+import { describe, it, expect, afterEach, vi } from 'vitest'
+import { act } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { UNKNOWN_CODEX_IDENTITY_CAPS } from '@shared/types'
+import { resetCodexIdentityCapsForTests } from '../../../state/codexIdentity'
+import { AgentsSection } from './AgentsSection'
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+const LINE = 'Shared Codex app-server is not available on Windows yet'
+let root: Root | null = null
+let host: HTMLElement | null = null
+
+async function render(): Promise<string> {
+ ;(window as unknown as { nodeTerminal: unknown }).nodeTerminal = {
+ settings: { save: vi.fn(async () => undefined) },
+ claude: { cliCaps: vi.fn(async () => null) }
+ }
+ host = document.createElement('div')
+ document.body.appendChild(host)
+ root = createRoot(host)
+ await act(async () => {
+ root!.render(<AgentsSection isActive />)
+ })
+ return host.textContent ?? ''
+}
+
+afterEach(() => {
+ if (root) act(() => root!.unmount())
+ host?.remove()
+ root = null
+ host = null
+ resetCodexIdentityCapsForTests()
+})
+
+describe('Settings → Agents: shared Codex identity on Windows', () => {
+ it('shows one muted line when the core reports unsupported-platform', async () => {
+ resetCodexIdentityCapsForTests({ ...UNKNOWN_CODEX_IDENTITY_CAPS, unavailableReason: 'unsupported-platform' })
+ const text = await render()
+ expect(text.split(LINE)).toHaveLength(2)
+ })
+
+ it('says nothing on any other answer', async () => {
+ resetCodexIdentityCapsForTests(UNKNOWN_CODEX_IDENTITY_CAPS)
+ expect(await render()).not.toContain(LINE)
+ })
+})
diff --git a/src/renderer/components/settings/sections/AgentsSection.tsx b/src/renderer/components/settings/sections/AgentsSection.tsx
index 14c609f8f..e43de29b2 100644
--- a/src/renderer/components/settings/sections/AgentsSection.tsx
+++ b/src/renderer/components/settings/sections/AgentsSection.tsx
@@ -40,6 +40,7 @@ import {
unsupportedModesNote
} from '@shared/agents/approval-mode'
import { codexApprovalCaps } from '@renderer/state/codexCli'
+import { codexIdentityCapsNow } from '@renderer/state/codexIdentity'
import { AgentIcon } from '../../../lib/agentIcons'
import { chipFor } from '../../../lib/keybindingOverrides'
import { NODE_IDENTITY_STRICT_DATE } from '@shared/node-identity'
@@ -550,6 +551,11 @@ export function AgentsSection({ isActive }: { isActive: boolean }): React.JSX.El
Overrides the managed per-node launcher — sessions join as plain clients.
</span>
) : null}
+ {hasSharedIdentity(id) && codexIdentityCapsNow().unavailableReason === 'unsupported-platform' ? (
+ <span className="text-[12px] text-muted">
+ Shared Codex app-server is not available on Windows yet; each node runs its own codex.
+ </span>
+ ) : null}
</div>
))}
</div>
diff --git a/src/shared/types.ts b/src/shared/types.ts
index 9b6c290e3..11d8a24e4 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -3691,6 +3691,10 @@ export interface CodexIdentityCaps {
* flag in its help and no such runtime, so it can never serve a shared identity. Unknown ⇒
* false ⇒ plain codex. */
appServer: boolean
+ /** Why shared identity is off by DESIGN rather than by probe, when it is. `unsupported-platform`
+ * = a Windows core (phase 1: not wired there yet; every node runs its own codex). Absent on
+ * every other answer — an older core never sends it. */
+ unavailableReason?: 'unsupported-platform'
}
/** The answer before the probe has run, and the one the Server Edition gives on purpose. */