SSH works but the remote Codex desktop cannot initialize its database

Source: Troubleshooting reference

Symptom: ordinary SSH succeeds, while app-server startup fails with a damaged-database recovery error and Cross-device link (os error 18).

Root cause: individually symlinked SQLite files and their recovery directory can cross filesystem boundaries. Separately, placing WAL databases on NFS allows incompatible multi-host access. Moving them to another NFS export does not solve that problem. A clean SQLite integrity check does not establish safe WAL locking or successful recovery renames.

Confirm on Linux: inspect the actual filesystem and link targets, not the directory names. Avoid printing authentication files.

findmnt -T ~/.codex -o TARGET,FSTYPE
readlink -f ~/.codex/state_5.sqlite
readlink -f ~/.codex/db-backups
tail -n 30 ~/.codex/app-server-control/app-server.log

Fix: stop writers and make a full verified backup of both the legacy root and any existing destination first, using codex.sh backup SOURCE DESTINATION as described in host-local state. Select persistent host-local state with install/host.sh configure, run bash install/codex.sh sync-runtime, and reconnect the desktop’s SSH connection. Verify its daemon received the new CODEX_HOME and that its Unix socket and databases are local. Keep the old shared tree for explicit history recovery. Do not delete a database merely because startup called it damaged, and do not symlink app-server-control: the native Unix listener requires a real directory. See host-local state.

If the error still names ~/.codex after the desktop is working locally, inspect the failing launcher’s environment. An old terminal/tmux shell may retain the previous codex() function, and non-login shells never read login profiles. Current Bash/Zsh wrappers resolve host policy lazily; reload the shell once after deployment (exec zsh -l or exec bash -l). A new desktop process using the local root does not prove an old terminal inherited that same environment.

---