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.
Requires macOS or Linux, Node.js 22.13+ (22.x) or 24.x, and lsof.
Windows and Node.js 26 are not supported.
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.
- 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.