python3 ~/.local/share/adom/codex/runtime/manage.py status
adom-codex-runtime --runtime-status
adom-wiki pkg uninstall adom/codex

# Codex reload integration

This integration belongs to the optional `adom/codex` wiki package. Installing
`adom/core`, Hydrogen, or the upstream Codex VSIX alone does not enable it.
Install with `adom-wiki pkg install adom/codex` in each container where it is wanted.
It applies to that Linux user's code-server installation in that container.

## What installation changes

- Configures `chatgpt.cliExecutable` to the package's JSONL/WebSocket adapter.
  Existing custom CLI choices are preserved: installation reports that the
  runtime integration was skipped instead of replacing them.
- Keeps one detached native Codex app-server for each effective `CODEX_HOME`.
  Reloaded extension hosts reconnect to it; closing a frontend does not stop
  an active turn. Approvals or other interactions still need a connected UI.
- Changes the renderer startup watchdog to run only while a restored editor
  tab is visible. Hidden tabs have no renderer yet; counting those 30 seconds
  was replacing their contents with “Codex could not start.” Visible tabs keep
  the upstream timeout and its real failure reporting.
- Removes the scroll fade only from the editable composer. Conversation and
  menu scrolling keep their existing appearance.

No model preferences, authentication files, Hydrogen source, shared Adom
bootstrap, or fleet-wide settings are changed. Python WebSocket dependencies
are bundled; installation does not use system pip or download a Codex binary.
The initial transition from a legacy stdio backend requires finishing its
work and closing its old editor connection; in-flight legacy turns cannot be
transferred into a different process.

## When the upstream extension updates

The official VSIX store still installs upstream updates. A package-owned
watcher checks the container's extension directories every five seconds and
reapplies the UI fixes to recognized startup code. A user crontab entry starts
the watcher after container boot and recovers it if it exits. Both entries
are owned and removed by this package. No other users or containers are enrolled.

The adapter selects the native binary belonging to the extension that launched
it, using the bin directory that extension appends to the child process PATH.
It does not select whichever downloaded extension has the highest version.
The normal extension-host reload activates the updated UI fixes. If activation
beats the watcher, a subsequent editor reload is needed; the watcher does not
force reloads or cancel work.

A changed binary starts only after all old adapter connections have closed and
the backend reports that every loaded thread is idle. A newer extension can
connect to the older backend while work continues when their complete generated
app-server JSON schemas (including experimental APIs) match exactly. Compatibility
is not inferred from the extension version or CLI major version. Schema hashes
are cached by executable identity, and new backends retain their schema hash so
removing an old VSIX does not invalidate the attestation.

`adom-codex-runtime --runtime-status` exposes a deferred `upgrade` record, including
the requested/running binary and whether connected views or backend work delayed
replacement. The next connection upgrades once all other views have closed and
the backend is authoritatively idle. The watcher does not proactively swap it.
Unknown/different protocols retain the conservative gate; downgrades, startup
option changes and unrecognized socket owners remain refused. No active turn is
interrupted. Unrecognized upstream renderer code is left intact
and reported as unsupported in integration status; it needs a package update.

Ordinary panel reloads use the existing backend immediately. This is not
persistence across container shutdown, WSL termination, or a service manager
killing the backend's entire process group/cgroup.

## Status and removal

```
python3 ~/.local/share/adom/codex/runtime/manage.py status
adom-codex-runtime --runtime-status
adom-wiki pkg uninstall adom/codex
```

Uninstall disables reconciliation, removes its cron entries, removes only the
managed CSS/JavaScript fragments and restores the previous CLI setting if the
user has not since changed it. It preserves unrelated settings and comments.
Package runtime files and any working backend are retained so uninstall cannot
interrupt a turn. After work finishes, close the old Codex views before returning
to upstream. New connections use the restored CLI setting. Runtime files can
be removed after those processes exit; credentials and conversations remain.

Installed state is under `~/.local/state/adom/codex-integration`; backend state
is under `~/.local/state/adom/codex-runtime`. These are container-local paths.