System skills cache can disappear during refresh

Summary

The embedded system skills cache under CODEX_HOME/skills/.system can temporarily disappear during startup/refresh. In practice this can make bundled skills such as $imagegen unavailable until another Codex process recreates the cache.

User impact

A user can see $imagegen fail to load because /Users/<user>/.codex/skills/.system/imagegen is missing. Running Codex again may recreate it, but it can disappear again later.

Observed behavior

On macOS with Codex v0.142.0, I observed:

• ~/.codex/skills/.system missing while the user expected $imagegen to be available.
• Starting codex exec recreated ~/.codex/skills/.system/imagegen.
• After the Codex process exited, the system cache could be missing again.
• The GitHub compare page for the proposed fix shows the branch is mergeable, but opening a PR is limited to collaborators on this repository.

Root cause hypothesis

codex-rs/skills/src/lib.rs::install_system_skills removes the existing CODEX_HOME/skills/.system directory before writing the embedded skills back into place. That creates a window where readers can observe .system as missing. If the process is interrupted or another process reads during that window, bundled skills can be unavailable.

Proposed fix

Refresh the embedded system skills in place instead of deleting the .system root first:

• collect the embedded paths
• write embedded files/directories into the existing cache root
• remove stale entries after the embedded files are written
• write the marker last

I pushed a candidate fix here:

https://github.com/openai/codex/compare/main...Tygb99:codex/system-skills-refresh-in-place?expand=1

Branch:

Tygb99/codex:codex/system-skills-refresh-in-place

Commit:

ea02050723c15994038768ab004974b14e652d88 (Refresh system skills in place)

Validation on the candidate branch

• Added a Unix regression test that verifies refresh keeps the existing .system cache root inode while still removing stale entries.
• Confirmed the new test fails before the fix because the cache root inode changes.
• just fmt
• just test -p codex-skills
• just fix -p codex-skills

Note

I attempted to open this as a PR, but GitHub reported that this repository limits opening pull requests to collaborators.