Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
import {
parseWorktreePorcelain,
isDangerousWorktreeRemovalPath,
decideMergeStrategy,
isValidGitRef,
worktreePathKey,
type WorktreeListResult
} from './worktree'
/** One git invocation's result (mirrors git-service.ts's internal `Exec`). */
export interface GitExec { ok: boolean; out: string; err: string }
/** Injected git runner: runs `git <args>` in `cwd`. */
export type GitExecutor = (cwd: string, args: string[]) => Promise<GitExec>
/** Renderer-facing result (structurally a `GitResult`). */
export interface WorktreeOpResult {
ok: boolean
message: string
/**
* `worktreeRemove` only: the worktree is no longer on disk (its registration was pruned, or it
* was never registered). The caller MUST clear its binding even when `ok` is false — otherwise a
* group whose directory was deleted behind git's back can never be cleaned up: removal keeps
* failing and the dead path keeps being handed to new terminals.
*/
worktreeGone?: boolean
}
/**
* Delete the worktree's branch — and report what git ACTUALLY did.
*
* `git branch -d` refuses a branch that is not fully merged, and that refusal is the safety: an
* unmerged branch is unpublished work, and `-D` would throw it away. We keep the refusal (we never
* escalate to `-D`) but we no longer SWALLOW it. The confirm dialog tells the user the branch is
* deleted; when git declines, the result has to say so, or the user walks away believing a branch
* is gone while it is still sitting in `git branch` — the one thing worse than not deleting it.
*
* The refusal is hedged in the wording ("git would not delete it") rather than asserted as
* "unmerged": -d also refuses for other reasons (the branch is checked out in another worktree), and
* claiming a specific cause we did not verify is the same sin in the other direction.
*
* Returns a sentence to append to the caller's message, or '' when no branch deletion was asked for.
*/
async function deleteWorktreeBranch(
git: GitExecutor,
repoPath: string,
/** `null` = the worktree has a detached HEAD, so there is no branch to delete. */
branch: string | null | undefined,
deleteBranch: boolean
): Promise<string> {
if (!deleteBranch || !branch || !isValidGitRef(branch)) return ''
const r = await git(repoPath, ['branch', '-d', branch])
return r.ok
? ` Branch ${branch} deleted.`
: ` Branch ${branch} was kept — git would not delete it (it may have unmerged commits).`
}
export async function repoRoot(git: GitExecutor, cwd: string): Promise<string | null> {
if (!cwd) return null
const r = await git(cwd, ['rev-parse', '--show-toplevel'])
return r.ok ? r.out.trim() : null
}
/**
* Does this path exist on disk? Injected (the shared layer has no fs) — the real one is wired in
* `git-service`. Defaults to "it exists": the conservative answer, which never deletes anything and
* never calls a live worktree missing.
*/
export type PathExists = (p: string) => Promise<boolean>
const alwaysExists: PathExists = async () => true
/**
* List a repo's worktrees, with `prunable` made TRUE for any entry whose directory is not on disk.
*
* git only emits the `prunable` tag from **2.36**. Debian 11 / Ubuntu 20.04 — the Server Edition's
* own target platform — ship git 2.30, where a worktree whose directory was deleted behind git's
* back is listed as perfectly healthy. Everything downstream reads `prunable` as "the directory is
* gone": `reconcileWorktrees` would call a dead binding live (chip healthy, "↪ Move into worktree"
* still clickable → it kills a running session and respawns it into a directory that no longer
* exists) and the bind dialog would offer the vanished directory as an adoptable orphan.
*
* So we do not trust the tag alone: stat every entry and OR the result in. Same seam, same
* conservative default as `worktreeRemove`'s.
*
* It also reports WHETHER GIT COULD BE READ AT ALL, and every caller — the ops below AND the
* renderer's worktrees store, which reaches this through the `git:worktree-list` IPC — must honour
* that flag. Collapsing both outcomes to `[]` ("git listed nothing" and "the git call failed": a
* spawn EAGAIN under load, an unmounted/NFS repo, a corrupt index) is what let a single transient
* failure escalate: `worktreeRemove` read the empty list as "this worktree is not registered — it is
* already gone", answered `worktreeGone`, and the renderer destroyed every descendant terminal's
* tmux session (running processes and all) while the directory sat untouched on disk; and
* `reconcileWorktrees([], …)` flipped EVERY healthy bound group to "missing" in one read, with none
* of the strike streak `WORKTREE_STALE_STRIKES` exists to require. A failed read is never evidence
* of absence — so it is never dressed up as one.
*/
export async function listWorktrees(
git: GitExecutor,
repoPath: string,
pathExists: PathExists = alwaysExists
): Promise<WorktreeListResult> {
if (!repoPath) return { ok: false, entries: [] }
const r = await git(repoPath, ['worktree', 'list', '--porcelain'])
if (!r.ok) return { ok: false, entries: [] }
const entries = await Promise.all(
parseWorktreePorcelain(r.out).map(async (e) => ({
...e,
prunable: e.prunable || !(await pathExists(e.path))
}))
)
return { ok: true, entries }
}
/** What every op says when git itself could not be read. Never `worktreeGone` — see `listWorktrees`. */
const UNREADABLE = (repoPath: string): WorktreeOpResult => ({
ok: false,
message: `Could not read the worktrees of ${repoPath || 'this repository'}. Nothing was changed — try again.`
})
export async function worktreeAdd(
git: GitExecutor, repoPath: string, wtPath: string, branch: string, baseRef: string, isNew: boolean
): Promise<WorktreeOpResult> {
if (!repoPath || !wtPath) return { ok: false, message: 'Missing repo or worktree path.' }
// Reject a path that could be parsed as an option flag (argv injection).
if (wtPath.startsWith('-')) return { ok: false, message: 'Invalid worktree path.' }
if (!isValidGitRef(branch)) return { ok: false, message: 'Invalid branch name.' }
if (isNew && !isValidGitRef(baseRef)) return { ok: false, message: 'Invalid base ref.' }
// `--no-track` so a new branch does not inherit upstream and report "behind".
// `--` ends option parsing so wtPath can never be read as a flag (verified git ≥2.39).
const args = isNew
? ['worktree', 'add', '--no-track', '-b', branch, '--', wtPath, baseRef]
: ['worktree', 'add', '--', wtPath, branch]
const r = await git(repoPath, args)
return r.ok ? { ok: true, message: `Worktree ready at ${wtPath}.` } : { ok: false, message: r.err }
}
/**
* Merge `branch` into `baseRef`, and — only when `push` is true AND the repo actually has an
* `origin` — publish the base branch to origin.
*
* The push is OPT-IN by design. It used to run "best effort" on every merge: one click on a small
* header chip published to `origin/main` (CI, teammates, protected-branch noise) without the confirm
* dialog ever mentioning it. Nothing here may do more than the caller disclosed to the user, so the
* default is not to push, and the result message states exactly what happened.
*/
export async function worktreeMerge(
git: GitExecutor, repoPath: string, branch: string, baseRef: string, push = false,
/** See `PathExists` / `worktreeList`. Without it, a base checkout whose directory was deleted
* behind git's back is listed as healthy and `decideMergeStrategy` merges INTO A DIRECTORY THAT
* IS NOT THERE — the merge fails and the user is told to resolve a conflict that does not exist
* in a directory that does not exist. */
pathExists: PathExists = alwaysExists
): Promise<WorktreeOpResult> {
if (!isValidGitRef(branch) || !isValidGitRef(baseRef)) return { ok: false, message: 'Invalid ref.' }
const listed = await listWorktrees(git, repoPath, pathExists)
// A listing that FAILED is not "the base is checked out nowhere": planning `fetch-update` on it
// would try to move a ref that IS checked out elsewhere and die with something obscure. Decide
// nothing on a read that did not happen.
if (!listed.ok) return UNREADABLE(repoPath)
const baseEntry = listed.entries.find((e) => e.branch === baseRef) ?? null
// The base branch is checked out in a worktree whose directory is GONE. Do not merge in place
// (nothing to merge into) and do not quietly fall through to `fetch-update` either: git still has
// the registration and refuses to update a ref that is checked out elsewhere, so that would fail
// with an obscure message. Say what is actually wrong.
if (baseEntry?.prunable) {
return {
ok: false,
message:
`The checkout of ${baseRef} is missing (${baseEntry.path}). ` +
`Restore that directory or run \`git worktree prune\`, then try again.`
}
}
let baseDirty = false
if (baseEntry) {
const st = await git(baseEntry.path, ['status', '--porcelain'])
baseDirty = st.ok && st.out.trim().length > 0
}
const plan = decideMergeStrategy({ baseCheckedOutPath: baseEntry?.path ?? null, baseDirty })
if (plan.kind === 'blocked') return { ok: false, message: plan.reason }
if (plan.kind === 'fetch-update') {
// Base not checked out anywhere → advance the ref without touching a working tree.
const r = await git(repoPath, ['fetch', '.', `${branch}:${baseRef}`])
if (!r.ok) return { ok: false, message: `Cannot fast-forward ${baseRef}. Merge manually in a terminal.` }
} else {
// Base is checked out and clean → merge in that checkout.
const r = await git(plan.path, ['merge', '--no-ff', '--no-edit', branch])
if (!r.ok) {
await git(plan.path, ['merge', '--abort'])
// The merge ran in the BASE checkout, so that is where the conflict is — sending the user to
// the worktree terminal (as this message used to) points at the wrong directory entirely.
return {
ok: false,
message: `Merge conflict in the base checkout (${plan.path}). Resolve it there, then try again.`
}
}
}
const merged = `Merged ${branch} into ${baseRef}.`
if (!push) return { ok: true, message: merged }
// The push below is hardcoded to `origin`, so "some remote exists" is not the question: a fork
// whose only remote is `upstream` would fail here after being promised an origin push. Only push
// when `origin` itself is there — never claim (or attempt) a publish that cannot happen.
const remotes = (await git(repoPath, ['remote'])).out.split('\n').map((r) => r.trim())
if (!remotes.includes('origin')) return { ok: true, message: merged }
const p = await git(repoPath, ['push', 'origin', baseRef])
// A failed push does not undo the merge, so this stays `ok` — but it is reported, not swallowed:
// the user must know whether origin has the merge.
return p.ok
? { ok: true, message: `Merged ${branch} into ${baseRef} and pushed ${baseRef} to origin.` }
: { ok: true, message: `${merged} The push to origin failed — push ${baseRef} manually.` }
}
/**
* Remove a worktree (and optionally its branch).
*
* `pruneOnly` = clean up git's REGISTRATION only, never the filesystem. It is what a stale binding
* (directory deleted behind git's back) needs: without a prune, git keeps listing the path and a
* later `git worktree add` at the same place fails with "missing but already registered worktree".
* A directory that still exists is left completely alone in that mode — a wrongly-stale group must
* never be able to delete a live checkout.
*/
export async function worktreeRemove(
git: GitExecutor, repoPath: string, wtPath: string, homeDir: string, deleteBranch: boolean,
pruneOnly = false,
/** See `PathExists` / `worktreeList`: git's `prunable` flag needs git ≥ 2.36; the stat is the
* fallback that makes every older git tell the truth about a deleted directory. */
pathExists: PathExists = alwaysExists
): Promise<WorktreeOpResult> {
// Reject a path that could be parsed as an option flag (argv injection).
if (!wtPath || wtPath.startsWith('-')) return { ok: false, message: 'Invalid worktree path.' }
if (isDangerousWorktreeRemovalPath(wtPath, repoPath, homeDir)) {
return { ok: false, message: 'Refusing to remove that path.' }
}
const listed = await listWorktrees(git, repoPath, pathExists)
// git could not be read. This is NOT evidence that the worktree is gone — and answering
// `worktreeGone` here is destruction on a guess: the renderer would kill every descendant
// terminal's tmux session and rewrite their persisted cwds while the directory is still there.
// Report the failure; a removal the user can retry beats a removal that destroys the wrong thing.
if (!listed.ok) return UNREADABLE(repoPath)
const entry = listed.entries.find((e) => worktreePathKey(e.path) === worktreePathKey(wtPath))
if (!entry) {
// git answered, and it does not know this path. Only the DIRECTORY's absence proves the
// worktree is gone: a path git does not list but that still EXISTS is a binding pointing
// somewhere else (another repo's worktree, a hand-edited project file) — its sessions are alive
// and must not be torn down. Say so and touch nothing; Unbind is the way out of that binding.
if (await pathExists(wtPath)) {
return {
ok: false,
message: `${wtPath} is not a registered worktree of this repository, and it still exists. Nothing was removed — unbind the group instead.`
}
}
// Deleted AND already pruned (or never registered): the worktree really is gone. Prune anyway —
// a leftover registration elsewhere would block a future `worktree add` — and tell the caller,
// so it can clear the binding. (Unconditionally: pruning is the whole point of `pruneOnly`, so
// skipping it there was exactly backwards.)
await git(repoPath, ['worktree', 'prune'])
return { ok: false, worktreeGone: true, message: 'Worktree is not registered — it is already gone.' }
}
const branch = entry.branch
// git still lists it, but is the directory actually there? `prunable` is git's own answer
// (≥ 2.36); the stat is the fallback for older gits, which never set the flag.
const dirGone = entry.prunable || !(await pathExists(wtPath))
if (dirGone) {
// The directory is gone. `worktree remove` would fail; prune the registration instead and
// touch no files.
await git(repoPath, ['worktree', 'prune'])
const branchNote = await deleteWorktreeBranch(git, repoPath, branch, !pruneOnly && deleteBranch)
return {
ok: true,
worktreeGone: true,
message: `The worktree directory was already gone; its registration was pruned.${branchNote}`
}
}
if (pruneOnly) {
return { ok: false, message: 'The worktree directory still exists; nothing was pruned.' }
}
// `--` ends option parsing so wtPath can never be read as a flag (verified git ≥2.39).
const rm = await git(repoPath, ['worktree', 'remove', '--force', '--', wtPath])
if (!rm.ok) return { ok: false, message: rm.err }
await git(repoPath, ['worktree', 'prune'])
const branchNote = await deleteWorktreeBranch(git, repoPath, branch, deleteBranch)
return { ok: true, message: `Worktree removed.${branchNote}` }
}