Document worktree-creation failure UX in in-app docs#798
Merged
Conversation
The Worktrees docs section explained creation, branch options, location, and cleanup, but never covered what a user sees when worktree creation fails. That path is user-visible: since the user explicitly asked for an isolated worktree, Dispatch refuses to fall back to the main checkout — it marks the agent stopped with the git error in `last_error` (surfaced as an Attention badge + "Last error" field on the card) and cleans up any partial worktree/branch so a relaunch starts clean. Verified against setup-script.ts (failure branch), manager.ts (setAgentStatus stopped + "Worktree creation failed: …" last_error), and agent-card.tsx (Attention badge tooltip + Last error meta). Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What was audited
Docs-audit run scoped to
next_focus: the in-app Worktrees docs section (apps/web/src/components/app/docs-sections/worktrees.tsx) againstapps/server/src/shared/git/worktree.ts, following the concurrent-create.git/configlock fix in #794.Verified every existing claim against source and found them all accurate:
createUseWorktree = useState(true)), disabled + noted when not a git repo..envcopy + dependency install acrosspnpm-lock.yaml/yarn.lock/package-lock.json/bun.lockb(workspace-prep.ts,setup-script.ts).createNewBranchPrefAtom,atomWithLocalStoragekeyed by cwd), auto-generated name when blank..dispatch/worktrees/), cleanup logic, and parallel-agent isolation (now reliably true post-Fix .git/config lock race when creating worktrees concurrently #794).What changed
Added a "When creation fails" paragraph — the one genuine gap. This path is user-visible but was undocumented: because the user explicitly asked for an isolated worktree, Dispatch refuses to fall back to the main checkout. On failure the agent is marked
stoppedwith the git error inlast_error(surfaced as an Attention badge tooltip + Last error field on the card, permanager.tsandagent-card.tsx), and any partial worktree/branch is cleaned up so a relaunch starts clean. This resolves the long-standing backlog item from #409.Deferred to next run
🤖 Generated with Claude Code