aspect worktree list --verbose says about it, plus its checkout. Name it, or run it from inside the slot to get the one you are standing in.
checkout: is what deciding whether to release needs: the commit the worktree is at, whether any remote has it, and whether the tree is clean, Bazel’s own leavings aside.
Without it, finding this out means listing the whole pool and matching a path by eye — which is the work a slot id exists to save.
Naming a slot
A name resolves as it does forpath: the branch checked out in the slot, the branch a free slot last held, the slot id or a unique prefix of it of four or more characters, or the slot’s directory. Any slot of this clone answers, free or held by anyone — another session’s included — since reading one acts on nothing. A free slot has no checkout: line. Another clone’s slot is refused, as release refuses it, because only that clone’s git can answer for its checkout.
Not naming one
Unnamed, it answers from any subdirectory of a slot, not just its root, because the worktree root comes from git rather than from the working directory. A slot is recognised by the name of its directory rather than by comparing paths: git canonicalises what it reports, so/var becomes /private/var on macOS and symlinks resolve, and two spellings of one directory would not compare equal — while aspect-worktree-<slot> is the same string either way.
Wherever it runs, inspect by a resumed session from a new process moves every lease of that session, its subagents’ included, off a recorded process that has stopped onto the caller’s, so they read as running; see agent detection.
When you are not in a slot
Unnamed, that is an answer rather than an error, and exits 0. It is the expected result in the clone itself, and the two shapes of it are distinguished because they lead different places. Either way it lists the slots this session holds, which is what an agent that has lost its place is asking — run as the session itself, its subagents’ too, each named — and then the leases of this session that ended in the last day: released, taken over, or taken back while its process had stopped. Their commits are on their branches. A held slot whose checkout directory is gone is marked(checkout gone: `aspect worktree release` says why).
In the clone:
git worktree add by hand:
Using it from a script
The exit code does not distinguish the three cases — two of them are 0 — so a script readslocation:
base and base_sha are where a branch add --create made started — the ref as given and the commit it was, which is the start of a git bundle range that a later fetch does not move. upstream is what the branch tracks, empty for none. head, head_on_remote and uncommitted are the checkout: line as data, head_on_remote null where there is no commit checked out; uncommitted lists git status --porcelain entries, Bazel’s own leavings excluded, each path named as the file is rather than as git quotes it, and a rename’s origin in from.
location is one of:
in_worktree says whether the working directory is in the slot reported: for an unnamed call, true only for slot, and for a named one, whether you happen to be standing in it. It cannot distinguish clone from unmanaged_worktree, which is why location exists. For a slot, held_by_this_session says whether the lease is yours — subagents sharing their parent’s session count as that session, and one given its own --agent-id is told a sibling’s slot is not. Outside a slot the document also carries held: {slot, branch, path, agent_id, gone} for each slot this session holds, agent_id naming a subagent’s and empty for the caller’s own, and gone true when the slot’s checkout directory is gone — aspect worktree release of it says why the lease is kept and how to recover the work. And ended: {branch, slot, ended_ms, agent_id} for each lease of this session, its subagents’ included, that ended in the last day — released, taken over, or taken back — on a slot the session no longer holds, agent_id naming the subagent and empty for the session’s own lease.
Arguments
string
The branch checked out in the slot, the branch a free slot last held, the slot id
aspect worktree list shows in its first column or a unique prefix of it of four or more characters, or the slot’s directory. Omitted, the slot the working directory is in.Flags
string
The agent harness asking, as given to
add with the same flag. Needed only when the lease was taken with --agent-kind; detected otherwise.string
The session or subagent asking, as given to
add with the same flag. Needed only when the lease was taken with --agent-id; detected otherwise.text | json
default:"text"
text writes the report to stderr and leaves stdout empty. json writes one document to stdout.Refusals
Unnamed, holding no slot is not a refusal. It exits 0 with
in_worktree: false.