[DOCS] `claude attach` behavior during a background agent's auto-update restart is undocumented; v2.1.205 wait-instead-of-error fix is not reflected in the Attach or supervisor sections

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

• The "Attach to a session" subsection under "Monitor sessions with agent view" (around the paragraphs that begin "Press Enter or → on a selected row to attach" and "Attached sessions always render in [fullscreen mode]") — currently says nothing about what users see if they invoke claude attach <id> from the shell while the supervisor is mid-upgrade.
• The "The supervisor process" subsection (around the paragraph that begins "The supervisor watches the installed Claude Code binary on disk and restarts into the new version") — describes the happy path of the upgrade only.
• The "Version history" table at the bottom of agent-view.md, which currently does not include a v2.1.205 row.

Current Documentation

From agent-view.md, the "Attach to a session" subsection (around lines 177-201 of agent-view.md):

### Attach to a session Press Enter or → on a selected row to attach. Agent view is replaced by the full interactive session. When you attach, Claude posts a short recap of what happened while you were away. While attached, the session behaves like any other Claude Code session: every command, keyboard shortcut, and feature works. Attached sessions always render in fullscreen mode, regardless of your tui setting, because a background session has no terminal scrollback to append to. Scroll with PgUp, PgDn, or the mouse wheel, and press Ctrl+O for transcript mode. Your terminal's native scroll and tmux copy mode show only the current viewport, the same as when you run any fullscreen application. Press ← on an empty prompt, or run /exit, to detach and return to agent view. As of v2.1.198 this works the same way whether you opened the session from agent view or with claude attach <id> from your shell.

The "detach never stops a background session" sentence that follows lists ←, Ctrl+Z, /exit, and double Ctrl+C/Ctrl+D but says nothing about the v2.1.205 wait-during-upgrade behavior.

The "The supervisor process" subsection, around line 547 of agent-view.md, currently describes the auto-update path only as a successful handoff:

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 same page currently has no row for v2.1.205. The latest listed row is the v2.1.203 row that summarizes the gateway ANTHROPIC_BASE_URL, PATH, @-picker worktree, and other changes from that release.

The closest troubleshooting entry, "Agent view says the background service did not respond" (around line 614), still frames any unresponsive-attach symptom as a stalled supervisor and tells the user to run claude daemon stop --any --keep-workers:

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: ``bash theme={null} claude daemon stop --any --keep-workers ` The new supervisor reconnects to the running sessions. Without --keep-workers, the command ends the background sessions too. The --any` flag confirms you want to stop a supervisor that started on demand rather than as an installed service, which is the default.

What's Wrong or Missing?

A. The Attach documentation does not describe the wait-during-upgrade behavior introduced in v2.1.205

The v2.1.205 changelog states:

Fixed claude attach erroring when a background agent was mid-upgrade restart instead of waiting for it to come back

Before v2.1.205, invoking claude attach <id> (or pressing Enter/→ on an agent-view row) for a background session that the supervisor had started or was in the middle of restarting onto a new binary produced an error and the attach attempt failed, even though the session itself was recoverable. After v2.1.205, the attach waits for the supervisor to finish bringing the background agent back onto the new version and then connects.

The "Attach to a session" subsection says nothing about what claude attach does while the supervisor is mid-upgrade. A user running claude attach <id> immediately after the auto-updater fires expects one of:

• error / refused (the v2.1.205 pre-fix behavior), or
• immediate attach (when the upgrade is already done), or
• wait + connect (the v2.1.205 fixed behavior).

The current prose does not distinguish those cases, so users do not know that a hang during the upgrade window is the new recoverable behavior, not a stalled attach.

B. The supervisor section only describes the successful upgrade handoff

The supervisor paragraph at line 547 talks only about how the new supervisor "reconnects to them" after the restart, not about what an in-flight attach does during the same window. It implies the only relevant state is the success path. A reader following this paragraph cannot tell that v2.1.205 changed what claude attach does if it is called before the reconnection has finished.

C. The Version history table does not include a v2.1.205 row

The "Version history" table at the bottom of agent-view.md is referenced by older clients via the min-version directive inside its rows; it currently lists v2.1.203 as the latest row. A v2.1.205 row, with a {/* min-version: 2.1.205 */} note, would make the new behavior reachable through the page summary and align with how prior fixes in the same area were recorded.

D. The "background service did not respond" troubleshooting entry was not updated to scope out the upgrade case

After v2.1.205, an attach that briefly appears unresponsive because the background agent is being brought back on the new binary is normal behavior, not a stalled supervisor. The troubleshooting entry treats any unresponsive attach as a stall to be cleared with claude daemon stop --any --keep-workers, which is unnecessary in this case and would disrupt a session that would have come back on its own a moment later.

Suggested Improvement

Add a short paragraph to the end of the "Attach to a session" subsection:

{/* min-version: 2.1.205 */}If you attach (with Enter/→ in agent view or with claude attach <id> from the shell) at the moment the supervisor is restarting onto a new binary because the auto-updater just replaced it, the attach waits for the supervisor to bring the background agent back on the new version and then connects, instead of erroring out.

Adjust the "The supervisor process" paragraph to acknowledge the attach side:

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. {/* min-version: 2.1.205 */}An attach that lands while the supervisor is in the middle of restarting waits for the background agent to come back rather than erroring out. An idle pinned session is also restarted in place onto the new version so it picks up the update without you reattaching.

Add a row at the top of the Version history table:

| v2.1.205 | {/* min-version: 2.1.205 */}Attaching (via the agent view row or claude attach <id> from the shell) waits for the supervisor to finish a mid-upgrade restart rather than erroring out. |

Soften the "background service did not respond" troubleshooting entry to note that brief unresponsiveness tied to an auto-update is the v2.1.205 wait case:

{/* min-version: 2.1.205 */}If you attached or peeked right after the auto-updater replaced the binary, the brief unresponsiveness may be the supervisor restarting the background agent under your feet, not a stall. It normally resolves once the new binary is in place. If the unresponsive state lasts longer than expected, run claude daemon stop --any --keep-workers to recycle the supervisor while keeping the sessions intact.

Impact

Medium - Makes feature difficult to understand

Additional Context

The v2.1.205 wait-during-upgrade behavior is the missing piece between the supervisor's auto-update paragraph (which promises that sessions "keep running through the restart and the new supervisor reconnects to them") and the troubleshooting entry (which still tells users to recycle the supervisor on unresponsive attach). Without a docs note, a shell user running claude attach <id> immediately after an upgrade will not know whether the wait they observe is the new v2.1.205 behavior or a stalled attach they should diagnose and force-resolve with claude daemon stop --any --keep-workers. The agent-view row equivalent (Enter/→) has the same ambiguity.

Affected Pages:
| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/agent-view | 177-201 | "Attach to a session" — attach behavior described, mid-upgrade case omitted |
| https://code.claude.com/docs/en/agent-view | 547 | "The supervisor process" — successful handoff only, no attach-during-upgrade note |
| https://code.claude.com/docs/en/agent-view | 614-626 | "Agent view says the background service did not respond" troubleshooting — does not scope out the v2.1.205 wait case |
| https://code.claude.com/docs/en/agent-view | 678-680 | "Version history" table — no v2.1.205 row |

Total scope: 1 page affected (the claude attach / supervisor surface on agent-view.md).