Ask AI
Ask AI Start conversation ↵

I'm an AI assistant with Grove's codebase and documentation in context.

Ask me anything about Grove.

EXAMPLE QUESTIONS

Clean up what a crash left behind

Every Grove verb cleans up after itself, but a crash, a killed daemon or an interrupted test run can skip that path and leave a tmux server, a worker process or a directory of files that no workspace owns. The reaper is the global pass that catches those leftovers. Think of it as a stocktake: compare what is on the shelves against the ledger, set aside what nobody ordered, and only throw it out if it is still unclaimed next time.

stateDiagram-v2
    direction LR
    [*] --> Found: a pass lists it
    Found --> Kept: a record names it
    Found --> Kept: config dir holds a transcript
    Found --> Marked: no record names it
    Marked --> Waiting: next pass, inside its grace
    Waiting --> Marked
    Marked --> Cleared: it vanished, or a record claims it
    Marked --> Swept: still there after its grace
    Swept --> [*]
    Cleared --> [*]
    Kept --> [*]

Mark, wait, sweep

Nothing is removed the first time it is seen. A leftover is marked, given a grace period, and removed only if a later pass still finds it unclaimed.

  • A pass compares what exists with what the records entitle. Each resource class has its own collector that lists what is on the host, and the workspace records decide what is accounted for. A collector never reads a record itself.
  • The first sighting is a mark. It is written to an append-only log, so a daemon restart between the mark and the sweep keeps the original sighting and the grace keeps running.
  • The grace is short for servers and long for files. Tmux servers and processes wait a minute, and per-workspace files wait a day.
  • The sweep re-checks under the workspace store's lock. A create saves its record under that same lock before it starts anything, so a workspace being created right now is always either named by the re-read or does not exist yet.
  • A leftover that disappears and later returns starts over. Its old mark is cleared when it vanishes, so it never inherits a stale grace.

What is never touched

The reaper is conservative by design. Leaving a leak costs a little disk or memory, and removing the wrong thing costs a live session.

  • Any workspace record entitles its resources, whatever its status. A running workspace whose server died, a paused one and an errored one all keep what they name.
  • Only what Grove itself started is a candidate. A process is recognised by the arguments Grove composes for it, a worker's config file or an observer's private socket, never by a name pattern your own process could share. The shared default tmux server is refused outright.
  • A wedged tmux server keeps its socket. If the server cannot be ended while its socket still accepts connections, something is still alive there, so only a socket that refuses connections counts as stale.
  • A config dir holding a real transcript is kept. A container's transcripts live in its agent config dir, so a dir with any transcript over 1 KB is listed as kept and never offered for removal. The check runs again at the moment of removal, so a transcript written after the mark still wins.
  • Files outside Grove's own per-workspace directories are out of reach. Transcripts, the SQLite stores and your config backups are never listed.

Run it by hand

The daemon runs a pass at start-up and then on its schedule. grove vacuum runs the same pass on demand.

grove vacuum                    # report candidates, change nothing
grove vacuum --apply            # remove what is past its grace
grove vacuum --class tmux       # one class only: tmux, process or files
  • A dry run lists everything a pass found, including candidates still in their grace with when they were first seen and when they become sweepable.
  • Run it twice to remove a leak. The first pass marks and the second, after the grace, sweeps.
  • It exits 1 whenever anything is marked, waiting or swept, so a CI job can assert that a host is clean.
  • grove doctor shows a leaked-resources row read from the latest pass. It is informational and never blocks a create.

Configuration

The daemon's reaper starts in dry-run mode, so it reports and removes nothing until you turn removal on.

~/.config/grove/config.json
{
  "reaper": {
    "enabled": true,
    "interval_seconds": 600,
    "dry_run": false
  }
}

grove vacuum --apply removes regardless of dry_run. Every field is in the Configuration Reference.

See also