fix(server): Codex accounts connect on Windows without Developer Mode#15277

Problem

A Codex account that runs in a shadow home cannot start on Windows unless Developer Mode is on. That is every "Connect with ChatGPT" account, plus any instance with a shadow home path. materializeCodexShadowHome links each shared entry with a symlink, Windows refuses an unprivileged process with EPERM, and the provider shows "Could not check Codex right now". Turning Developer Mode on once does not hold, because new entries keep appearing in ~/.codex and each one needs another link.

Fixes #14325.

Change

When Windows refuses a symlink, the shadow home falls back to what an unprivileged process can create, from that entry on:

• Directories are linked with junctions, through node:fs because Effect's symlink takes no type. Sessions, skills, plugins and the other shared directories behave as they do with symlinks.
• Files are no longer linked. A file Codex creates in the shadow home is left alone instead of raising the conflict error. A real directory where a shared directory belongs still raises it. File links made while symlinks were allowed are kept; one that points into a different home is removed.
• The fallback is recorded in the shadow home (.t3-local-files) and kept. Codex creates its own state_5.sqlite, installation_id and so on in a home with no file links. If a later pass went back to symlinks because someone enabled Developer Mode, each of those files would hit the conflict rule and disable the provider again.

There is no capability probe: the first refused link is the signal. macOS and Linux never reach the new code. On Windows, a home that has never been refused a link does one extra readlink per pass to look for the marker and is otherwise unchanged. .t3-local-files is a reserved name and is never linked in from the shared home.

Why files are not linked

Triage pointed out that files still need a link and that a hard link or copy is not a symlink. I looked for a file link that holds up and did not find one:

• Codex rewrites config.toml by rename. With codex-cli 0.154.0, codex mcp add against a hard-linked config.toml left the two names on different inodes (nlink went from 2 to 1 on both) and the other copy stale.
• After that the shadow entry is a plain file that cannot be told apart from a real conflicting file without per-entry bookkeeping. Replacing it silently would break the rule that a real config.toml in the shadow home raises and leaves both copies untouched.
• Hard-linking the top-level SQLite files gives one database two WAL names.
• A junction aimed at a file is created without error and then fails to open, so "junction for everything on win32" is not an option either.

The cost is that on these hosts config.toml and AGENTS.md are not shared into the shadow home. The Codex provider guide now says so. Sharing them would mean T3 Code overwriting the shadow copy on every pass, which is a product call I left alone.

Scope and approval

Bug fix for #14325, triaged in this comment. It follows the constraints listed there: junctions go through node:fs and only for directories, nothing is hard-linked or copied so the next refresh has no unexpected plain file to reject, and an entry that cannot be linked no longer fails the check. The change is one file of logic (CodexHomeLayout.ts), its tests, and one paragraph in the user guide, because "the accounts share sessions and configuration" is not fully true on these hosts.

Not in scope: #5817. On a home that has not been refused a link yet, a real file that collides is still a conflict, exactly as on main. A fresh home cannot get there, because the known directories are linked before anything from the listing and the first of them triggers the fallback.

Verification

Windows 11 Home 26200, Developer Mode off, standard user, Node 24.21.0, codex-cli 0.154.0. fs.symlink returns EPERM on this host for files and directories.

Before and after on the real filesystem, no fakes. A script builds a disposable shared home shaped like ~/.codex and calls materializeCodexShadowHome.

main at 77823bd10:

This branch:

A further pass over an already prepared home changed no entry in it (same inode, birth time and mtime for all 11).

Real Codex in that home. Started codex app-server with CODEX_HOME set to the prepared shadow home and sent initialize and thread/list; both answered. Codex created state_5.sqlite, goals_1.sqlite, logs_2.sqlite, queue_1.sqlite and memories_1.sqlite with their -wal/-shm files, plus installation_id, in the shadow home. The next two passes succeeded.

Tests. In apps/server: vp test run src/provider/Drivers/CodexHomeLayout.test.ts

The 7 skips are the skipIf(!symlinksSupported) tests, 4 existing and 3 new. The hosted runs are this run on a scratch branch of my fork that adds a three-OS workflow for this one file; that branch is not part of the PR.

The new tests fake the refusal (a FileSystem whose symlink fails with the same EPERM Effect produces, plus HostProcessPlatform set to win32), so they run on every platform. On a Windows host that really refuses symlinks they only pass if the links are real junctions. No Node API tells a junction from a directory symlink, so a runner that can create symlinks cannot prove that part.

With main's CodexHomeLayout.ts swapped in, the 8 new tests that run on this host fail.

The existing CodexManagedRuntime.test.ts shows the same thing one level up. Its two "additional account" cases fail on this host on main with ProviderSetupError: Codex shadow home filesystem operation 'symlink' failed. On this branch they get through provider setup and stop at a later assertion that expects forward slashes in a path, which this change does not touch.

Also ran tsc --noEmit for apps/server (0 errors), and vp lint and vp fmt --check on the changed files.

Not checked

• A full "Connect with ChatGPT" sign-in in the desktop app. I verified the function that fails and Codex running in the home it produces, not the OAuth flow around them.
• A Codex home on a network share, where a junction cannot point. That setup fails today as well.

Claude Fable 5.1, Claude Code