$worker

worktree

Name: worktree
Author: iii

v0.2.1

Git worktree lifecycle for parallel agents — mint, claim, and track isolated worktrees per repo, emit lifecycle trigger types, and land branches back through a per-repo FIFO queue (rebase, test gate, ff-only merge).

iiiverified

3 installs0 in 7d0 today

install

$iii worker add worktree@0.2.1

binarygit worktree parallel agents branches ci

macOS: arm64 · x64
Linux: arm64 · armv7 · x64
Windows: arm64 · x64 · x86

12functions 6triggers 1skills 3deps v0.2.1version

repoiii-hq/workers

exact versions are immutable; binary and bundle artifacts are digest-pinned.

functions

worktree::claim

function

Claim a worktree for a session. Fails with W210 when another session holds it, unless force is set.

request

forceboolean
Take the claim even when another session holds it.
session_idstringrequired
The claiming session.
worktree_idstringrequired
The worktree to claim.

response

claimedbooleanrequired
True when the claim is now held by `session_id`.
previous_session_idstring
The session that held the claim before, when taken over with force.
session_idstringrequired
The claiming session.
worktree_idstringrequired
The claimed worktree.

worktree::create

function

Create an isolated, locked git worktree off a base ref and register it in the cross-agent registry. Returns the path to hand to an agent as its working directory.

request

base_refstring
Ref to base the worktree on. Defaults to `HEAD`.
branchstring
Branch to create. Defaults to `<branch_prefix><worktree_id>` (or a codename when `branch_naming: codename`).
printeger· uint64min 0
Create the worktree at a GitHub pull request head: fetches `refs/pull/<n>/head` from `origin` and branches `<prefix>pr-<n>` at it. Mutually exclusive with `base_ref` and `branch`.
repo_pathstringrequired
Absolute path of the repository to branch from.
session_idstring
Session to auto-claim the worktree for.

response

base_refstringrequired
The ref the worktree was based on.
base_shastringrequired
The commit `base_ref` resolved to.
branchstringrequired
The branch checked out in the worktree.
created_atinteger· int64required
Creation time, ms since epoch.
dev_portinteger· uint16requiredmin 0
Advisory dev-server port derived from the worktree id.
pathstringrequired
Absolute path of the new worktree; hand this to an agent as its working directory.
repo_keystringrequired
Canonical per-repo key (FIFO group for lands).
worktree_idstringrequired
Stable id, `wt_<12hex>`.

worktree::get

function

Fetch one managed worktree with its current git status.

request

worktree_idstringrequired
The worktree to fetch.

response

base_refstringrequired
The ref the worktree was created from.
base_shastringrequired
The commit `base_ref` resolved to at creation time.
branchstringrequired
The branch checked out in the worktree.
created_atinteger· int64required
Creation time, ms since epoch.
dev_portinteger· uint16requiredmin 0
Advisory dev-server port derived from the worktree id: deterministic, collision-improbable, never reserved anywhere.
lifecycleall ofrequired
Current lifecycle (reported `orphaned` when the directory is gone).
all of (1)
variant 1
one of (5)
variant 1
valuestringenum: active
variant 2
valuestringenum: claimed
variant 3
valuestringenum: landing
variant 4
valuestringenum: land-blocked
variant 5
valuestringenum: orphaned
pathstringrequired
Absolute path of the worktree directory.
repo_keystringrequired
Canonicalized per-repo key.
repo_pathstringrequired
The repository path the worktree was created from.
session_idstring
Owning session, when claimed.
statusany of
Git status, when requested and computable.
any of (2)
variant 1
aheadinteger· uint64requiredmin 0
Commits ahead of the comparison base (upstream when set, else `base_sha`).
behindinteger· uint64requiredmin 0
Commits behind the comparison base.
cleanbooleanrequired
True when there are no staged, unstaged, untracked, or conflicted entries.
conflictedinteger· uint64requiredmin 0
Unmerged (conflicted) entry count.
diffstatstringrequired
`git diff --shortstat` of committed work since `base_sha`.
head_shastringrequired
Current HEAD commit.
in_rebasebooleanrequired
True while a rebase is in progress in this worktree.
integratedboolean
True when the branch's work is already contained in its integration target (fast-forward, merge, rebase, or squash merge). Integrated worktrees are prunable even when ahead of their base.
integration_reasonstring
Which check detected the integration: `same_commit`, `ancestor`, `no_added_changes`, `trees_match`, `merge_adds_nothing`, or `patch_id_match`.
stagedinteger· uint64requiredmin 0
Staged entry count.
unpushedinteger· uint64requiredmin 0
Commits not merged upstream (upstream ahead count, else commits past `base_sha`).
unstagedinteger· uint64requiredmin 0
Unstaged entry count.
untrackedinteger· uint64requiredmin 0
Untracked entry count.
variant 2
valuenull
updated_atinteger· int64required
Last mutation time, ms since epoch.
worktree_idstringrequired
Stable id, `wt_<12hex>`.

worktree::land

function

Queue a land: rebase onto the target, run the optional test gate via shell::exec, fast-forward the target with an atomic CAS, then clean up. Serialized per repo via the land queue.

request

force_restartboolean
Abort a conflicted rebase left by a previous land and start over.
keepboolean
Keep the worktree and branch after a successful land.
target_branchstringrequired
The branch to fast-forward with the worktree's commits.
test_cmdstring
Optional test command run in the worktree via `shell::exec` before merging (the test gate).
worktree_idstringrequired
The worktree to land.

response

job_idstringrequired
The queued land job.
queuedbooleanrequired
True when the job was enqueued.

worktree::land-step

function

Internal: execute one queued land job. Bound to the land queue; not agent-callable.

request

job_idstringrequired
The job to advance.
repo_keystring
FIFO group key; consumed by the engine's queue config, echoed here.

response

donebooleanrequired
True when the job reached a terminal state (landed or blocked).
job_idstringrequired
The advanced job.
phase_completedstringrequired
The last phase this invocation completed.

worktree::list

function

List managed worktrees, optionally filtered by repo or session and enriched with git status. Also reports unmanaged worktrees of the repo when repo_path is given.

request

include_statusboolean
Compute git status for each worktree (slower).
repo_pathstring
Only worktrees of this repository.
session_idstring
Only worktrees claimed by this session.

response

unmanagedobject[]required
Non-primary worktrees of the repo without a record (only populated when repo_path is given). Never auto-adopted.
- branchstring
  Checked-out branch ref, when not detached.
- pathstringrequired
  Absolute path of the worktree.
worktreesobject[]required
Managed worktrees, oldest first.
- base_refstringrequired
  The ref the worktree was created from.
- base_shastringrequired
  The commit `base_ref` resolved to at creation time.
- branchstringrequired
  The branch checked out in the worktree.
- created_atinteger· int64required
  Creation time, ms since epoch.
- dev_portinteger· uint16requiredmin 0
  Advisory dev-server port derived from the worktree id: deterministic, collision-improbable, never reserved anywhere.
- lifecycleall ofrequired
  Current lifecycle (reported `orphaned` when the directory is gone).
  all of (1)
  variant 1
  one of (5)
  variant 1
  valuestringenum: active
  variant 2
  valuestringenum: claimed
  variant 3
  valuestringenum: landing
  variant 4
  valuestringenum: land-blocked
  variant 5
  valuestringenum: orphaned
- pathstringrequired
  Absolute path of the worktree directory.
- repo_keystringrequired
  Canonicalized per-repo key.
- repo_pathstringrequired
  The repository path the worktree was created from.
- session_idstring
  Owning session, when claimed.
- statusany of
  Git status, when requested and computable.
  any of (2)
  variant 1
  aheadinteger· uint64requiredmin 0
  Commits ahead of the comparison base (upstream when set, else `base_sha`).
  behindinteger· uint64requiredmin 0
  Commits behind the comparison base.
  cleanbooleanrequired
  True when there are no staged, unstaged, untracked, or conflicted entries.
  conflictedinteger· uint64requiredmin 0
  Unmerged (conflicted) entry count.
  diffstatstringrequired
  `git diff --shortstat` of committed work since `base_sha`.
  head_shastringrequired
  Current HEAD commit.
  in_rebasebooleanrequired
  True while a rebase is in progress in this worktree.
  integratedboolean
  True when the branch's work is already contained in its integration target (fast-forward, merge, rebase, or squash merge). Integrated worktrees are prunable even when ahead of their base.
  integration_reasonstring
  Which check detected the integration: `same_commit`, `ancestor`, `no_added_changes`, `trees_match`, `merge_adds_nothing`, or `patch_id_match`.
  stagedinteger· uint64requiredmin 0
  Staged entry count.
  unpushedinteger· uint64requiredmin 0
  Commits not merged upstream (upstream ahead count, else commits past `base_sha`).
  unstagedinteger· uint64requiredmin 0
  Unstaged entry count.
  untrackedinteger· uint64requiredmin 0
  Untracked entry count.
  variant 2
  valuenull
- updated_atinteger· int64required
  Last mutation time, ms since epoch.
- worktree_idstringrequired
  Stable id, `wt_<12hex>`.

worktree::on-config-change

function

Internal: hot-reload the worktree worker from the authoritative configuration when it changes — swaps the per-call snapshot and re-binds the prune cron on a schedule change.

request

idstring
Configuration id that changed (advisory; the handler re-fetches).

response

okbooleanrequired

worktree::prune

function

Sweep managed worktrees: reconcile records whose directories are gone and remove clean, unclaimed, expired worktrees. Cron-safe: an empty payload uses defaults; dry_run reports without acting.

request

dry_runboolean
Report what would be pruned without acting.
repo_pathstring
Only sweep worktrees of this repository.

response

prunedstring[]required
Worktree ids pruned (or prunable, with dry_run).
skippedobject[]required
Records left alone, with reasons.
- idstringrequired
  The skipped worktree.
- reasonstringrequired
  Why it was skipped.

worktree::release

function

Release a session's claim. Fails with W211 when the caller does not hold the claim, unless force is set.

request

forceboolean
Release even when another session holds the claim.
session_idstringrequired
The releasing session (must hold the claim unless force is set).
worktree_idstringrequired
The worktree to release.

response

releasedbooleanrequired
True when the worktree is now unclaimed.
worktree_idstringrequired
The released worktree.

worktree::remove

function

Remove a managed worktree. Refuses dirty (W220) or unmerged (W221) work unless force is set; optionally deletes the branch.

request

delete_branchboolean
Also delete the worktree's branch.
forceboolean
Remove even when dirty or carrying unmerged commits.
worktree_idstringrequired
The worktree to remove.

response

branch_deletedbooleanrequired
True when the branch was deleted too.
removedbooleanrequired
True when the worktree (and its record) are gone.

worktree::status

function

Git status for one worktree: cleanliness, ahead/behind, diffstat, rebase-in-progress, lifecycle.

request

worktree_idstringrequired
The worktree to inspect.

response

aheadinteger· uint64requiredmin 0
Commits ahead of the comparison base (upstream when set, else `base_sha`).
behindinteger· uint64requiredmin 0
Commits behind the comparison base.
branchstringrequired
The branch checked out in the worktree.
cleanbooleanrequired
True when there are no staged, unstaged, untracked, or conflicted entries.
conflictedinteger· uint64requiredmin 0
Unmerged (conflicted) entry count.
dev_portinteger· uint16requiredmin 0
Advisory dev-server port derived from the worktree id.
diffstatstringrequired
`git diff --shortstat` of committed work since `base_sha`.
head_shastringrequired
Current HEAD commit.
in_rebasebooleanrequired
True while a rebase is in progress in this worktree.
integratedboolean
True when the branch's work is already contained in its integration target (fast-forward, merge, rebase, or squash merge). Integrated worktrees are prunable even when ahead of their base.
integration_reasonstring
Which check detected the integration: `same_commit`, `ancestor`, `no_added_changes`, `trees_match`, `merge_adds_nothing`, or `patch_id_match`.
lifecycleall ofrequired
Current lifecycle.
all of (1)
variant 1
one of (5)
variant 1
valuestringenum: active
variant 2
valuestringenum: claimed
variant 3
valuestringenum: landing
variant 4
valuestringenum: land-blocked
variant 5
valuestringenum: orphaned
stagedinteger· uint64requiredmin 0
Staged entry count.
unpushedinteger· uint64requiredmin 0
Commits not merged upstream (upstream ahead count, else commits past `base_sha`).
unstagedinteger· uint64requiredmin 0
Unstaged entry count.
untrackedinteger· uint64requiredmin 0
Untracked entry count.
worktree_idstringrequired
The inspected worktree.

worktree::validate

function

Validate a path as a managed worktree (console picker surface). Unmanaged worktrees are reported but never adopted.

request

pathstringrequired
Absolute path to validate.

response

managedbooleanrequired
True when a record manages this path.
reasonstring
Why the path is not valid.
validbooleanrequired
True when the path is a live, managed worktree.
worktree_idstring
The managing record's id, when one exists.

triggers

worktree::claimed

trigger

A session took ownership of a worktree.

invocation

repo_pathstring
Only deliver events for this repository path.
session_idstring
Only deliver events for worktrees claimed by this session.
worktree_idstring
Only deliver events for this worktree.

return

valueunknown

worktree::created

trigger

A new managed worktree exists.

invocation

repo_pathstring
Only deliver events for this repository path.
session_idstring
Only deliver events for worktrees claimed by this session.
worktree_idstring
Only deliver events for this worktree.

return

valueunknown

worktree::land-blocked

trigger

A land ended blocked (conflict, failed tests, dirty tree, moved target).

invocation

repo_pathstring
Only deliver events for this repository path.
session_idstring
Only deliver events for worktrees claimed by this session.
worktree_idstring
Only deliver events for this worktree.

return

valueunknown

worktree::landed

trigger

A land completed; the target branch was fast-forwarded.

invocation

repo_pathstring
Only deliver events for this repository path.
session_idstring
Only deliver events for worktrees claimed by this session.
worktree_idstring
Only deliver events for this worktree.

return

valueunknown

worktree::released

trigger

A worktree claim was released.

invocation

repo_pathstring
Only deliver events for this repository path.
session_idstring
Only deliver events for worktrees claimed by this session.
worktree_idstring
Only deliver events for this worktree.

return

valueunknown

worktree::removed

trigger

A managed worktree was removed.

invocation

repo_pathstring
Only deliver events for this repository path.
session_idstring
Only deliver events for worktrees claimed by this session.
worktree_idstring
Only deliver events for this worktree.

return

valueunknown