@clawboo/worktrees gives a file-changing task its own git worktree and branch, writes the working files any
runtime can resume the task from, and records a structured handoff when a run ends. It is server-only, because it
runs git and writes files. The board decides what runs; this package is only the git and file mechanism, and the
database bookkeeping (the task’s workspaces row) lives in apps/web/server/lib/worktrees.ts.
Use this page when you change how task runs are isolated, paused, resumed or cleaned up. The model behind it is on
Worktrees and handoff. A worktree keeps parallel teammates’ file changes apart,
but it is not a sandbox: see What agents can do.
When a task gets a worktree
isolationForTask(kind) returns folder for research and review tasks and worktree for code and any
unknown kind; it never returns container. The IsolationLevel type is 'folder' | 'worktree' | 'container'.
folder means no worktree: the server runs the task in its own plain folder, <team folder>/tasks/<task id>,
which this package does not make. Worktrees are made by the task runner (a run of
POST /api/runtimes/<id>/run, or an agent routine that names a repository) and by
POST /api/board/<taskId>/workspace; team chat never makes one. The task runner refuses a file-changing task with
no repository path (workspace_unavailable) rather than run it without isolation; see
The executor runner.
The package’s default root is <repo>/.clawboo/worktrees, but the server always passes its own: task worktrees
live at <work folder>/worktrees/<hash of the repo path>/<task id> and review checkouts under
<work folder>/reviews/, so nothing is created inside your repository (see
The work folder). Each task gets the branch clawboo/task-<task id>.
The server also acts on a task worktree the board records under <clawboo home>/worktrees/, where older versions
made them, and on one the work folder move kept at its old place.
The lifecycle
Clawboo never merges a task branch; finished work waits on
clawboo/task-<task id>.
The working files
SOR_FILES names the system-of-record files, which any runtime (or a person) reads to pick a task up cold:
writeScaffold writes the first five. reconstructState(path) rebuilds what is done, what is broken and what comes
next from the handoff (falling back to task-progress.md) and init.sh, with no access to chat or the board, which
is what lets a different runtime resume the task.
The agent owns the folder these files sit in, so it could swap one for a link, or a hard link, to a file the server
can open, such as its database. readHandoff, writeHandoff and reconstructState therefore never follow one, and
the server uses the same helpers for VERIFICATION.md:
readTaskFile(dir, name, maxBytes?)returns the text ofnamedirectly underdir. It opens the file without following a link and throws unless it is a regular file with no other name and at mostmaxBytes(TASK_FILE_MAX_BYTES, 1 MiB, by default).readHandoffreads a refused file as missing.replaceTaskFile(dir, name, content)writes a new file and renames it over the name, so a link at the name is replaced, never written through.appendTaskFile(dir, name, content)appends to the file, creating it when missing, and refuses a link, a hard link or anything but a regular file.UnsafeTaskFileErroris what they throw for a refused file (itsfilePathnames it). Nothing was read or written. The scaffold’sVERIFY_CMDis a placeholder, andTASK.md’s steps tell the agent to set it: until the agent sets a real command, the verification gate reports that no verify command is configured and the attempt fails.
Path safety
These functions remove folders recursively and run commands, so every path they act on is checked first:- Task ids are one path segment.
assertSafeTaskIdaccepts only^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$and throws for anything else rather than rewriting it.branchNameForTask,worktreePathForand the lifecycle functions all go through it. - Worktree folders stay under the root.
worktreePathFor(repo, taskId, rootDir)resolves the task’s worktree folder and throws if it would land anywhere but one segment below the root. - Removal rebuilds the path. Before their recursive remove,
pauseWorktreeandcompleteWorktreerebuild the folder from the root and the task id, and throw if the stored record points somewhere else.rootDirmay be a list of roots, and then the record has to be the task’s worktree folder under one of them; an empty list refuses every record. The server passes the work folder’s root, the state folder’s, and any root the work folder move kept a checkout under. - A replace never loses work. Resume and a provision’s clean-up of leftovers delete a task’s worktree folder only
when it is missing, empty, or a checkout of the task’s repository at a commit a branch holds, with nothing in
git status --ignored. Anything else throwsUnsafeWorktreeErrorand the folder is left exactly as it was: uncommitted changes, files git ignores (an.env, build output), a detached commit no branch holds, a separate repository (its own.git, whose commits would go with it), or a folder git cannot read. - GC goes by registration. For a checkout git lists, GC commits any uncommitted changes to its branch, then
removes the folder; files git ignores are not committed and go with it. It skips a listed checkout that is a
separate repository, has its commit on no branch, or has changes on a detached HEAD. A folder git does not
list is removed only under the rule above, and a folder whose registration git could not report is always
kept. With
owns, GC leaves alone, and does not count, any folder the callback rejects; the server passes it for the work folder’s roots and accepts only checkouts its board records there or that carry this install’s.<task id>.ownermarker, so two installs can share a work folder. - Review checkouts stay in the review folder.
removeReviewWorktree(repo, worktree, rootDir)throws before it removes anything unless the record’s path is exactly one segment below the review root (rootDir, else<repo>/.clawboo/reviews). Pass therootDirthe checkout was provisioned with.provisionReviewWorktreechecks its own path the same way. ItsrepoPathmay be a bare repository, such as the history the server keeps of a team folder (see How work is checked). - Verify commands run in Clawboo’s folders only. The server’s verification gate runs
VERIFY_CMDonly in a task or review checkout or a team folder under the work folder’sworktrees/,reviews/andteams/, in a folder under Clawboo’s state folder (older layouts), or in a checkout the work folder move kept at its old place. It refuses anything else, including the work folder itself, its other folders, and a link whose real path leaves those places, before it runs the command in that real path.
Helpers you will reach for
KeyedMutex.mutex.run(key, fn, { acquireTimeoutMs })serializes work per key and throwsMutexAcquireTimeoutErrorwhen the wait runs out. The lifecycle functions lock per worktree path, the task runner locks each agent’s persistent home (the wait isCLAWBOO_HOME_MUTEX_ACQUIRE_MS), and the OpenClaw routine dispatcher locks per agent.execGit(cwd, args). Runsgitwith a timeout and an output cap and throwsGitErrorwith the command’sstderrandargs. The Computer tab’s git status and file diffs use it.- Diffs.
diffStatandworktreeDiffcompare a worktree with its baseline, andisDetachedconfirms a review checkout has no branch. - Registration.
worktreeRegistration(repo, path)answersregistered,unregistered, orunknownwhengit worktree listitself failed.isWorktreeRegisteredis the yes-or-no form, withunknownas no; anything that removes a folder on the answer uses the three-way form.
Who uses it
Only the server: the task runner, the board’s workspace routes, the verification gate and critic, the Routines dispatchers, and the Computer tab’s file view. Agent chat and team chat import onlyMutexAcquireTimeoutError, to
recognise a busy agent home.
Test it
Runpnpm --filter @clawboo/worktrees test. The suite creates real git repositories in temporary folders, so it
needs git on your PATH; CI also runs it on Windows and macOS.
Related
- Worktrees and handoff: why tasks get worktrees and how handoff works.
- Hand a task from one runtime to another: the handoff from start to finish.
- The executor runner: when the runner provisions, pauses and completes a worktree.
- How work is checked: how the verify command and the critic judge the work.