WIP: Worktrees from the phone: three declared capabilities

[broven]

Closes #133.

Branch off and put an agent on it from the phone. Three capabilities — listWorktrees, createWorktree, openWorktree — behind three routes, surfacing in two places.

A worktree nests under the space showing its repo

MuxSpace gains repoRoot and isWorktree — declared facts, like spaces capacity, never capabilities — and Herdr answers both on the workspace record it already sends, so the nesting costs no extra call and needs nothing switched on.

Three rules, each answering a case the flat list never had:

• A group takes the position of its most recent member. The list promises that what is fresh is near the top; sorting by the parent alone would bury a worktree used a minute ago under a checkout last touched last week.
• A worktree whose repo is not open stays flat. There is no row to indent under, and indenting under nothing reads as a rendering fault.
• Filtering flattens, for the same reason: a filter matching only the child would indent it under a parent that is not on screen.

A space outside any repo is the row it always was.

+ asks which kind

The worktree side asks which repo, because a sheet opened from the list has no current space to take one from. It offers the repos that are open, defaulting to the most recently used. Under the branch field sits "or open one that already exists" — the worktrees of the chosen repo that no space is showing, read once per repo choice. Those are the only checkouts the phone has no other route to; everything else is already a space in the list behind the sheet.

The tab strip renders only where there is a choice. No capability, or nothing open in a repo, and this is the plain new-space sheet, unchanged.

Opening navigates the phone. focus is never sent, so the operator's own screen stays where they left it — moving that is setFocus, which is its own capability for exactly this reason.

Both states are cards in the states playground, each with its "reach it for real" line.

Why the port, and not git worktree add + createSpace

The cheaper route is the obvious one, and ADR 0032 is there for when it is proposed again.

Herdr does not merely run Git; it keeps a record — open_workspace_id per checkout, a worktree block on every workspace. That record is the feature: it is how the phone knows which checkouts exist, which of them a space already shows, and which space nests under which repo. A checkout made behind Herdr's back has none of it, and Collie could only list it by doing its own Git work and then reconciling two answers about one directory.

Herdr declares all three. tmux and zellij decline them with their reasons: tmux could shell out to Git, but it keeps no mapping from a checkout to the session showing it, so what it made could not be found again. Declining is the honest answer until an adapter keeps that record itself and a probe proves it.

Probed, not assumed

Every Herdr cell in MUX_CONTRACT.md cites a first-hand probe of herdr 0.8.2 (protocol 20), 2026-08-28, run against an isolated herdr --session over a throwaway repo — never a live pane. Two findings shaped the code:

• worktree.create is not atomic. In a session with no window server the checkout was created and the open failed with worktree_open_failed: the branch exists, nothing shows it, and creating again answers worktree_create_failed because the path is taken. That case gets its own code — worktree.created_not_opened — and the UI offers open, never create again.
• worktree.open is idempotent, answering already_open with the space showing it. Treated as an answer rather than a refusal: either way the pane below is where to go.

Refusals reach the phone as catalogued codes. Three change what it does — a busy multiplexer means retry, an ambiguous branch means type a better one, a space outside a repo shows nothing at all — and the rest carry the multiplexer's own sentence in {reason}.

Notes

• Version files and CHANGELOG untouched, per CLAUDE.md's fork rule. A line in my words, if you want one:
  - Worktrees from the phone: create or open a Git worktree from the spaces list, and see it nested under its repo. (<hash>)
• Six locales, since the dictionary is total by type.
• Conformance covers all three in both directions. The declared side creates its own target first — "open this" cannot be proven against a checkout nothing made.
• bun run lint clean, bun test and the web suite green.

🤖 Generated with Claude Code

[AltanS]

Just a heads up, this PR is against the v1 branch (not main) and I dont have a clear release path for v1 yet. Not sure if that was intended, but it definitely saves me some time as I won't have to port the feature back into v1. There is a path to install the beta which are outlined in the v1's readme. Let me know if you have troubles setting it up.

If this was meant for the current main branch, please close and resubmit the PR.