WorktreeLeases

The leases of the worktrees: one holder per worktree at a time (trove-parts §TPW-4).

In the namespace octomy::trove::git. Declared in src/libs/libworktree/worktree/WorktreeLeases.hpp.

Detailed description

A lease lends one worktree of one checkout to one holder: a Trove lane (`lane:<X>`), a session (`session:<id>`) or an external caller (`external:<label>`). A write to the worktree (sync, park, finalize or remove) needs the caller's lease, or no live lease at all. A create and the reads need none. permits() states this rule, and Worktrees applies it.

A lease is not a lock. It has a term, 30 minutes by default, and the holder renews it before the term ends. An expired lease is free, and the next claim takes it. So a holder that crashed blocks the worktree for at most one term. release() frees a lease at once.

The store is `worktrees.json` in the base folder of the door host, written through SimpleDataStore in synchronous mode, as SessionBook writes `sessions.json`. The door host is the only writer (trove-parts §TPA-5), so the file has no lock. A mutex guards the in-memory state, because the tasks call from plan threads and the lane engine calls from the GUI thread. A file of a newer schema is never overwritten: the store then refuses every change.

The clock is a constructor argument, so a test sets the time and never waits for a lease to expire.

See also octomy::trove::git::Worktrees.