[DOCS] Background daemon auto-upgrade failure now preserves running sessions instead of killing them silently (v2.1.203)

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

"The supervisor process" section in agent-view.md (around the claude daemon status description and the paragraph that begins "The supervisor watches the installed Claude Code binary on disk…"), and the matching agent-view.md Version history table at the bottom of the page.

Current Documentation

agent-view.md describes the supervisor's interaction with the auto-updater only in terms of the happy path. The current text says:

The supervisor watches the installed Claude Code binary on disk and restarts into the new version after the regular auto-updater replaces it. This is a local file watch, not a network check. Background sessions are detached processes, so they keep running through the restart and the new supervisor reconnects to them. An idle pinned session is also restarted in place onto the new version so it picks up the update without you reattaching.

The Version history table at the bottom of the page also has no row that mentions daemon auto-upgrade failure behavior.

What's Wrong or Missing?

The current paragraph in "The supervisor process" implies the only auto-update scenario is the success path: the binary changes on disk, the supervisor restarts, and detached background sessions keep running. It never addresses what happens when the auto-updater fails to replace the binary or leaves the supervisor in a transitional state, and it never mentions that v2.1.203 made that failure mode recoverable.

A. The v2.1.203 fix is not reflected in the supervisor section

The v2.1.203 changelog records:

Fixed a background daemon auto-upgrade failure silently killing all running background sessions

Before v2.1.203, when a background daemon auto-upgrade failed (for example, when the on-disk binary could not be replaced or the restart into the new version did not complete), the supervisor path was killing every running background session without a clear, user-visible cause. After v2.1.203, a failed auto-upgrade no longer silently takes down running background sessions.

agent-view.md is the canonical page where a user learns how the supervisor interacts with the auto-updater. The current paragraph describes only the success case and never acknowledges the failure mode. As a result:

• A user upgrading to v2.1.203 has no docs entry explaining that an auto-upgrade that fails will no longer silently terminate their sessions.
• A user on a pre-v2.1.203 version who lost all background sessions after an auto-upgrade has no docs entry describing that failure mode or how to recover.
• Operators debugging a "where did my background sessions go?" question after an auto-update miss have no docs entry to point them at.

B. The Version history table does not include a v2.1.203 row for this fix

The Version history table at the bottom of agent-view.md is the place where other supervisor fixes are recorded (for example, the v2.1.199 row about low-memory exit reasons and the v2.1.200 row about roster.json field preservation). The v2.1.203 auto-upgrade fix has no row there, even though it changes the same supervisor-process surface.

Suggested Improvement

A. Extend the supervisor paragraph in agent-view.md

Add a short clause after the existing "Background sessions are detached processes, so they keep running through the restart and the new supervisor reconnects to them" sentence, for example:

When the auto-upgrade does not finish replacing the binary, the supervisor keeps the existing background sessions running instead of terminating them. The next successful upgrade or a manual claude daemon stop --any picks up the new version. Before v2.1.203, a failed daemon auto-upgrade silently killed every running background session.

B. Add a v2.1.203 row to the Version history table

Add the v2.1.203 entry in the same shape as the existing v2.1.199 and v2.1.200 rows, for example:

| v2.1.203 | {/* min-version: 2.1.203 */}A failed background daemon auto-upgrade no longer silently kills every running background session; the supervisor keeps the existing sessions running until the next successful upgrade or a manual claude daemon stop --any. |

C. Optional: surface the recovery path in the Troubleshooting section

The Troubleshooting section already covers supervisor stalls via claude daemon stop --any. A short cross-reference note in the same area, pointing readers to that command when an auto-upgrade fails to land, would close the loop without duplicating the existing stall guidance.

Impact

Medium - Makes feature difficult to understand

Additional Context

The current agent-view.md paragraph describes the supervisor's auto-upgrade interaction as a single sentence about detached processes, which works only when the upgrade succeeds. The v2.1.203 changelog entry does not yet appear in the public changelog at https://code.claude.com/docs/en/changelog, and the agent-view page does not yet include a v2.1.203 row.

A successful run of claude daemon status after a failed auto-upgrade should not show the background sessions as gone, and that is the user-visible change. The docs should describe that change in the supervisor section and record it in the page's version history.

Affected Pages:
| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/agent-view | "The supervisor process" section (~line 529) and the Version history table at the end of the page | Supervisor paragraph describes only the auto-upgrade success path; no v2.1.203 row exists |

Total scope: 1 page affected.

Related but distinct issues that already have open issues:

• v2.1.200 build-recency handover rule (open issue in the prefetched queue).
• v2.1.196 long-running command survival across process restarts (open issue in the prefetched queue).

Neither covers the v2.1.203 "auto-upgrade failure silently killed sessions" scenario, which is what this draft reports.