Model catalog changes are not reflected in running Codex app-server until it is restarted

[firewine]

Summary

Changes to the OpenCodex model catalog are written correctly to disk, but an already-running Codex app-server continues using the previous model list until the app-server processes are terminated.

Restarting the OpenCodex proxy, running ocx sync, and running ocx sync-cache are not sufficient. Rebooting the machine appeared to fix the problem only because it terminated the persistent Codex app-server processes.

Environment

• Ubuntu, accessed over SSH
• tmux
• OpenCodex 2.7.40
• Codex CLI 0.145.0
• Bun 1.3.14
• Node.js v24.18.0
• OpenCodex systemd user service enabled

Reproduction

1. Start OpenCodex using the systemd user service.
2. Start Codex CLI and allow its background app-server processes to remain running.
3. Modify the OpenCodex model configuration. In this case, Anthropic should expose only:
   • anthropic/claude-fable-5
   • anthropic/claude-opus-5
   • anthropic/claude-sonnet-5
4. Run:

ocx service stop
ocx service start
ocx sync
ocx sync-cache

5. Verify the generated files:

grep -oE '"anthropic/[^"]+"' ~/.codex/opencodex-catalog.json | tr -d '"' | sort -u
grep -oE '"anthropic/[^"]+"' ~/.codex/models_cache.json | tr -d '"' | sort -u

Both files correctly contain only the three intended Anthropic models.

6. Codex still shows the previous/stale model list.
7. Check background processes:

pgrep -af 'codex|app-server'

Persistent processes include variants of:

codex ... app-server --listen unix://
codex app-server proxy
codex-code-mode-host

8. Terminate only the Codex app-server processes:

pkill -TERM -f 'codex.*app-server'
pkill -TERM -f 'codex-code-mode-host'

After Codex recreates/restarts these processes, the new model list is immediately reflected.

Actual behavior

ocx sync and ocx sync-cache update the catalog/cache files, but running Codex app-server processes continue serving the old in-memory model catalog.

The OpenCodex proxy itself is healthy and correctly restarted with a new PID. The issue is specifically the persistent Codex app-server processes.

Expected behavior

One of the following would be helpful:

1. Running Codex app-server processes reload the updated model catalog; or
2. ocx sync detects running Codex app-server processes and clearly warns that they must be restarted; or
3. Add an explicit safe option/command, for example:

ocx sync --restart-codex

or:

ocx codex reload-models

The command could update the catalog/cache, then send SIGTERM only to the current user's Codex app-server processes.

Important safety detail

A broad command such as pkill -f codex is unsafe because unrelated processes may contain codex in their command line, for example hermes-codex-bridge-mcp.

A targeted pattern such as the following worked in this environment:

pkill -TERM -f 'codex.*app-server'
pkill -TERM -f 'codex-code-mode-host'

It may also be preferable to avoid restarting automatically while a turn is active, or require an explicit flag/confirmation because restarting app-server can interrupt active work.

[github-actions]

Possibly related issues:

• [Bug]: Routed models are loaded by Codex app-server but missing from Desktop model picker #241

Reason: The new issue regarding the Codex app-server not reflecting model catalog changes until restarted relates to the existing issue on routed models not appearing in the model picker, as both are concerned with model visibility and refresh beha

Detected automatically via GitHub Models.

[firewine]

Suggested implementation

A practical interim solution would be an explicit command such as:

ocx sync --restart-codex

or:

ocx codex reload-models

The command should:

1. Run the existing catalog sync logic.
2. Run the existing cache invalidation logic.
3. Find only Codex app-server processes owned by the current user.
4. Send SIGTERM to those processes.
5. Avoid broad matching such as pkill -f codex because unrelated processes like hermes-codex-bridge-mcp may also match.
6. Warn that active turns may be interrupted, or require an explicit --force / --restart-codex flag.

A shell-level reference implementation that worked in this environment:

ocx-reload-models() {
    echo "[1/3] Syncing OpenCodex catalog"
    ocx sync || return 1
    ocx sync-cache || return 1

    echo "[2/3] Finding running Codex app-server processes"
    mapfile -t pids < <(
        pgrep -u "$UID" -f '[c]odex.*app-server'
    )

    if ((${#pids[@]} == 0)); then
        echo "No running Codex app-server found"
        return 0
    fi

    printf 'Stopping PID(s): %s\n' "${pids[*]}"
    kill -TERM "${pids[@]}"

    sleep 2

    echo "[3/3] Verifying"
    pgrep -u "$UID" -af '[c]odex.*app-server' \
        || echo "Codex app-server stopped"
}

A possible Bun/TypeScript helper could look like this:

function restartCodexAppServers(): number[] {
  const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
  if (uid === undefined) return [];

  const result = Bun.spawnSync({
    cmd: ["pgrep", "-u", String(uid), "-f", "[c]odex.*app-server"],
    stdout: "pipe",
    stderr: "pipe",
  });

  if (result.exitCode !== 0) return [];

  const pids = result.stdout
    .toString()
    .trim()
    .split(/\s+/)
    .map(Number)
    .filter((pid) => Number.isInteger(pid) && pid > 1);

  for (const pid of pids) {
    try {
      process.kill(pid, "SIGTERM");
    } catch (error) {
      console.warn(`Failed to stop Codex app-server PID ${pid}:`, error);
    }
  }

  return pids;
}

For extra safety, the implementation could inspect /proc/<pid>/cmdline before signaling and only accept command lines containing both codex and app-server. It may also be useful to wait for termination and report any surviving PIDs instead of escalating automatically to SIGKILL.

[Wibias]

This was generated by AI during triage.

Implementing the accepted approach from review:

1. Warn after ocx sync / ocx sync-cache when current-user Codex app-server / codex-code-mode-host processes are still running.
2. Opt-in restart via --restart-codex (targeted SIGTERM only; no broad pkill -f codex).
3. Docs + dashboard stale hint updated.

PR: will link shortly after open.

[Wibias]

PR: #518

[github-actions]