Fail-closed diagnostics and safe recovery for Codex native thread writer locks.
Find a thread and inspect whether its writer is eligible for safe recovery:
Real macOS list/inspect output from v0.4.2, re-rendered with personal
identifiers redacted. The live lock owner is not safe to unlock; no session is
terminated in this demo.
codex-unlock list
codex-unlock inspect <thread-id>
Replace <thread-id> with a UUID from list. Add --json for structured output.
For an eligible completed session, codex-unlock unlock <thread-id> requests
recovery only when every safety check passes.
The stable npm CLI requires macOS or Linux, Node.js 22.13+ (22.x) or 24.x, and lsof.
That CLI does not support Windows or Node.js 26.
list and inspect do not change the contents of Codex's native lock or
transcript files, though each probe briefly takes Codex's coordination lock.
An interactive command may separately refresh codex-unlock's advisory update
cache after printing the primary result; see update behavior.
unlock sends SIGTERM only after revalidation confirms that exactly one
same-user Codex process owns the target lock. That process must hold exactly one
thread lock, and its stable transcript must end in task_complete. Shared
app-server, Remote Control, daemon, and uncertain owners are refused. unlock
never deletes native lock files, forces an unlock, or sends SIGKILL. See the
safety model.
npm install --global codex-unlock
codex-unlock --helpOr run without a retained global installation:
npx --yes codex-unlock@latest listcodex-unlock check-update
npm install --global codex-unlock@latestcheck-update checks the registry; it does not install anything.
Automatic notices are advisory only. See update behavior.
The separate Windows diagnostic-only channel uses tags windows-v<version>.
Release candidates are marked as prereleases. Consult
GitHub Releases for its
publication status and ZIP availability. Running the standalone ZIP's executable
requires no Node.js, Rust or lsof installation; npm installation remains the
macOS/Linux CLI.
The support scope is Windows 10 x64 on local NTFS, with a verified
Medium-integrity, non-elevated, non-AppContainer token. Windows 11 and Windows
Server are outside this qualified scope. Security-product and Codex-mode
coverage is recorded in the platform guide; it does not cover every configuration.
There is no Windows unlock or recovery, a supplied
PID does not establish the lock holder, and safeToUnlock is always false.
See Windows scope and download guidance.
- CLI reference — commands, safety, options, exit codes, and source installation
- JSON v1 and TypeScript types — the supported automation contract
- Platform support — verified OS, architecture, and Node combinations
- Safety race coverage and update security
- v0.2 migration — historical integration baseline
- Contributing and maintainer releases
- Upstream handoff proposal — design only, not an implemented fallback
MIT.
For questions and non-sensitive bugs, use GitHub Issues. Report vulnerabilities privately using the security policy. Redact local paths, process arguments, thread IDs, transcripts, and credentials before sharing diagnostics; never post unredacted JSON output.