Gnaroshi
EN한국어
← Back to Projects
codex-unlock-stale application role
Application

codex-unlock-stale

The utility keeps the newest recognized VS Code Remote extension host and terminates only older duplicates that can retain a Codex conversation writer lock.

Usable locallyCLI
codex-unlock-stale dry run keeping the newest extension host and identifying one stale duplicate.
Inspect the exact keep and stale decision before changing a process.Process IDs, ages, and child commands are synthetic demo data; no conversation data was read.

At a glance

For
People using Codex through VS Code Remote SSH on a Linux host
Primary use
Inspect duplicate Codex app servers and release a stale conversation writer lock without editing session files.
Product status
Usable locally
Platforms
CLI

Overview

Laptop sleep and network changes can leave an older Remote SSH extension host running beside the current one. This narrow Bash utility makes that duplicate visible and provides a guarded cleanup path.

Example workflow

Example recovery

Inspect two synthetic extension hosts, preserve possible active work, and release only the stale lock.

  1. Inspect first

    Run the dry-run path and confirm which extension host would be kept.

  2. Protect active work

    Stop automatically when the stale host still has a non-helper command child.

    codex-unlock-stale refusing to terminate a host with a synthetic active command child.
    Stop when a stale host may still own active work. Process IDs, ages, and child commands are synthetic demo data; no conversation data was read.

  3. Release the lock

    After the child is gone, terminate only the stale extension host and verify one current app server remains.

    codex-unlock-stale terminating only the stale extension host and preserving session files.
    Release the stale lock without modifying conversation files. Process IDs, ages, and child commands are synthetic demo data; no conversation data was read.

Key features

  • Dry-run process inspection
  • Newest-host preservation
  • Active-child safety stop
  • SIGTERM-first cleanup
  • No conversation-file access

Data and privacy

The script reads process metadata only. It never reads, edits, moves, or deletes ~/.codex conversation files; the approved terminal evidence uses synthetic process data.

Tech stack

Languages

  • Shell

Runtime

  • Linux

Integrations

  • VS Code Remote SSH

Technology icons are repository-owned category symbols; the verified technology name remains visible.

Studio relationship

No Studio integration is planned; the utility is intentionally a standalone terminal recovery command.

Current state

Version 0.1.0 is public and usable from a Linux shell after a VS Code Remote SSH reconnect.

Current limitations

  • The process matcher targets the current OpenAI VS Code extension path and may need updates if that layout changes.
  • It is a recovery utility, not an official OpenAI-supported repair path.

Technical notes

  • Bash coordinates process inspection and guarded signals.
  • Linux ps supplies parent, age, and command metadata.
  • The matcher recognizes VS Code Remote extension hosts and the Codex app-server path.

Next milestones

  • Keep the matcher covered as extension layouts change.
  • Add verified reports for other Linux remote environments when available.

Technical facts

Source provenance
Gnaroshi/codex-unlock-stale
Source commit
2a3485ba5168
Studio integration
Not planned
Content reviewed
Aug 26, 2026