# Worktrees

> Where an agent does a ticket's work, how it carries over between runs and machines, and when By Dawn clears it to free disk space.

This page explains where an agent does a ticket's work, and what happens to that work between runs. By the end
you'll know why two tickets never get in each other's way, what carries over when you start a ticket again, and
when By Dawn clears old work to free disk space.

When an agent starts on a ticket, it gets a **worktree** for each repo the ticket works in: a checkout of the repo
on the ticket's own branch, in a folder of its own on the machine running the agent. Every ticket gets its own, so
several agents can work in the same repo at once without touching each other's files, and your own checkout is never
changed.

A ticket that works in three [repos](https://docs.bydawn.com/repos/) has three worktrees, one per repo, each on the ticket's branch in that
repo ([Branching and CI](https://docs.bydawn.com/branching-and-ci/) says how that branch is named and where it starts).

## Where they live

Worktrees live on the machine that runs the ticket's agent: your own computer with the desktop app, or a remote
agent your organization runs. They sit under one folder, `~/.saw/worktrees` unless the machine is set up otherwise.

With the desktop app, **Settings › You › This computer** shows that folder as **Worktree root**. You
don't need to open it, though: the ticket's [Changes and Code](https://docs.bydawn.com/changes-and-code-view/) views show what's in its worktrees from anywhere, and its terminal opens
in them.

## When a worktree is made

The first time an agent starts on a ticket, the card shows it getting ready, step by step: "Claiming the ticket",
"Fetching the repository", "Cloning the repository", **"Creating the worktree"**, "Installing dependencies" and
"Starting the agent". The worktree starts from the branch the ticket's pull request will open into, so the agent
begins from the latest code there.

## Starting the ticket again

The worktree stays after the agent finishes, so starting the ticket again (**Start a new run**, or **Retry**) picks
up where it left off: the same worktree with every change in it, and the same conversation, so the agent remembers
what it did.

Choose **⋯** next to the start button for two other ways to start:

- **Start with a fresh conversation**: the agent starts without its earlier conversation, but "The worktree and its
  changes are kept." Use it when the agent has gone down the wrong path and you'd rather it looked at the work with
  fresh eyes.
- **Run on any machine (starts from the base)**: see [below](#work-that-hasnt-been-pushed).

### Work that hasn't been pushed

Changes the agent hasn't pushed yet exist only in its worktree, on that one machine. So a new run goes back to the
same machine, and the ticket says so: "This ticket's unpushed work is on mac-mini-2, so a new run goes there." If
that machine is offline, the run waits for it.

When you'd rather not wait, **Run on any machine (starts from the base)** lets another machine take it. That machine
builds a new worktree from the base branch, without the commits on the first one. They're kept there until it comes
back, so nothing is lost.

## When By Dawn clears a worktree

Worktrees take disk space, so By Dawn clears ones that are finished with:

- **When the ticket is done.** Once a ticket reaches a completed column, such as **Done**, a remote agent clears its
  worktrees.
- **When a machine runs low on space.** The agent clears finished worktrees and old caches until there's room again.
  It never touches a worktree with a live session, and never deletes files that By Dawn didn't create.

Clearing a worktree doesn't lose committed work. The ticket's **Changes** and **Code** can still show what was
committed, and its pull request, but nothing can be edited, and "The worktree was reclaimed" explains why
**Uncommitted** and **Whole branch** are greyed out. Once the machine's copy of the repo is gone too, the views say
"This ticket's code was cleared from its machine — reclaimed work is kept for 30 days."

Starting a ticket whose worktree was cleared makes a new one from its pushed branch.

## Disk space on remote agents

An org admin can see each remote agent's disk in **Settings › Organization › Remote agents**: how much
of the disk holding its worktrees is free, and **Disk breakdown**, which lists what's using it, such as By Dawn's own
worktrees, caches and Docker. A machine shows **Low disk space** when less than 10% is free, and **Disk almost full**
below 5% or 5 GB.

When the disk is critically full, the machine stops taking new jobs ("Paused: disk critically full"), clears space,
and starts again on its own once there's enough. Its waiting jobs move to another machine after a few minutes. If
the space is taken by files outside By Dawn, clearing worktrees won't help, and the machine says so: free space on it
yourself.

## FAQ

**Can I work in a ticket's worktree myself?**

Yes. Edit a file from the ticket's [Code](https://docs.bydawn.com/changes-and-code-view/#edit-a-file) view, or open the ticket's terminal,
which starts in its worktrees. The agent sees your changes on its next look.

**Does starting with a fresh conversation throw away the agent's changes?**

No. Only the conversation starts again. The worktree and every change in it are kept.

**Two tickets change the same file. Will they clash?**

Not while they work, because each has its own worktree and branch. They can conflict when their pull requests merge,
like any two branches, and By Dawn brings the worker back to fix a conflict if the mission's **Keep it mergeable** step is
ticked (see [Pull requests](https://docs.bydawn.com/pull-requests/#landing-it)).

Source: https://docs.bydawn.com/worktrees/