Skip to content
Sign in

worktree

v0.4.6

Git worktree lifecycle for parallel agents — mint, claim, and track isolated worktrees per repo, call observable lifecycle functions (worktree::on-*), and land branches back through a per-repo FIFO queue (rebase, test gate, ff-only merge).

license: Apache-2.0Used in 1 kitagentsbranchescigitparallelworktree

Install

bash
iii trigger compose::add worker=worktree

Run in your project with the iii engine running. Exact versions are immutable and digest-pinned.

worktree

Git worktree lifecycle for parallel agents. worktree::create mints an isolated, locked worktree off any ref and registers it in a cross-agent registry; agents work inside it through their turn's filesystem scope (metadata.fs_scope.root); worktree::land rebases the branch onto a target, runs an optional test gate through the shell worker, fast-forwards the target with an atomic compare-and-swap, and cleans up. Every lifecycle change is a call of a worktree::on-* function that sibling workers observe, so a Slack bot can announce lands or a harness can react when a sibling's branch merges.

Install

iii call compose::add worker=worktree

iii call compose::add resolves the worker and its dependencies, writes exact declarations to worker-compose.yaml, and reconciles the Compose project. The land test gate delegates to shell::exec, so install the shell worker alongside it:

iii call compose::add worker=ide

Quickstart

use iii_sdk::{register_worker, CallRequest, InitOptions};
use serde_json::json;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let iii = register_worker("ws://localhost:49134", InitOptions::default());

    // 1. Mint an isolated worktree and hand its path to an agent.
    let wt = iii.call(CallRequest {
        function_id: "worktree::create".into(),
        payload: json!({ "repo_path": "/home/me/project", "session_id": "sess_1" }),
        action: None,
        timeout_ms: Some(30_000),
    }).await?;
    println!("agent fs_scope root: {}", wt["path"]);

    // 2. ... the agent commits work inside the worktree ...

    // 3. Land it: rebase onto main, gate on tests, ff-merge, clean up.
    let job = iii.call(CallRequest {
        function_id: "worktree::land".into(),
        payload: json!({
            "worktree_id": wt["worktree_id"],
            "target_branch": "main",
            "test_cmd": "cargo test",
        }),
        action: None,
        timeout_ms: Some(30_000),
    }).await?;
    println!("queued land job: {}", job["job_id"]);
    Ok(())
}

The land completes asynchronously; observe worktree::on-landed / worktree::on-land-blocked (below) or poll worktree::get for the outcome.

Configuration

Runtime settings live in the configuration worker under id worktree and hot-reload on change (a prune_schedule change observes cron::on-tick with the new expression, then disposes the previous observer).

worktree_root: "worktrees"          # relative to III_COMPOSE_DIR
branch_prefix: "iii/"               # auto-minted branch names
branch_naming: "id"                 # or "codename" for <adjective>-<noun>-<4hex> names
prune_schedule: "0 0 * * * *"       # six-field cron for the reconcile sweep
prune_expire_hours: 72              # idle hours before a clean, unclaimed worktree is prunable
land_queue: "worktree-land"         # engine queue name for land jobs
max_land_retries: 3                 # rebase retries when the target branch moves mid-land
git_timeout_ms: 60000               # per-git-subprocess bound
test_timeout_ms: 600000             # land test gate bound
provision:
  copy_ignored: false               # replicate gitignored files into new worktrees
  include: []                       # globs; empty = every ignored path
  exclude: []                       # globs subtracted from the copy
  max_copy_bytes: 2147483648        # total budget; entries beyond it are skipped
gates:
  allow_remove: true                # worktree::remove
  allow_force: false                # remove force, claim/release force, land force_restart
  allow_branch_delete: true         # remove delete_branch and the land finalize cleanup
  allow_land: true                  # worktree::land
  allow_prune: true                 # worktree::prune (including the cron sweep)
  land_targets: ["*"]               # globs; pin to ["main"] to allow only mainline lands
  repos: ["*"]                      # globs over canonical repo paths worktrees may branch from
  max_worktrees_per_repo: 0         # live-worktree budget per repo at create time; 0 = unlimited

Copy-ignored provisioning

With provision.copy_ignored: true, every create spawns a background task that replicates the source repo's gitignored files (.env files, caches, local settings) into the new worktree: cheapest copy per platform (APFS clones via cp -c with a plain fallback on macOS, --reflink=auto on Linux), VCS metadata directories and the managed worktree root always excluded, bounded by max_copy_bytes. Provisioning is best-effort by design: the create response never waits on it, failures only log, and a retried copy skips files that already landed.

Pull request checkouts, dev ports, integration

worktree::create also takes pr: <number>: it fetches refs/pull/<n>/head from origin (GitHub layout) and branches <prefix>pr-<n> at it, so reviewing a PR gets its own isolated checkout. Every worktree carries an advisory dev_port (10000 + hash of the id mod 10000): deterministic, collision-improbable across parallel worktrees, and never reserved anywhere; point dev servers at it to avoid port fights. worktree::status reports integrated with an integration_reason (same_commit, ancestor, no_added_changes, trees_match, merge_adds_nothing, patch_id_match) so squash- or rebase-landed branches read as merged, and worktree::prune removes integrated-but-ahead worktrees instead of holding them forever.

Removal and trash

worktree::remove never blocks on a large directory delete: the worktree is renamed into a .trash staging area under worktree_root (instant), the git admin entry is pruned, and a detached task deletes the staged directory in the background; if the rename fails the removal falls back to a synchronous git worktree remove. Entries stranded by a crash are cleared by the next prune's trash sweep, which runs even when gates.allow_prune is off (it is remove's crash recovery, not part of prune's destructive surface). Unforced removals also probe for processes holding files open under the worktree and refuse with W222 rather than deleting a directory out from under a running dev server.

Gates

Every mutating handler checks its gate before anything else, so an operator can turn off whole classes of destruction with one config flip and the change hot-reloads. Denials are structured: W500 (operation disabled), W501 (force paths disabled), W502 (land target not allowed), and every message names the exact key to flip, e.g. worktree::remove is disabled by configuration; set gates.allow_remove: true to enable. Force is the one gate that ships closed: takeovers, forced removals, and land restarts are opt-in.

Creation is gated too: gates.repos pins which repositories worktrees may branch from (globs over the canonicalized path, W503 otherwise), and gates.max_worktrees_per_repo caps live worktrees per repository at create time (W504 names the current count; orphaned records do not count, and narrowing either gate later never breaks existing worktrees).

Gates constrain this worker's own surface only. Restricting what an agent can run in a shell (rm, git branch -D, ...) is the shell worker's allowlist/denylist job; pair both for defense in depth.

Filesystem scope interplay

Agents are scoped through metadata.fs_scope.root on the turn: the console picker (or harness::send options) sets it to the worktree path, and the harness stamps fs_scope: { root, grants } onto every scoped shell::* / coder::* call the agent makes. The land test gate does the same directly: it runs shell::exec with the worktree as cwd and as the fs_scope root, so the shell worker enforces the scope for gated tests exactly as it does for agent calls.

worktree_root must still resolve inside the shell worker's fs.host_roots: a root outside the jail fails with S215 (a path inside the jail but outside the scope root fails with S220), and the test gate surfaces the S215 misconfiguration as a W411 land block naming it.

Engine queue config

Land jobs serialize per repository through an engine FIFO queue. Add this block to the engine config (the repo_key group field is carried on every job payload):

queue_configs:
  worktree-land:
    type: fifo
    message_group_field: repo_key
    concurrency: 1
    max_retries: 2

Without it the queue still delivers, but ordering falls back to this worker's in-process per-repo lock, which only holds within a single instance.

Functions

  • worktree::create — mint a locked worktree off a ref; auto-claims when session_id is given.
  • worktree::list — registry view with filters and optional git status; reports unmanaged worktrees of a repo without adopting them.
  • worktree::get — one worktree with status.
  • worktree::validate — picker-style path validation; reconciles records whose directories are gone.
  • worktree::claim / worktree::release — session ownership with force takeover and W210/W211 mismatch errors.
  • worktree::status — clean, ahead/behind, staged/unstaged/untracked, diffstat, rebase-in-progress.
  • worktree::remove — guarded removal (W220 dirty, W221 unmerged, W222 busy), instant trash staging with background delete, optional branch deletion.
  • worktree::prune — reconcile sweep, run on every cron::on-tick of prune_schedule; {} payload works.
  • worktree::land — queue a land job; returns { job_id, queued }.
  • worktree::land-step — internal queue consumer; not agent-callable.
  • worktree::rest: internal target of the HTTP routes (below).

Errors carry stable W### codes (src/error.rs). One instance per engine: state has no compare-and-set, so run a single worktree worker (shard by repo if you need more).

Lifecycle events

Six private functions carry the lifecycle events: only this worker calls them, any worker observes them, and each handler returns the event it is called with. None takes args; iii delivers every call to each observer whose filters match. Every event carries repo_path and worktree_id, and session_id when a session is involved, so observers select with filters on input.repo_path, input.worktree_id and input.session_id. The worker calls a function only while it has observers.

Function Called when Event
worktree::on-created A worktree was minted CreatedEvent { worktree_id, repo_path, path, branch, base_ref, base_sha, session_id?, timestamp }
worktree::on-claimed A session took ownership ClaimedEvent { worktree_id, repo_path, session_id, previous_session_id?, timestamp }
worktree::on-released A claim was released ReleasedEvent { worktree_id, repo_path, session_id, timestamp }
worktree::on-removed A worktree was removed or pruned RemovedEvent { worktree_id, repo_path, branch, branch_deleted, session_id?, timestamp }
worktree::on-landed A land fast-forwarded the target LandedEvent { worktree_id, repo_path, branch, target_branch, merged_sha, session_id?, timestamp }
worktree::on-land-blocked A land ended blocked LandBlockedEvent { worktree_id, repo_path, target_branch, reason, code, conflict_files?, exit_code?, session_id?, timestamp }
use iii_sdk::{Capture, Source};
use serde_json::json;

// every land in one repository; the target reads the event at payload["output"]
iii.observe(
    Source::function("worktree::on-landed")
        .filters(json!({ "input.repo_path": { "$eq": "/home/me/project" } }))
        .capture([Capture::Output]),
    "notify::on-land",
);

Conflict resolution flow

When a land's rebase hits conflicts, the rebase is left IN PROGRESS inside the worktree and worktree::on-land-blocked is called with reason: "rebase_conflict" and the conflicted paths. The owning agent resolves in place (its filesystem scope already roots at the worktree), finishes with git rebase --continue, and reruns worktree::land. A rerun while the rebase is still unresolved returns W402; pass force_restart: true to abort the rebase, reset, and start the land over.

HTTP endpoints

With the http worker installed, the read surface is also served over HTTP: the worker observes http::on-request with { method: "POST", path } for /worktree/list, /worktree/get, /worktree/status and /worktree/validate, each targeting worktree::rest. It runs the function the path names (/worktree/get is worktree::get) with the request's JSON body as its input (an empty body is {}) and answers with the function's result as the response body, status 200. A body that is not JSON answers 400 W001 and runs no function. An error answers { "error": { "code", "message" } } with the status of its code:

Status code
400 W001 (also a body that is not JSON or does not fit the function's input), W110, W111, W112
403 W500-W504
404 W200, W201
409 W120, W210-W222, W401-W413
503 W300
504 W101
500 any other code
curl -s -X POST http://127.0.0.1:3111/worktree/get \
  -H 'content-type: application/json' -d '{"worktree_id":"wt_..."}'

Without an http worker those observers stay pending and the worker keeps serving the bus; a rejected route logs a warning.

Local development and testing

cargo run --release -- --url ws://127.0.0.1:49134
cargo test

The end-to-end tests boot a real engine and self-skip when iii is not on PATH (III_ENGINE_BIN names another binary). The REST test also runs the http worker, III_HTTP_BIN (cargo build --manifest-path ../http/Cargo.toml). Regenerate wire-schema goldens with UPDATE_GOLDENS=1 cargo test.

Search the registry

Find workers, kits and executables, or jump to a page.