shell_snapshot validation fails when zsh KSH_OPTION_PRINT is enabled
Open 💬 1 comment Opened Aug 1, 2026 by Aloxaf
What version of Codex CLI is running?
0.146.0
What subscription do you have?
ChatGPT Pro
Which model were you using?
gpt-5.6-sol
What platform is your computer?
Linux 7.1.5-zen1-2-zen x86_64 unknown
What terminal emulator and version are you using (if applicable)?
tmux 3.7b; zsh 5.9.2 (x86_64-pc-linux-gnu)
Codex doctor report
{
"schemaVersion": 1,
"generatedAt": "1785559855s since unix epoch",
"overallStatus": "ok",
"codexVersion": "0.146.0",
"checks": {
"app_server.status": {
"id": "app_server.status",
"category": "app-server",
"status": "ok",
"summary": "background server is not running",
"details": {
"control socket": "/home/aloxaf/.codex/app-server-control/app-server-control.sock",
"daemon state dir": "/home/aloxaf/.codex/app-server-daemon",
"mode": "ephemeral",
"pid file": "/home/aloxaf/.codex/app-server-daemon/app-server.pid (missing)",
"settings": "/home/aloxaf/.codex/app-server-daemon/settings.json (missing)",
"status": "not running",
"update-loop pid file": "/home/aloxaf/.codex/app-server-daemon/app-server-updater.pid (missing)"
},
"remediation": null,
"durationMs": 0
},
"auth.credentials": {
"id": "auth.credentials",
"category": "auth",
"status": "ok",
"summary": "auth is configured",
"details": {
"auth file": "/home/aloxaf/.codex/auth.json",
"auth storage mode": "File",
"stored API key": "false",
"stored ChatGPT tokens": "true",
"stored agent identity": "false",
"stored auth mode": "chatgpt"
},
"remediation": null,
"durationMs": 0
},
"config.load": {
"id": "config.load",
"category": "config",
"status": "ok",
"summary": "config loaded",
"details": {
"CODEX_HOME": "/home/aloxaf/.codex",
"config.toml": "/home/aloxaf/.codex/config.toml",
"config.toml parse": "ok",
"cwd": "/home/aloxaf/Coding/Rust/codex",
"enabled feature flags": "shell_tool, unified_exec, shell_snapshot, code_mode_host, terminal_resize_reflow, sqlite, hooks, enable_request_compression, network_proxy, multi_agent, tool_search_always_defer_mcp_tools, tool_suggest, plugins, in_app_browser, in_app_updates, browser_use, browser_use_full_cdp_access, browser_use_external, computer_use, remote_plugin, plugin_sharing, image_generation, resize_all_images, item_ids, skill_mcp_dependency_install, skill_search, mentions_v2, steer, guardian_approval, goals, collaboration_modes, tool_call_mcp_elicitation, auth_elicitation, personality, fast_mode, tui_app_server, remote_compaction_v2, workspace_dependencies",
"feature flag overrides": "network_proxy=true, apps=false",
"feature flags enabled": "38",
"log dir": "/home/aloxaf/.codex/log",
"mcp servers": "0",
"model": "gpt-5.6-terra",
"model provider": "openai",
"sqlite home": "/home/aloxaf/.codex"
},
"remediation": null,
"durationMs": 0
},
"git.environment": {
"id": "git.environment",
"category": "git",
"status": "ok",
"summary": "git version 2.55.0",
"details": {
".git entry": "directory",
"PATH git #1": "/usr/bin/git",
"PATH git entries": "1",
"git branch": "main",
"git build options": "git version 2.55.0; cpu: x86_64; built from commit: e9019fcafe0040228b8631c30f97ae1adb61bcdc; sizeof-long: 8; sizeof-size_t: 8; shell-path: /bin/sh; rust: enabled; feature: fsmonitor--daemon; gettext: enabled; libcurl: 8.21.0; OpenSSL: OpenSSL 3.6.3 9 Jun 2026; zlib-ng: 2.3.3; SHA-1: SHA1_DC; SHA-256: SHA256_BLK; default-ref-format: files; default-hash: sha1",
"git exec path": "/usr/lib/git-core",
"git version": "git version 2.55.0",
"repo detected": "true",
"repo root": "/home/aloxaf/Coding/Rust/codex",
"selected git": "/usr/bin/git"
},
"remediation": null,
"durationMs": 54
},
"installation": {
"id": "installation",
"category": "install",
"status": "ok",
"summary": "installation looks consistent",
"details": {
"PATH codex #1": "/usr/bin/codex",
"current executable": "/usr/bin/codex",
"install context": "other",
"managed by bun": "false",
"managed by npm": "false",
"managed by pnpm": "false",
"managed package root": "not set"
},
"remediation": null,
"durationMs": 0
},
"mcp.config": {
"id": "mcp.config",
"category": "mcp",
"status": "ok",
"summary": "no MCP servers configured",
"details": {},
"remediation": null,
"durationMs": 0
},
"network.env": {
"id": "network.env",
"category": "network",
"status": "ok",
"summary": "network-related environment looks readable",
"details": {
"proxy env vars": "none"
},
"remediation": null,
"durationMs": 0
},
"network.provider_reachability": {
"id": "network.provider_reachability",
"category": "reachability",
"status": "ok",
"summary": "active provider endpoints are reachable over HTTP",
"details": {
"ChatGPT base URL": "https://chatgpt.com/backend-api/ reachable (HTTP 403)",
"reachability mode": "ChatGPT auth"
},
"remediation": null,
"durationMs": 802
},
"network.websocket_reachability": {
"id": "network.websocket_reachability",
"category": "websocket",
"status": "ok",
"summary": "Responses WebSocket handshake succeeded",
"details": {
"DNS": "1 IPv4, 0 IPv6, first IPv4",
"auth mode": "chatgpt",
"connect timeout": "15000 ms",
"endpoint": "wss://chatgpt.com/backend-api/<redacted>",
"handshake result": "HTTP 101 Switching Protocols",
"model provider": "openai",
"models etag present": "true",
"provider name": "OpenAI",
"proxy env vars": "none",
"reasoning header": "false",
"server model present": "false",
"supports websockets": "true",
"wire API": "responses"
},
"remediation": null,
"durationMs": 1303
},
"runtime.provenance": {
"id": "runtime.provenance",
"category": "runtime",
"status": "ok",
"summary": "running local build on linux-x86_64",
"details": {
"commit": "unknown",
"current executable": "/usr/bin/codex",
"install method": "other",
"platform": "linux-x86_64",
"version": "0.146.0"
},
"remediation": null,
"durationMs": 0
},
"runtime.search": {
"id": "runtime.search",
"category": "search",
"status": "ok",
"summary": "search is OK (system)",
"details": {
"search command": "rg",
"search command readiness": "ripgrep 15.2.0",
"search provider": "system"
},
"remediation": null,
"durationMs": 1
},
"sandbox.helpers": {
"id": "sandbox.helpers",
"category": "sandbox",
"status": "ok",
"summary": "sandbox configuration is readable",
"details": {
"approval policy": "OnRequest",
"codex-linux-sandbox helper": "/home/aloxaf/.codex/tmp/arg0/codex-arg0YPX8d9/codex-linux-sandbox",
"execve wrapper helper": "/home/aloxaf/.codex/tmp/arg0/codex-arg0YPX8d9/codex-execve-wrapper",
"filesystem sandbox": "restricted",
"network sandbox": "enabled"
},
"remediation": null,
"durationMs": 0
},
"state.paths": {
"id": "state.paths",
"category": "state",
"status": "ok",
"summary": "state paths and databases are inspectable",
"details": {
"CODEX_HOME": "/home/aloxaf/.codex (dir)",
"active rollout files": "2164 files, 1439770914 total bytes, 665328 average bytes",
"archived rollout files": "0 files, 0 total bytes, 0 average bytes",
"goals DB": "/home/aloxaf/.codex/goals_1.sqlite (file)",
"goals DB integrity": "ok",
"log DB": "/home/aloxaf/.codex/logs_2.sqlite (file)",
"log DB integrity": "ok",
"log dir": "/home/aloxaf/.codex/log (dir)",
"memories DB": "/home/aloxaf/.codex/memories_1.sqlite (file)",
"memories DB integrity": "ok",
"sqlite home": "/home/aloxaf/.codex (dir)",
"state DB": "/home/aloxaf/.codex/state_5.sqlite (file)",
"state DB integrity": "ok",
"thread history DB": "/home/aloxaf/.codex/thread_history_1.sqlite (missing)",
"thread history DB integrity": "skipped (missing)"
},
"remediation": null,
"durationMs": 754
},
"state.rollout_db_parity": {
"id": "state.rollout_db_parity",
"category": "threads",
"status": "ok",
"summary": "rollout files and state DB thread inventory agree",
"details": {
"default model provider": "openai",
"rollout DB active files": "2164",
"rollout DB active rows": "2164",
"rollout DB archive mismatches": "0",
"rollout DB archived files": "0",
"rollout DB archived rows": "0",
"rollout DB duplicate DB paths": "0",
"rollout DB duplicate rollout thread ids": "0",
"rollout DB malformed file names": "0",
"rollout DB missing active rows": "0",
"rollout DB missing archived rows": "0",
"rollout DB model providers": "openai=2164",
"rollout DB rows": "2164",
"rollout DB scan cap reached": "false",
"rollout DB scan errors": "0",
"rollout DB sources": "subagent:thread_spawn=1283, cli=554, subagent:other=307, subagent:review=17, exec=2, vscode=1",
"rollout DB stale rows": "0"
},
"remediation": null,
"durationMs": 376
},
"system.environment": {
"id": "system.environment",
"category": "system",
"status": "ok",
"summary": "OS language en-US",
"details": {
"EDITOR": "not set",
"LANG": "zh_CN.UTF-8",
"LC_ALL": "zh_CN.UTF-8",
"VISUAL": "not set",
"os": "Arch Linux Rolling Release [64-bit]",
"os language": "en-US",
"os type": "Arch Linux",
"os version": "Rolling Release"
},
"remediation": null,
"durationMs": 17
},
"terminal.env": {
"id": "terminal.env",
"category": "terminal",
"status": "ok",
"summary": "terminal metadata was detected",
"details": {
"COLORTERM": "truecolor",
"DISPLAY": "present",
"TERM": "alacritty",
"WAYLAND_DISPLAY": "present",
"color output": "enabled",
"effective locale": "zh_CN.UTF-8",
"multiplexer": "tmux 3.7b",
"stderr is terminal": "true",
"stdin is terminal": "true",
"stdout is terminal": "true",
"terminal": "unknown",
"terminal size": "221x33",
"tmux allow-passthrough": "on",
"tmux client termname": "alacritty",
"tmux extended-keys": "off",
"tmux focus-events": "on",
"tmux set-clipboard": "on",
"tmux xterm-keys": "on"
},
"remediation": null,
"durationMs": 26
},
"terminal.title": {
"id": "terminal.title",
"category": "title",
"status": "ok",
"summary": "terminal title default",
"details": {
"terminal title activity": "true",
"terminal title items": "activity, project-name",
"terminal title project source": "git repo root",
"terminal title project value": "codex",
"terminal title source": "default"
},
"remediation": null,
"durationMs": 0
},
"updates.status": {
"id": "updates.status",
"category": "updates",
"status": "ok",
"summary": "update configuration is locally consistent",
"details": {
"cached latest version": "0.146.0",
"check for update on startup": "true",
"last checked at": "2026-08-01T03:03:15.893706712Z",
"latest version": "0.146.0",
"latest version status": "current version is not older",
"update action": "manual or unknown",
"version cache": "/home/aloxaf/.codex/version.json"
},
"remediation": null,
"durationMs": 1932
}
}
}What issue are you seeing?
When Codex creates a shell snapshot for zsh, snapshot validation fails if the zsh option KSH_OPTION_PRINT is enabled:
ERROR codex_core::shell_snapshot: Shell snapshot validation failed:
Snapshot command exited with status exit status: 1:
.../shell_snapshots/<session-id>.tmp-...:setopt:21268: no such option: offWith KSH_OPTION_PRINT enabled, setopt outputs every option followed by on or off. Codex currently prefixes each complete line with setopt, producing invalid snapshot lines such as:
setopt noaliases offzsh then interprets off as an option name during snapshot validation.
What steps can reproduce the bug?
- Enable KSH_OPTION_PRINT in .zshrc:
setopt ksh_option_print- Run Codex with shell snapshots enabled:
codex exec \
--ephemeral \
--sandbox read-only \
'Just run `pwd` and return'- Observe the shell snapshot validation error
What is the expected behavior?
Codex should successfully create and validate the zsh shell snapshot regardless of whether KSH_OPTION_PRINT is enabled.
Additional information
❯ setopt no_ksh_option_print; setopt | head -n5
autocd
autopushd
nobanghist
nobeep
completeinword
❯ setopt ksh_option_print; setopt | head -n5
noaliases off
aliasfuncdef off
allexport off
noalwayslastprompt off
alwaystoend off
1 Comment
I reproduced this against current
main(ee0247f95) with zsh 5.9 in a clean Alpine container, including by running the currentzsh_snapshot_script()with a temporaryZDOTDIR/.zshrcthat enablesKSH_OPTION_PRINT.The full reproduction generated 182 lines of the form:
and the existing validator (
set -e; . snapshot) exited 1 withno such option: off. An option-only minimal reproduction fails the same way, so functions, aliases, exports, tmux, and the reporter's Arch-specific environment are not required.The root cause appears bounded to the option serialization in
codex-rs/core/src/shell_snapshot.rs: the snapshot script assumessetoptalways emits one enabled option name per line. WithKSH_OPTION_PRINT, zsh instead emits every option plus anon/offstatus, and blindly prefixing each line withsetoptturns the status into a second option argument.A small repair would normalize both output shapes to the enabled-option list before counting and emitting commands, for example:
I also checked the green side of that approach: the normalized snapshot validates successfully under the same zsh validator and restores
KSH_OPTION_PRINTitself.The regression test shape I would suggest is:
ZDOTDIR/.zshrccontainingsetopt ksh_option_print.zsh -funderset -e.KSH_OPTION_PRINTis restored, no emitted command contains a trailingon/off, and the header count matches the emittedsetoptcommands.If this repair direction matches the intended behavior, would maintainers be open to a focused PR with the regression test?