Worktrees

Worktrees are the checked-out working copies a project's tasks run in, one per slot on a node. These endpoints list, add, release and erase slots, and edit the port grid that assigns each slot its ports.

📄️Get port grid

Returns the organization's port grid: each service variable with its range start and the projects that declare it, the block size, stride and window, the automatic port range, and any configuration warnings. Requires the Org Owner or Org Admin role.

📄️Create port grid variable

Adds a service variable to the port grid with its range start; projects that declare it move onto the grid at their next worktree lease. Returns the created variable, or 409 for a duplicate name. Requires the Org Owner or Org Admin role.

📄️Delete port grid variable

Removes a variable from the port grid without checking current use; projects that declare it get an automatically assigned port at their next lease. Returns 204 with no body. Requires the Org Owner or Org Admin role.

📄️Update port grid variable

Changes a port grid variable's name, range start or description; `name` and `range_start` cannot be cleared. Returns the updated variable, or 409 when the new name is taken. Requires the Org Owner or Org Admin role.

📄️List worktrees

Lists the worktree slots the caller can see, ordered by project, slot number and node, with each slot's state, current task and node. Filter by `node_id`; `limit` caps the number of rows.

📄️Add worktree slots

Declares worktree slots for a project on a node: `count` takes the lowest free slot numbers, or `number` names one. Returns the created slots, each with a warning when the clone has no git access to a private repository. Requires the Org Owner or Org Admin role.

📄️Set clone owner

Sets whose git access a project's clone on a node uses, for every slot of that project there; the person must belong to the node's organization. Returns the new owner and the number of slots changed. Requires the Org Owner or Org Admin role.

📄️Delete worktree slot

Removes one worktree slot's record only: the directory stays on the node and any runner in it keeps going. Returns 204 with no body. Requires the Org Owner or Org Admin role.

📄️Get worktree

Returns one worktree slot by project name and slot number, with its state, current task and node. Pass `node_id` when the project has slots on several nodes; otherwise the first node by name is used. A slot the caller cannot see returns 404.

📄️Erase worktree slot

Deletes one worktree slot even when it is in use, ending whatever task or session holds it and asking the node to remove the directory. Returns what happened to the record, the directory and the holder. Requires the Org Owner or Org Admin role.

📄️Release worktree slot

Frees a worktree slot held by a task or user and stops the runner in it; a held task is dispatched again, and the next lease discards uncommitted work in the slot. Returns 409 for the main clone (#0), and while a live session is attached unless `force` is true. Returns 204 with no body.

📄️Set worktree slot title

Sets a worktree slot's title, description or both; an empty string resets the value to its default. Returns the resolved title and whether it was saved and applied on the node, which can lag while the node is offline.