Correct the Worktrees docs and document shortcut pins - #943
Merged
Conversation
Worktrees deep-dive against workspace-prep.ts, shared/git/worktree.ts, tmux/setup-script.ts, and archive.ts: - "When creation fails" claimed the card shows an Attention badge. That badge renders only for status `error`; a worktree failure goes through markSetupFailed, which sets `stopped` — and the reconciler never revisits it, since its query only selects running/stopping/creating/ archiving. What users actually see is the status line flipping to Blocked with the git error, so say that. - Both launch paths fetch the starting branch from origin and fork the new branch from `origin/<branch>`; checking out the starting branch directly uses the local copy. Neither was documented. - Removing a worktree also deletes the branch Dispatch created for it, and "Archive and remove worktree" force-deletes it (`branch -D`) including unpushed commits. The section only described the directory. - The tmux setup script skips the dependency install for terminal-type agents. Also from the diff since the last audit: the shortcut-pin `disabled` state (#937) in the Pins paragraph, the two terminal injection routes inject-text (#935) and inject-pin (#930) in the api-spec Terminal table, and a new ambient tip for shortcut pins deep-linked to a new media#media-sidebar anchor. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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 freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Nightly docs audit. Slice: the in-app Worktrees section (carried
next_focus), plus the user-facing gaps in the diff since9319fcaa.Worktrees deep-dive
Audited
docs-sections/worktrees.tsxagainstagents/workspace-prep.ts,shared/git/worktree.ts,agents/tmux/setup-script.ts,agents/archive.ts, and the create-dialog controls.status === "error"(agent-card-header.tsx); a worktree failure goes throughmarkSetupFailed, which setsstopped, and the reconciler never revisits it because its query only selectsrunning/stopping/creating/archiving. The real signal is the status line flipping to Blocked with the git error — now what the docs say.originand fork the new branch fromorigin/<starting branch>; checking out the starting branch directly uses the local copy, and repos without anoriginfall back to local. None of that was documented.git branch -D) along with unpushed commits. The section only described the directory.Verified-accurate and left alone: checkbox default/disabled state,
.envcopy, lockfile list and priority, sibling vs.dispatch/worktrees/location, auto-generated branch name, per-cwd new-branch preference, partial-worktree cleanup on failure, and the archive keep/remove prompt.Diff-driven
media.tsx— shortcut pins can now be greyed out by the agent itself with the caption as the reason (Add a disabled state to shortcut pins #937).docs/03-api-spec.md— Terminal table was missinginject-text(Mobile fullscreen input: API-backed Paste/Submit buttons #935) andinject-pin/:pinId(Add shortcut pins: one-click prompt injection from the sidebar #930); added both with their body/error contract.tips.ts— new ambient tip for shortcut pins (Add shortcut pins: one-click prompt injection from the sidebar #930 shipped in 0.33.7 with no tip), deep-linked to a newmedia#media-sidebaranchor.Deferred
Backlog gets the hold-badge-after-reload item (unchanged) and a note that the Archive and remove worktree button copy doesn't mention branch deletion — a product call, not a docs fix. Next run: the Repo Tools section against
.dispatch/tools.jsonhandling and lifecycle hooks.