`sendBrokerShutdown` has no timeout — SessionEnd hook can hang indefinitely

[SmidaOps]

Summary

sendBrokerShutdown in plugins/codex/scripts/lib/broker-lifecycle.mjs awaits a Promise that resolves only on socket data, error, or close events. If the broker accepts the connection but stops responding mid-RPC (no data, no error, no close), the Promise never resolves and the SessionEnd hook hangs indefinitely.

Affected code

plugins/codex/scripts/lib/broker-lifecycle.mjs:43-57 (v1.0.3)

export async function sendBrokerShutdown(endpoint) {
  await new Promise((resolve) => {
    const socket = connectToEndpoint(endpoint);
    socket.setEncoding("utf8");
    socket.on("connect", () => {
      socket.write(`${JSON.stringify({ id: 1, method: "broker/shutdown", params: {} })}\n`);
    });
    socket.on("data", () => {
      socket.end();
      resolve();
    });
    socket.on("error", resolve);
    socket.on("close", resolve);
  });
}

Asymmetry with startup path

waitForBrokerEndpoint in the same file (line 24) explicitly takes timeoutMs = 2000 and bounds its wait loop. Startup path is timed; shutdown path isn't. Same module — looks like an oversight rather than intent.

Observed symptoms

Running Claude Code in unattended (cron/launchd) invocations on macOS:

• Multiple sessions hung at SessionEnd after content rendered cleanly. One held its lock 19.5 hours before something external (a new Claude Code session creating a fresh broker socket) unwedged it.
• In a separate session the harness's hook timeout fired with Hook cancelled and exit 1 — content was already delivered, but the misleading exit code surfaced as a failure in launchd telemetry.
• Correlation suggests macOS DarkWake during long-running SSE streams wedges the broker. We mitigated with caffeinate -ims on the wrapper, but the shutdown await still hangs when a wedge does happen.

Proposed fix

Mirror the timeout pattern used in waitForBrokerEndpoint:

export async function sendBrokerShutdown(endpoint, timeoutMs = 5000) {
  await new Promise((resolve) => {
    const socket = connectToEndpoint(endpoint);
    let settled = false;
    const finish = () => {
      if (settled) return;
      settled = true;
      clearTimeout(timer);
      try { socket.destroy(); } catch {}
      resolve();
    };
    const timer = setTimeout(finish, timeoutMs);
    socket.setEncoding("utf8");
    socket.on("connect", () => {
      socket.write(`${JSON.stringify({ id: 1, method: "broker/shutdown", params: {} })}\n`);
    });
    socket.on("data", finish);
    socket.on("error", finish);
    socket.on("close", finish);
  });
}

5s is generous for a local socket RPC and can be tuned. Caller in session-lifecycle-hook.mjs:99 requires no change.

Environment

• Plugin: @openai/codex-plugin-cc v1.0.3
• Platform: macOS Darwin 25.4 (arm64)
• Node: >= 18.18 (per engines)
• Trigger: launchd-scheduled claude --agent ... -p ... --permission-mode bypassPermissions heartbeat invocations

[dhruvac29]

I opened a PR for this: #300

The fix adds a bounded timeout to sendBrokerShutdown(endpoint, timeoutMs = 5000) and uses a guarded cleanup path for data, error, close, and timeout.

I also added a regression test that simulates the reported failure mode: a broker accepts the socket connection, receives broker/shutdown, but never replies or closes the socket.

Validation passed locally:

node --test tests/broker-lifecycle.test.mjs
npm test

Full suite: 87 passed, 0 failed.

[Pelton]

Same observation on macOS (Claude Code with codex@openai-codex v1.0.4). The silent-resolve on socket error/close in sendBrokerShutdown means SessionEnd can't be relied on for cleanup — that's what produces the orphan tree we see (node codex app-server plus Rust codex app-server reparented to launchd, persisting across sessions). Tracking PR #343 as the candidate fix.

[dhruvac29]

Thanks for the additional repro/details. I think this is related but not the same failure mode as #300.

#300 addresses the unbounded wait in sendBrokerShutdown: if the shutdown socket connects but never receives data, error, or close, SessionEnd can hang indefinitely. That PR adds a timeout and guarded socket cleanup for the shutdown RPC itself.

The orphaned codex app-server process case described here looks broader: stale broker/session cleanup needs to terminate the recorded broker process, which #343 appears to address.

So I see #300 and #343 as complementary:

• Fix broker shutdown hang on unresponsive socket #300: prevent SessionEnd from hanging forever during shutdown RPC
• fix(runtime): clean up stale brokers and lock state updates #343: clean up stale/orphaned broker processes and state races

Happy to rebase/resolve conflicts if #343 lands first.