Worktree

Functions

• worktree::create — mint a locked, isolated worktree off a base ref or a pull request head (pr); auto-claims for session_id when given, names the branch by id or deterministic codename per config, and returns an advisory dev_port derived from the id (never reserved anywhere).
• worktree::list — registry view, filterable by repo or session, with optional git status per worktree.
• worktree::get — one worktree with status.
• worktree::validate — check a path is a live managed worktree; reconciles records whose directories were removed by hand.
• worktree::claim — take session ownership (force to take over).
• worktree::release — release ownership (force to override).
• worktree::status — clean flag, ahead/behind, staged/unstaged/untracked counts, diffstat, rebase-in-progress, and integrated with an integration_reason, so squash- or rebase-landed branches read as merged even while ahead of their base.
• worktree::remove — remove a worktree; refuses dirty or unlanded work unless forced, and refuses while running processes hold files open under it (W222); the directory leaves its path instantly (staged into a trash area, deleted in the background); can delete the branch.
• worktree::prune — sweep: drop records whose directories are gone and remove clean, unclaimed, expired worktrees, including integrated ones whose work already landed (cron-bound, {} payload).
• worktree::land — queue the rebase / test / fast-forward / cleanup pipeline; returns a job_id immediately.
• worktree::land-step — internal queue consumer that executes land phases; never call it directly (denied to agents).

With provision.copy_ignored enabled in config, every create also replicates the source repo's gitignored files (.env files, caches) into the new worktree in the background; the create response never waits on it.

Errors carry stable W### codes; the ones worth branching on are W210 (already claimed), W220 (dirty), W221 (unmerged work), W222 (files held open by running processes), W401 (land already queued), W402 (unresolved rebase from a previous land), and the land-block reasons carried on events (W410 conflict, W411 tests, W412 target kept moving, W413 target checked out dirty). W5xx means configuration denied the operation, not that it failed: W500 gate off, W501 force disabled, W502 land target not in gates.land_targets, W503 repository not in gates.repos, W504 per-repo worktree budget hit. The message names the exact key; do not retry, surface that key to the operator (or drop the force flag) instead.

Reactive triggers

Register a worktree::* trigger when a different worker should react to lifecycle changes without polling worktree::list — announce lands in chat, start a follow-up agent when a sibling's branch merges, or alert on blocked lands.

Reach for it when:

• A land's outcome should drive the next step (worktree::landed, worktree::land-blocked with reason and conflict_files).
• Ownership changes matter to an orchestrator (worktree::claimed, worktree::released).
• Cleanup should cascade (worktree::removed).

The caller of worktree::land gets only { job_id, queued } back; the outcome arrives on these triggers, so a landing workflow should always bind one instead of polling.

How to bind

1. Register a handler: registerFunction('notify::on-land', handler).
2. Register the trigger:

iii.registerTrigger({
  type: 'worktree::landed',
  function_id: 'notify::on-land',
  config: {
    // optional equality filters:
    // repo_path, worktree_id, session_id
  },
})

All six types accept the same three optional filters; unknown config keys are rejected at registration. For event payload shapes, call get function info on the trigger type.