Broker process not cleaned up on session exit — no idle timeout

[NewAiCoder]

Bug

The Codex companion app-server broker process (app-server-broker.mjs) persists indefinitely after the Claude Code session that spawned it exits. Found a stale broker (3 processes, ~185 MB) running 5+ hours after the originating session ended.

Root Cause

The plugin has a well-implemented session-lifecycle-hook.mjs with handleSessionEnd() that sends broker/shutdown — but this hook doesn't appear to fire reliably. The broker itself has no idle timeout — it only shuts down upon receiving an explicit broker/shutdown RPC or SIGTERM/SIGINT.

When the session-end hook fails to fire (or the session crashes/is killed), the broker runs forever.

Suggested Fix

Add an idle timeout to app-server-broker.mjs as a defensive fallback. If no RPC messages are received for N minutes (e.g., 15-30), the broker should self-terminate. This complements the existing session-end hook rather than replacing it.

The lifecycle hook approach is correct, but defense-in-depth with an idle timeout would prevent orphaned brokers when the hook doesn't fire.

Environment

• Ubuntu 22.04, Claude Code CLI
• @openai/codex-plugin-cc v1.0.2
• Broker was spawned for intake-portal project, outlived the session by 5+ hours

Workaround

Manually killing the broker processes after session exit.

[NewAiCoder]

Local fix applied

Added a 15-minute idle timeout to app-server-broker.mjs. The timer resets on every incoming socket data (any RPC activity) and calls the existing shutdown() for clean teardown.

+const IDLE_TIMEOUT_MS = Number(process.env.CODEX_BROKER_IDLE_TIMEOUT_MS) || 15 * 60 * 1000;
+let idleTimer = null;
+
+function resetIdleTimer(shutdownFn) {
+  if (idleTimer) clearTimeout(idleTimer);
+  idleTimer = setTimeout(async () => {
+    process.stderr.write(`Broker idle for ${IDLE_TIMEOUT_MS / 1000}s with no RPC activity, self-terminating.\n`);
+    await shutdownFn();
+    process.exit(0);
+  }, IDLE_TIMEOUT_MS);
+  idleTimer.unref();
+}

 // Before server creation:
+  resetIdleTimer(() => shutdown(server));

 // First line inside socket "data" handler:
+      resetIdleTimer(() => shutdown(server));

• Configurable via CODEX_BROKER_IDLE_TIMEOUT_MS env var
• .unref() ensures the timer doesn't prevent normal exit
• Uses existing shutdown() for clean teardown (sockets, pid file, unix socket)

Happy to submit a PR.