[DOCS] Agent view docs do not describe control-socket startup failure keeping the supervisor unreachable (fixed in v2.1.195)

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/agent-view

Section/Topic

The "Supervisor process" section, specifically the claude daemon status description and the troubleshooting bullet that says "If attaching, peeking, or claude logs reports that the background service did not respond, the supervisor process has likely stalled". The current text does not address the v2.1.195 fix where the supervisor can stay reachable but fail to start its control socket, blocking restarts.

Current Documentation

The supervisor section currently says:

To inspect this state without reading the files directly, run claude daemon status. It reports whether the supervisor is reachable, its process ID and version, the socket directory, and how many background sessions are live. /doctor includes a summary of the same check.

And later, for the stalled-supervisor case:

If attaching, peeking, or claude logs reports that the background service did not respond, the supervisor process has likely stalled. Stop it and let the next claude agents start a fresh one. To keep your background sessions running through the restart, pass --keep-workers: `` claude daemon stop --any ``

Neither description distinguishes between a supervisor whose process is up but whose control socket has not started, and a supervisor that has stalled entirely.

What's Wrong or Missing?

Claude Code v2.1.195 fixed an issue where the background-agent supervisor could be running and reachable but fail to start its control socket, leaving it unreachable from claude agents, claude attach, and claude respawn. Before the fix, the control-socket startup was a single point of failure: if it failed, the supervisor stayed alive but blocked every restart path that needed to talk to it, including the auto-restart after a binary upgrade.

After the fix, a failed control-socket startup no longer pins the supervisor in an unreachable state. The docs do not say so, and users hitting "supervisor reachable, socket not started" symptoms currently have no doc-level signal that the v2.1.195 fix has changed the recovery path.

Suggested Improvement

Update the claude daemon status description to mention the control socket explicitly:

To inspect this state without reading the files directly, run claude daemon status. It reports whether the supervisor is reachable, whether its control socket has started, its process ID and version, the socket directory, and how many background sessions are live. /doctor includes a summary of the same check. Claude Code v2.1.195 fixes a case where the supervisor was reachable but its control socket failed to start, blocking restarts; claude daemon status now reports the control-socket state separately.

Update the stalled-supervisor paragraph to mention the new failure mode:

If attaching, peeking, or claude logs reports that the background service did not respond, the supervisor process has likely stalled, or its control socket has failed to start. Claude Code v2.1.195 fixes the control-socket case so the next claude agents starts a fresh supervisor instead of pinning the existing one in an unreachable state. To keep your background sessions running through the restart, pass --keep-workers: `` claude daemon stop --any ``

Impact

Medium - Makes feature difficult to understand

Additional Context

The supervisor section's troubleshooting bullet is the only place that mentions what to do when "the background service did not respond". The control-socket failure mode is the same shape from the user's perspective (no response from claude attach/logs/agents) but the recovery path differs: a stalled supervisor needs claude daemon stop --any, while a control-socket failure now recovers automatically on the next claude agents. The fix is already in v2.1.195; the docs just need to mention the new behavior.

Affected Pages:
| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/agent-view | "Supervisor process" section, claude daemon status description, and stalled-supervisor recovery paragraph |

Total scope: 1 page affected