[DOCS] Background agent working directory deleted, replaced by a file, or invalid: docs do not mention the v2.1.203 "fail once with a clear error" behavior

Documentation Type

Unclear/confusing documentation

Documentation Location

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

Section/Topic

• The "Troubleshooting" section, specifically the area between "Sessions show as failed after shutdown" and "A session fails before starting with a possibly low memory note". Neither troubleshooting entry addresses what an operator sees when the background session's working directory has been deleted, replaced by a file, or has become an invalid path on disk.
• The "Version history" table at the bottom of the same page. The table lists v2.1.202, v2.1.200, v2.1.199, v2.1.198, v2.1.196, v2.1.195, and earlier rows; there is no v2.1.203 row, so the fix is not represented in the version-history summary that older clients are directed to.

Current Documentation

The "Troubleshooting" section of https://code.claude.com/docs/en/agent-view covers shut-down, low-memory, stalled-supervisor, dispatch authentication, macOS folder access, macOS local-network permission, slow-after-attach, and .claude/worktrees/ filling failures. The full set of troubleshooting entries the section currently lists is:

### Sessions show as failed after shutdown Shutting down or restarting your machine stops running background sessions, so they show as failed when you next open agent view. Attach, peek, or reply to any of them and the session restarts from where it left off. Sleep alone doesn't cause this. Sessions are preserved across sleep and the supervisor reconnects to them on wake. ### A session fails before starting with a possibly low memory note As of v2.1.199, when a background session's process exits before it finishes starting and the host is low on memory, the row's status names the exit and adds possibly low memory — free some up and retry. Earlier versions showed only the bare exit reason for this failure. ### Agent view says the background service did not respond ... ### Dispatch fails with Could not resolve authentication method ...

No entry describes the case where the working directory the background session was started in is no longer present, has been replaced by a file, or is otherwise invalid on disk. The "Version history" table top row is v2.1.202, and the bottom of the table lists the launch row at v2.1.139. There is no v2.1.203 row.

The Supervisor section's "## State and recovery" prose ("Where state is stored", "Inspect the supervisor", "Background sessions across updates") similarly describes file locks, version-skew, and stale daemon.lock recovery paths but does not mention what happens when the session's own working directory is gone.

What's Wrong or Missing?

A. The v2.1.203 "fail once with a clear error" behavior is not described anywhere on agent-view

The v2.1.203 changelog records:

Fixed background agents crash-looping when their working directory was deleted, replaced by a file, or became an invalid path — they now fail once with a clear error

Before this fix, a background agent whose working directory had been deleted, swapped for a regular file, or otherwise vanished from under it would repeatedly start, fail, and get respawned by the supervisor in a loop, because the failure signature matched the conditions the supervisor treats as a stuck worker and tries to recover from. After the fix, the agent fails one final time with a single, readable error and the supervisor stops respawning it.

The agent-view page is the canonical place operators learn how background sessions report and recover from startup failures. It already documents analogous cases (possibly low memory, background service did not respond, dispatch-auth failures) in a parallel shape. It does not document this case, so:

• An operator running into the post-fix row in agent view has no way to learn from the docs that "fail once with a clear error" is the expected behavior on v2.1.203, instead of the crash-loop the earlier versions produced.
• The "Troubleshooting" section is silent on which row status they should see when their cwd is gone, and silent on the most common cause (the directory was moved, renamed, deleted, or replaced with a regular file by another tool between dispatch and the next turn).
• The "Version history" table does not mention the fix at all, so a user who upgrades to v2.1.203 and finds that a previously crash-looping session now reports a single clean failure has no way to confirm from the docs that the new behavior is intended.

B. The "replaced by a file" and "invalid path" sub-cases are not listed

The fix covers three distinct on-disk scenarios:

1. The directory was deleted while the session was running.
2. The directory path is now a regular file (something replaced the directory entry with a file of the same name).
3. The path is otherwise invalid for the worker — the changelog treats these as one crash-loop class and fixes them together.

The current troubleshooting entries only mention shell-out-style working-directory failures in passing ("Sessions are preserved across sleep", "the row shows that error instead" for low memory, "Stops idle non-pinned sessions first" for memory pressure). No entry groups the three v2.1.203 sub-cases and tells an operator that all of them now produce the same single-failure result, with no further supervisor respawn.

C. No cross-reference to the error wording

The https://code.claude.com/docs/en/errors reference describes individual fatal errors. The "crash-loop replaced by a clear error" wording in the changelog implies a named, stable error an operator could match on. Neither agent-view.md nor errors.md is currently updated to name that error or to say "if you see this, your working directory was deleted, replaced by a file, or became invalid for the worker — restart the session from a directory that still exists." Without that cross-reference, an operator encountering the new error has to guess that the working-directory handling is what changed.

Suggested Improvement

Add a new troubleshooting entry to the agent-view Troubleshooting section

Insert the following entry alongside the existing "Sessions show as failed after shutdown" / "A session fails before starting with a possibly low memory note" pair:

### A session's row reports the working directory is gone A background session that was started in a directory that has since been deleted, replaced by a regular file of the same name, or otherwise become an invalid path fails exactly once with a clear error, and the supervisor stops respawning it. As of v2.1.203 the error replaces the older behavior in which the supervisor repeatedly tried to restart the session and the row alternated between Working and a crash-style error. The row's status names the path that is gone so you can confirm the cause. To recover, dispatch a new session from a directory that still exists on disk, or recreate the expected directory and attach, peek, or reply to the existing row — the supervisor starts a fresh worker for that session in the recreated directory. If the session's working directory was a git worktree under .claude/worktrees/, see .claude/worktrees/ is filling up for the cleanup path.

Add a v2.1.203 row to the Version history table

Extend the "Version history" table on https://code.claude.com/docs/en/agent-view with a row directly above the current v2.1.202 row:

| v2.1.203 | {/ min-version: 2.1.203 /}A background agent whose working directory was deleted, replaced by a regular file, or otherwise became an invalid path fails once with a clear error and is left in that state, instead of being repeatedly restarted by the supervisor. The error names the working directory that the worker could not reach. Before v2.1.203, the supervisor treated this failure as a stuck worker and tried to restart the session, producing a visible crash-loop. |

Optional: name the error in errors.md

If errors.md documents the per-failure error class produced when a worker's cwd is gone, give it a heading like Background session working directory gone and link to the new agent-view troubleshooting entry with one sentence: "See Agent view › A session's row reports the working directory is gone for the recovery flow."

Impact

High - Prevents users from using a feature

Additional Context

The agent-view troubleshooting section already groups its failures by the row-status an operator sees ("failed after shutdown", "possibly low memory", "did not respond", "Could not resolve authentication method", "Operation not permitted", "connect: no route to host", "slow to respond", ".claude/worktrees/ is filling up"). The new entry follows that pattern: a row-level symptom and a recovery path. The version-history row follows the same shape as the v2.1.202, v2.1.200, v2.1.199, and v2.1.198 rows already on the page.

Affected Pages:
| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/agent-view | Primary documentation location. Section 3 anchors here. The Troubleshooting section needs the new entry and the Version history table needs the v2.1.203 row |
| https://code.claude.com/docs/en/errors | Cross-reference. The named error the worker emits should be documented in the errors reference and link to the new troubleshooting entry |

Total scope: 2 pages affected.

The v2.1.203 changelog entry the agent-view version-history row is supposed to summarize is:

Fixed background agents crash-looping when their working directory was deleted, replaced by a file, or became an invalid path — they now fail once with a clear error