Bug: Claude child processes not reaped after query completion (single-user mode)

[akuehner]

Summary

In Clay v2.23.0 single-user mode (no osUsers), each sdk.query() call spawns a claude child process via the Claude Agent SDK. After the query stream completes, the process is never terminated — it remains as a child of the daemon indefinitely. Over normal usage this leads to dozens of orphaned claude processes consuming gigabytes of RAM.

Environment

• Clay v2.23.0, Agent SDK v0.2.92
• Linux (systemd service), single-user mode, no osUsers
• Daemon running as root

Observed Behavior

After ~24 hours of normal usage:

• 35 orphaned claude processes (all children of daemon PID)
• ~7.8 GB RSS consumed
• All orphans had exactly 2 file descriptors (base stdio sockets only — no active client connections)
• Only the 3 sessions with active WebSocket clients had 3-4 FDs

Root Cause Analysis

In sdk-bridge.js, the in-process query path (startQuery(), used when linuxUser is null):

1. sdk.query() is called at line ~1767, spawning a claude child process via the Agent SDK
2. processQueryStream() iterates the async iterable (for await ... of session.queryInstance)
3. When the stream ends, the finally block (line ~1594) sets session.queryInstance = null but never calls .close() or [Symbol.dispose]() on the query object

Compare this to the worker path (startQueryViaWorker()), which properly calls cleanupSessionWorker() → worker.kill() → sends "shutdown" + SIGKILL after 3s. The in-process path has no equivalent cleanup.

Suggested Fix

In processQueryStream()'s finally block, before nulling queryInstance, explicitly close/dispose it:

// In the finally block of processQueryStream():
if (session.queryInstance) {
  // Close the SDK query to terminate the underlying claude process
  if (typeof session.queryInstance.close === 'function') {
    try { session.queryInstance.close(); } catch (e) {}
  } else if (typeof session.queryInstance[Symbol.dispose] === 'function') {
    try { session.queryInstance[Symbol.dispose](); } catch (e) {}
  }
}
session.queryInstance = null;

Additionally, deleteSession() and deleteSessionQuiet() in sessions.js should also ensure any active query's process is killed (they currently only call abortController.abort() and messageQueue.end(), which don't terminate the child process).

Workaround

Manually kill orphaned processes:

# Find claude processes with only 2 sockets (orphaned, no active client)
for pid in $(ps -eo pid,cmd --no-headers | grep 'claude$' | awk '{print $1}'); do
  sockets=$(ls -la /proc/$pid/fd 2>/dev/null | grep -c socket)
  if [ "$sockets" -le 2 ]; then
    kill -TERM $pid
  fi
done

Impact

On a machine with 8 GB RAM, this exhausted available memory within ~24 hours of normal usage, likely degrading performance of all sessions.

[chadbyte]

This has been fixed. The root cause was exactly as you identified: processQueryStream() was never closing the SDK query object after the stream ended, leaving claude child processes alive indefinitely. We now explicitly call .close() / [Symbol.dispose]() in the finally block, and also added cleanup in deleteSession() to kill any lingering child processes.

To update:

npx clay-server@latest

Thanks for the incredibly thorough analysis, the root cause breakdown and the FD-based workaround were really impressive.

By the way, you've reported quite a few issues at this point (all excellent quality). Just curious if you don't mind sharing: how are you mainly using Clay? And if Clay didn't exist, is there another tool you think you'd reach for instead? It would really help us figure out where to focus development going forward.

[akuehner]

Thanks for the quick fix — confirmed working on v2.24.2.

For context on how I'm using Clay: multiple sessions across multiple projects simultaneously, jumping between desktop and mobile with always-on VPN. If Clay didn't exist I'd be looking for an alternative or building my own — Claude Code's native remote session functionality doesn't come close to covering this workflow, so it was a non-starter.

One other thing I noticed while on v2.23.0 — when a hook breaks, the UI goes silent rather than surfacing the error. Opened a separate issue here: #270

[chadbyte]

Confirmed, thanks! Great to hear it's working on v2.24.2.

Really appreciate the context on your workflow. Multi-project, multi-session with desktop/mobile switching is exactly the kind of use case we want to nail down, so this is super helpful.

We've noted #270 and will be working through the open issues. Thanks again for the consistently excellent reports.