Documentation
¶
Overview ¶
Package git encapsulates the per-session git worktree: creation, diff stats, push, and cleanup.
Each agent session runs inside its own worktree under {configDir}/worktrees/, on a branch named "{BranchPrefix}{SessionTitle}". The worktree is torn down on pause (branch preserved) and destroyed entirely on kill. Callers interact via the GitWorktree type; a CommandRunner abstraction makes the exec layer injectable for tests.
Error handling convention: errors are wrapped with fmt.Errorf("...: %w", err) so callers can match the cause. ErrBranchGone is a sentinel returned when the underlying branch has disappeared between operations — callers typically recover by rediscovering the branch or dropping the session.
Index ¶
- Constants
- Variables
- func AheadBehind(repoPath, branch, base string, runner CommandRunner) (ahead, behind int, err error)
- func CleanupWorktrees(configDir string, runner CommandRunner) error
- func CurrentBranch(repoPath string, runner CommandRunner) (string, error)
- func FetchBranches(repoPath string, runner CommandRunner)
- func FetchRef(repoPath, ref string, runner CommandRunner) error
- func IsGitRepo(path string, runner CommandRunner) bool
- func IsTimeout(err error) bool
- func RemoveTitleSidecar(worktreePath string)
- func ResolveBaseCommit(repoPath, configured string, runner CommandRunner) (sha, name string, err error)
- func SearchBranches(repoPath, filter string, runner CommandRunner) ([]string, error)
- func WorktreeRemoveTimeout() time.Duration
- func WorktreeTitleSidecarPath(worktreePath string) string
- type CommandRunner
- type DiffStats
- type GitWorktree
- func NewGitWorktree(repoPath string, sessionName string, configDir string) (tree *GitWorktree, branchname string, err error)
- func NewGitWorktreeFromBranch(repoPath string, branchName string, sessionName string, configDir string) (*GitWorktree, error)
- func NewGitWorktreeFromBranchWithRunner(repoPath string, branchName string, sessionName string, configDir string, ...) (*GitWorktree, error)
- func NewGitWorktreeFromSpec(spec WorktreeSpec) (tree *GitWorktree, branchname string, err error)
- func NewGitWorktreeFromStorage(repoPath string, worktreePath string, sessionName string, branchName string, ...) *GitWorktree
- func NewGitWorktreeFromStorageWithRunner(repoPath string, worktreePath string, sessionName string, branchName string, ...) *GitWorktree
- func NewGitWorktreeWithRunner(repoPath string, sessionName string, configDir string, runner CommandRunner) (tree *GitWorktree, branchname string, err error)
- func (g *GitWorktree) ApplyStash(sha string) error
- func (g *GitWorktree) Cleanup() error
- func (g *GitWorktree) CleanupFailedStart() error
- func (g *GitWorktree) CommitChanges(commitMessage string) error
- func (g *GitWorktree) Diff() *DiffStats
- func (g *GitWorktree) DiffShortStat() *DiffStats
- func (g *GitWorktree) DropStash(sha string) error
- func (g *GitWorktree) EnsureBaseCommit() error
- func (g *GitWorktree) GetBaseCommitSHA() string
- func (g *GitWorktree) GetBranchName() string
- func (g *GitWorktree) GetRepoName() string
- func (g *GitWorktree) GetRepoPath() string
- func (g *GitWorktree) GetStashRef() string
- func (g *GitWorktree) GetWorktreePath() string
- func (g *GitWorktree) InspectTree() (TreeState, error)
- func (g *GitWorktree) IsBranchCheckedOut() (bool, error)
- func (g *GitWorktree) IsDirty() (bool, error)
- func (g *GitWorktree) IsExistingBranch() bool
- func (g *GitWorktree) Merge(sourceBranch string) error
- func (g *GitWorktree) OpenBranchURL() error
- func (g *GitWorktree) Prune() error
- func (g *GitWorktree) PushChanges(commitMessage string, open bool) error
- func (g *GitWorktree) Remove() error
- func (g *GitWorktree) SetStashRef(sha string)
- func (g *GitWorktree) Setup() (err error)
- func (g *GitWorktree) StashChanges(message string) (string, error)
- func (g *GitWorktree) StashListed(sha string) (string, error)
- func (g *GitWorktree) StashOnDisk(sha string) (bool, error)
- type TreeState
- type WorktreeSpec
Constants ¶
const MaxBranchSearchResults = 50
MaxBranchSearchResults is the maximum number of branches returned by SearchBranches.
Variables ¶
var ErrBranchGone = errors.New("branch not found locally or on remote")
ErrBranchGone is returned by Setup when the branch a paused instance was pointing at has disappeared both locally and on origin — typically because an operator ran `git branch -D <name>` from outside the app. Callers use errors.Is to classify the failure and surface a recovery hint (kill-to-clean-up) instead of a generic setup error.
var ErrNoCommits = errors.New("this appears to be a brand new repository: please create an initial commit before creating an instance")
ErrNoCommits reports a repository with no commits yet, where no base commit can exist. Its message is user-facing: it surfaces directly in the TUI when session creation fails.
var ErrStashNotDropped = errors.New("stashed changes restored, but the stash entry could not be dropped")
ErrStashNotDropped marks an ApplyStash whose apply succeeded but whose drop of the stash-list entry afterwards did not. The work is in the worktree; the wrapped error says what is left on the stash list.
var ErrTimeout = errors.New("git did not answer in time")
ErrTimeout marks a git command killed at its deadline: git never answered, which says nothing about the state it was asked about.
Functions ¶
func AheadBehind ¶ added in v0.13.0
func AheadBehind(repoPath, branch, base string, runner CommandRunner) (ahead, behind int, err error)
AheadBehind returns how many commits branch has that base lacks (ahead) and vice versa (behind), reading local refs only — one subprocess, no network, so it is safe on the metadata tick.
func CleanupWorktrees ¶
func CleanupWorktrees(configDir string, runner CommandRunner) error
CleanupWorktrees removes all worktrees and their associated branches. configDir is the workspace config directory; if empty, falls back to GetConfigDir(). Pass nil for runner to use the default subprocess runner.
func CurrentBranch ¶
func CurrentBranch(repoPath string, runner CommandRunner) (string, error)
CurrentBranch returns the current branch name for the given repo directory. Pass nil for runner to use the default subprocess runner.
func FetchBranches ¶
func FetchBranches(repoPath string, runner CommandRunner)
FetchBranches fetches and prunes remote-tracking branches (best-effort, won't fail if offline). Pass nil for runner to use the default subprocess runner.
func FetchRef ¶ added in v0.13.0
func FetchRef(repoPath, ref string, runner CommandRunner) error
FetchRef updates the remote-tracking ref named like "origin/main". The ref must genuinely exist under refs/remotes: a local branch whose name merely contains a slash ("release/2.0") is not a remote ref and returns nil without running anything, as does a ref with no slash at all. Network-bound: gitNetworkTimeout applies.
func IsGitRepo ¶
func IsGitRepo(path string, runner CommandRunner) bool
IsGitRepo checks if the given path is within a git repository. Pass nil for runner to use the default subprocess runner.
func IsTimeout ¶ added in v0.13.0
IsTimeout reports whether err comes from a git command that timed out.
func RemoveTitleSidecar ¶ added in v0.6.0
func RemoveTitleSidecar(worktreePath string)
RemoveTitleSidecar deletes the title sidecar if present. Exported for callers outside this package that remove a worktree without going through GitWorktree.Cleanup — e.g. session.RemoveOrphanWorktree, which force-removes an orphaned worktree directly via `git worktree remove`. Best-effort, mirroring removeTitleSidecar.
func ResolveBaseCommit ¶ added in v0.13.0
func ResolveBaseCommit(repoPath, configured string, runner CommandRunner) (sha, name string, err error)
ResolveBaseCommit returns the commit SHA a new session worktree should be cut from, along with the human-readable name of the ref it came from (for the branch picker label and logs).
configured is config.BaseBranch. When set, only that branch is considered — locally first, then as a remote-tracking ref, mirroring how setupFromExistingBranch resolves a branch that exists only on origin. A configured branch that resolves nowhere is an error rather than a silent fallback: quietly rooting a session somewhere other than where the user asked is worse than refusing.
When configured is empty the repo's default branch is auto-detected: origin/HEAD, then main, then master, then whatever is checked out. That last rung is loom's historical behaviour, kept so repos with no remote and no conventionally-named default branch keep working.
All lookups read local refs only — no fetch, so this stays fast and works offline. A stale origin/<branch> is the cost of that.
func SearchBranches ¶
func SearchBranches(repoPath, filter string, runner CommandRunner) ([]string, error)
SearchBranches searches for branches whose name contains filter (case-insensitive), ordered by most recently updated first. Returns at most MaxBranchSearchResults. If filter is empty, returns all branches up to the limit. Pass nil for runner to use the default subprocess runner.
func WorktreeRemoveTimeout ¶ added in v0.13.0
WorktreeRemoveTimeout exposes the `git worktree remove` deadline to the one caller outside this package that removes a worktree directly (session.RemoveOrphanWorktree), so it cannot fall back to a tick-sized budget and reintroduce the half-removed-worktree failure.
func WorktreeTitleSidecarPath ¶ added in v0.4.0
WorktreeTitleSidecarPath returns the path of the sidecar file that records a worktree's original instance title. It lives next to the worktree directory (a sibling file), NOT inside it — keeping it out of the work tree avoids polluting git status/diffs. Orphan discovery reads it to reconstruct the exact display title — and therefore the exact tmux session name — which the lossy branch-name sanitization (lowercasing, dash-collapsing) otherwise destroys.
Types ¶
type CommandRunner ¶
type CommandRunner = internalexec.Executor
CommandRunner is an alias for internal/exec.Executor. Kept as a type alias so git-package callers keep the familiar name while the concrete interface lives in a leaf package shared with cmd/.
func DefaultRunner ¶
func DefaultRunner() CommandRunner
DefaultRunner returns the production subprocess runner.
type DiffStats ¶
type DiffStats struct {
// Content is the full diff content
Content string
// Added is the number of added lines
Added int
// Removed is the number of removed lines
Removed int
// Error holds any error that occurred during diff computation
// This allows propagating setup errors (like missing base commit) without breaking the flow
Error error
}
DiffStats holds statistics about the changes in a diff
func DiffUncommitted ¶
func DiffUncommitted(repoPath string, runner CommandRunner) *DiffStats
DiffUncommitted returns the diff of uncommitted changes in the given repo directory. Used for workspace terminals that operate on the root repo without a worktree. Only shows tracked file changes to avoid mutating the user's git index. Pass nil for runner to use the default subprocess runner.
func DiffUncommittedShortStat ¶
func DiffUncommittedShortStat(repoPath string, runner CommandRunner) *DiffStats
DiffUncommittedShortStat returns only line counts for uncommitted changes. Pass nil for runner to use the default subprocess runner.
type GitWorktree ¶
type GitWorktree struct {
// contains filtered or unexported fields
}
GitWorktree manages git worktree operations for a session
func NewGitWorktree ¶
func NewGitWorktree(repoPath string, sessionName string, configDir string) (tree *GitWorktree, branchname string, err error)
NewGitWorktree creates a new GitWorktree instance using the workspace config's branch prefix. configDir is the workspace config directory; if empty, falls back to GetConfigDir().
func NewGitWorktreeFromBranch ¶
func NewGitWorktreeFromBranch(repoPath string, branchName string, sessionName string, configDir string) (*GitWorktree, error)
NewGitWorktreeFromBranch creates a new GitWorktree that uses an existing branch. The branch will not be deleted on cleanup. configDir is the workspace config directory; if empty, falls back to GetConfigDir().
func NewGitWorktreeFromBranchWithRunner ¶
func NewGitWorktreeFromBranchWithRunner(repoPath string, branchName string, sessionName string, configDir string, runner CommandRunner) (*GitWorktree, error)
NewGitWorktreeFromBranchWithRunner is NewGitWorktreeFromBranch with an injected CommandRunner for tests. Passing nil falls back to the default subprocess runner.
func NewGitWorktreeFromSpec ¶ added in v0.13.0
func NewGitWorktreeFromSpec(spec WorktreeSpec) (tree *GitWorktree, branchname string, err error)
NewGitWorktreeFromSpec creates a new GitWorktree from spec, returning the composed branch name alongside it.
func NewGitWorktreeFromStorage ¶
func NewGitWorktreeFromStorage(repoPath string, worktreePath string, sessionName string, branchName string, baseCommitSHA string, isExistingBranch bool, configDir string) *GitWorktree
NewGitWorktreeFromStorage rehydrates a GitWorktree from its persisted [session.GitWorktreeData] fields. Unlike NewGitWorktree, this constructor does no git work — it simply reattaches the in-memory wrapper to an on-disk worktree that already exists (or that needs to be rebuilt by a caller via Setup on resume).
func NewGitWorktreeFromStorageWithRunner ¶
func NewGitWorktreeFromStorageWithRunner(repoPath string, worktreePath string, sessionName string, branchName string, baseCommitSHA string, isExistingBranch bool, configDir string, runner CommandRunner) *GitWorktree
NewGitWorktreeFromStorageWithRunner is NewGitWorktreeFromStorage with an injected CommandRunner for tests. Passing nil falls back to the default subprocess runner.
func NewGitWorktreeWithRunner ¶
func NewGitWorktreeWithRunner(repoPath string, sessionName string, configDir string, runner CommandRunner) (tree *GitWorktree, branchname string, err error)
NewGitWorktreeWithRunner is NewGitWorktree with an injected CommandRunner (used by tests). Passing nil falls back to the default runner. configDir must be a concrete workspace config directory (callers thread this through via config.WorkspaceContext); passing empty string falls back to the global directory and logs a warning.
func (*GitWorktree) ApplyStash ¶ added in v0.6.0
func (g *GitWorktree) ApplyStash(sha string) error
ApplyStash applies the stash commit sha onto the worktree, targeting the exact commit rather than stack position (stash@{0}) — refs/stash is shared across every worktree of this repo. A no-op for an empty sha.
Because StashChanges' commit is two-parent (see its doc comment), `git stash apply` treats every previously-untracked file as a clean "add" against the index, so it comes back staged (`git status` would show it as `A`) rather than untracked (`??`) — unlike real `git stash apply -u`, which restores untracked content straight to disk without touching the index. To match the user-visible result of a real stash, ApplyStash finds every path that is newly added in the index relative to HEAD (`git diff --cached --diff-filter=A`) and unstages it (`git reset --`); the file's content on disk is untouched, only its index entry is removed, so it reads back as untracked. Best-effort: a failure here is logged, not returned, since the restore itself already succeeded and the file is still present (just staged) either way.
On a clean apply, the matching stash-list entry is dropped. A drop that fails returns an error wrapping ErrStashNotDropped: the work is restored, so the caller clears its reference, but what the drop left behind (its own entry, or another session's entry it removed and could not store back) is the user's to hear about. On conflict, the stash entry is left in place — mirroring `git stash pop`'s own safety behavior — and a plain error is returned so the caller does not clear its reference to it; neither the unstage nor the drop step runs then.
func (*GitWorktree) Cleanup ¶
func (g *GitWorktree) Cleanup() error
Cleanup removes the worktree and associated branch
func (*GitWorktree) CleanupFailedStart ¶ added in v0.13.0
func (g *GitWorktree) CleanupFailedStart() error
CleanupFailedStart undoes a Setup whose session then failed to start: it removes the worktree Setup just created, but deletes the branch only if Setup created it too. Setup also checks out a branch that already existed — one left behind by an earlier session with the same title, whose commits may be unmerged — and that one is kept.
func (*GitWorktree) CommitChanges ¶
func (g *GitWorktree) CommitChanges(commitMessage string) error
CommitChanges commits changes locally without pushing to remote
func (*GitWorktree) Diff ¶
func (g *GitWorktree) Diff() *DiffStats
Diff returns the git diff between the worktree and its base commit — the commit the session branched from (see ResolveBaseCommit) — along with statistics.
func (*GitWorktree) DiffShortStat ¶
func (g *GitWorktree) DiffShortStat() *DiffStats
DiffShortStat returns only the line counts (Added/Removed) without full diff content. Uses git diff --shortstat which is significantly cheaper for large diffs.
func (*GitWorktree) DropStash ¶ added in v0.6.0
func (g *GitWorktree) DropStash(sha string) error
DropStash removes the stash-list entry for commit sha, if present. A no-op if sha is empty or no longer listed (already dropped, or never stored). Runs against repoPath rather than worktreePath since refs/stash is a repo-level concept and the worktree directory may not exist at call time (e.g. after Kill has already removed it).
`git stash drop` only takes a position, stash@{N}, and refs/stash is shared by every worktree of the repository: another session pushing or dropping between the lookup and the drop shifts the stack, and the drop then deletes that session's entry — its only copy of the work. So the drop is verified against the commit git reports it removed. A wrong entry is stored straight back (at the top of the stack; its content and message are kept, its position is not) and the lookup retried.
func (*GitWorktree) EnsureBaseCommit ¶ added in v0.13.0
func (g *GitWorktree) EnsureBaseCommit() error
EnsureBaseCommit records the worktree's HEAD as its base commit when none is recorded, as a rebuild from an existing branch does. A session whose start was interrupted reaches Resume without one, and without it the session never gets diff stats. A recorded base is never overwritten.
func (*GitWorktree) GetBaseCommitSHA ¶
func (g *GitWorktree) GetBaseCommitSHA() string
GetBaseCommitSHA returns the base commit SHA for the worktree
func (*GitWorktree) GetBranchName ¶
func (g *GitWorktree) GetBranchName() string
GetBranchName returns the name of the branch associated with this worktree
func (*GitWorktree) GetRepoName ¶
func (g *GitWorktree) GetRepoName() string
GetRepoName returns the name of the repository (last part of the repoPath).
func (*GitWorktree) GetRepoPath ¶
func (g *GitWorktree) GetRepoPath() string
GetRepoPath returns the path to the repository
func (*GitWorktree) GetStashRef ¶ added in v0.6.0
func (g *GitWorktree) GetStashRef() string
GetStashRef returns the pending stash commit SHA, or "" if none.
func (*GitWorktree) GetWorktreePath ¶
func (g *GitWorktree) GetWorktreePath() string
GetWorktreePath returns the path to the worktree
func (*GitWorktree) InspectTree ¶ added in v0.13.0
func (g *GitWorktree) InspectTree() (TreeState, error)
InspectTree classifies what is on disk at the worktree path. The error accompanies TreeUnverified and says why the tree could not be confirmed; IsTimeout tells a git that never answered apart from one that rejected the tree.
The .git check comes first and is load-bearing, not an optimization: worktrees can live inside the repo they belong to (a workspace keeps them under <repo>/.loom/worktrees), so git run from a directory that lost its .git walks up and answers for the enclosing repo. An intact verdict lets Resume launch an agent into the tree, so git must also report the path as its own top level and as a linked worktree of this session's repository (not an unrelated repo, the main checkout, or a submodule), and the worktree must not still be locked "initializing" by a `git worktree add` that never finished.
func (*GitWorktree) IsBranchCheckedOut ¶
func (g *GitWorktree) IsBranchCheckedOut() (bool, error)
IsBranchCheckedOut checks if the instance branch is currently checked out
func (*GitWorktree) IsDirty ¶
func (g *GitWorktree) IsDirty() (bool, error)
IsDirty checks if the worktree has uncommitted changes
func (*GitWorktree) IsExistingBranch ¶
func (g *GitWorktree) IsExistingBranch() bool
IsExistingBranch returns whether this worktree uses a pre-existing branch
func (*GitWorktree) Merge ¶ added in v0.3.0
func (g *GitWorktree) Merge(sourceBranch string) error
Merge runs `git merge <sourceBranch>` in the worktree's directory, bringing another session's branch into this one. On conflict or any other non-zero exit, the git error/output is returned as-is and the merge is left exactly as git leaves it (MERGE_HEAD + conflict markers on a real conflict) — callers must not run `merge --abort` automatically, so a conflicted merge stays available for the user (or the agent) to resolve and commit.
func (*GitWorktree) OpenBranchURL ¶
func (g *GitWorktree) OpenBranchURL() error
OpenBranchURL opens the branch URL in the default browser
func (*GitWorktree) Prune ¶
func (g *GitWorktree) Prune() error
Prune removes all working tree administrative files and directories
func (*GitWorktree) PushChanges ¶
func (g *GitWorktree) PushChanges(commitMessage string, open bool) error
PushChanges commits and pushes changes in the worktree to the remote branch
func (*GitWorktree) Remove ¶
func (g *GitWorktree) Remove() error
Remove removes the worktree but keeps the branch
func (*GitWorktree) SetStashRef ¶ added in v0.6.0
func (g *GitWorktree) SetStashRef(sha string)
SetStashRef sets the pending stash commit SHA (or clears it, for "").
func (*GitWorktree) Setup ¶
func (g *GitWorktree) Setup() (err error)
Setup creates a new worktree for the session
func (*GitWorktree) StashChanges ¶ added in v0.6.0
func (g *GitWorktree) StashChanges(message string) (string, error)
StashChanges snapshots the worktree's tracked and untracked changes into a stash commit without disturbing the shared stash stack's ordering, and without ever calling `git stash push`/`create` (both pass through the same option parser, which documents only `git stash create [<message>]` — no -u/--include-untracked; passing it anyway silently swallows the flag into the commit message and drops untracked files from the snapshot, verified empirically against the installed git). Instead this builds, by hand, the same two-parent "index on ..." / "On ..." commit pair `git stash push -u` itself would produce, via plumbing against a scratch GIT_INDEX_FILE so the real index and working tree are left untouched:
- iCommit: tree = HEAD plus staged/unstaged modifications to already-tracked files (`add -u`), parent = HEAD. This is the "index" side of the stash.
- the returned commit: tree = iCommit's tree plus untracked files (`add -A` on the same scratch index), parents = [HEAD, iCommit]. Untracked files exist only in this tree, not iCommit's, so `stash apply` (which diffs parent1..parent2 for the index and parent2..commit for the worktree) restores them via the second diff, same as it would for a real `stash push -u` entry.
Note this is deliberately a two-parent commit, not real git's three-parent (b, i, u) --include-untracked format — there is no separate untracked-only commit unpacked straight onto disk. Building that would mean reproducing stash's internal object plumbing exactly; instead ApplyStash restores content via this simpler shape and then re-derives the tracked/untracked classification itself (see its doc comment) so the user-visible result still matches real stash.
`git stash store` then anchors the resulting commit against gc (dangling commits are prunable after gc.pruneExpire) and makes it visible via `git stash list` for manual recovery, using the SHA — never stack position — that plumbing already handed back, so there is no race window reading back "top of stack" afterward. Returns "" (no error) if the worktree has nothing to stash, mirroring IsDirty's scope (tracked and untracked).
func (*GitWorktree) StashListed ¶ added in v0.13.0
func (g *GitWorktree) StashListed(sha string) (string, error)
StashListed reports whether the stash commit sha is still an entry in `git stash list`, returning its current stash@{N} name when it is (a position that shifts as other sessions stash; see DropStash). One listing supplies every entry's commit, so no per-entry lookup can fail quietly: when the list cannot be read the answer is an error, never "not listed" — callers forget a stash that is not listed.
func (*GitWorktree) StashOnDisk ¶ added in v0.13.0
func (g *GitWorktree) StashOnDisk(sha string) (bool, error)
StashOnDisk reports whether the worktree already holds exactly what the stash commit sha would restore: its tracked and untracked (not ignored) content, snapshotted the way StashChanges builds a stash, matches the stash's tree. StashChanges leaves the worktree as it found it, so a pause interrupted after stashing — or a restore that applied the stash but never cleared its reference — leaves a worktree for which this is true, and applying the stash again would be redundant.
type TreeState ¶ added in v0.13.0
type TreeState int
TreeState is what InspectTree found at a worktree's path.
const ( // TreeAbsent means nothing is on disk at the path. TreeAbsent TreeState = iota // TreeGutted means the path is on disk but has no .git entry: git has // already let go of it (typically a half-finished `worktree remove`). // Only leftovers remain, which clearWorktreePath moves aside rather // than deletes. TreeGutted // TreeIntact means git recognizes the path as a working tree of its // own. Whatever it holds, committed or not, is live work. TreeIntact // TreeUnverified means the path has a .git entry but git could not // confirm it as a working tree rooted there (an error, a timeout, or // a .git git does not accept). Nothing is known about what it holds. TreeUnverified )
type WorktreeSpec ¶ added in v0.13.0
type WorktreeSpec struct {
// RepoPath is any path inside the target repository.
RepoPath string
// SessionName is the instance title; it becomes the branch name's leaf.
SessionName string
// ConfigDir is the workspace config directory. Empty falls back to the
// global directory and logs a warning.
ConfigDir string
// BranchPrefix overrides the workspace config's branch_prefix for this
// session. nil means "use the configured value"; a non-nil empty string
// deliberately means "no prefix at all", which is why this is a pointer.
BranchPrefix *string
// Runner injects a CommandRunner for tests. nil uses the default.
Runner CommandRunner
}
WorktreeSpec describes a request for a new-branch worktree. It exists so callers can override the branch prefix per session without every constructor growing another positional parameter — the same shape as session.InstanceOptions and overlay.LaunchOptions.