Isolated coding worktrees

Isolated coding worktrees

Holaryn gives each mutating Code session and unattended coding job its own Git worktree by default.
The checkout, branch, lease, recorded base revision, validation evidence, and integration state are
durable. Two agents can therefore work on the same repository without sharing modified files,
checkpoints, terminals, or repository-index namespaces.

Choose a workspace mode

In the Code tab, choose the mode in New code session. The Workspace panel then shows the
recorded base, candidate, and target revisions as one integration path. Background
start_coding_task calls use isolated for edits and read_only for safe unless the caller
chooses a mode explicitly. Completed background jobs report a worktree_id; the checkout remains
available for review instead of being silently merged or deleted.

current with shared_policy: true is an expert escape hatch. It makes collisions possible and is
never selected implicitly.

Disk use and durable identity

Managed checkouts live below:

<Holaryn state directory>/coding-worktrees/<repository hash>/<worktree id>/

Lifecycle rows, atomic leases, validation evidence, conflicts, archive paths, and explicit
multi-repository root mappings live in:

<Holaryn state directory>/coding-worktrees.sqlite3

A Git worktree shares the repository's object database but has a separate checkout, index, and
branch. Its disk use is therefore mainly checked-out files, generated dependencies, build output,
and untracked artifacts. Run holaryn worktree list or open the Code Workspace panel before
removing anything manually.

New worktrees start from a committed revision. Untracked files—including untracked secret files—
are not copied from the original checkout. If a task needs generated or ignored inputs, recreate
them deliberately inside that worktree without putting credentials in prompts, logs, or commits.

Review, validate, and integrate

Start with a comparison:

holaryn worktree compare wt_1234abcd

The returned plan fixes the recorded base, current candidate and target revisions, commit IDs and
subjects, changed files, dirty state, drift/conflicts, patch fingerprint, and plan_sha256.
Validation is bound to that exact patch fingerprint:

holaryn worktree validate wt_1234abcd
holaryn worktree validate wt_1234abcd --commands-json "[[\"uv\",\"run\",\"pytest\"]]"

The default validation is git diff --check against the recorded base. Custom commands are JSON
argument arrays, not shell command strings. If the candidate changes, previous validation no
longer unlocks integration.

After reviewing the current comparison, choose one strategy:

holaryn worktree integrate wt_1234abcd adopt --plan-sha256 PLAN --target-revision TARGET --approve
holaryn worktree integrate wt_1234abcd apply --plan-sha256 PLAN --target-revision TARGET --approve
holaryn worktree integrate wt_1234abcd merge --plan-sha256 PLAN --target-revision TARGET --approve

• adopt fast-forwards the target and refuses when fast-forward is impossible.
• apply cherry-picks the reviewed candidate commits in order.
• merge creates a non-fast-forward merge commit.

The explicit --approve, reviewed plan digest, and target revision are all required. Holaryn
recomputes the plan immediately before mutation and refuses stale candidates, target drift, dirty
targets, missing validation, or conflicts. It never force-pushes, hard-resets, or silently
overwrites the target.

The Code Workspace panel provides the same compare, validate, strategy, and exact confirmation
flow. The authenticated API mirrors it under
/api/code/sessions/{chat_id}/worktree/{compare,validate,integrate}.

Drift and conflicts

Target-branch drift appears in the next comparison. Review the new target revision and either
merge/apply the independent histories or rebase the isolated candidate:

holaryn worktree rebase wt_1234abcd start --plan-sha256 PLAN --target-revision TARGET --approve

If Git reports conflicts, the session enters conflict and records the affected paths. Resolve
them inside the isolated worktree and continue with:

holaryn worktree rebase wt_1234abcd continue

Or restore the candidate to its pre-rebase state:

holaryn worktree rebase wt_1234abcd abort

Integration failures are aborted before returning control. The target is not destructively reset;
the candidate and conflict evidence remain available for review.

Restart, missing paths, and recovery

At host startup Holaryn reconciles every durable worktree row with Git:

• a valid checkout has its lease restored;
• an externally deleted checkout is marked missing;
• mismatched or unreadable repository metadata is marked corrupt;
• archived sessions remain preserved without an active lease.

Inspect and recover with:

holaryn worktree status wt_1234abcd
holaryn worktree recover wt_1234abcd

Holaryn can recreate a missing checkout only when it owns the managed path and its branch still
exists. An external worktree or deleted branch is reported honestly for manual repair. Explicit
root mappings (--root api=/path/to/api) are persisted and validated; Holaryn does not guess how
separate repositories relate.

Archive, abandon, and safe cleanup

Use archive when you want to stop work but preserve every file:

holaryn worktree archive wt_1234abcd

This releases the lease and records the recoverable path without removing the checkout.
abandon --archive is the safe choice for a dirty or unintegrated candidate.

Use cleanup only after successful integration:

holaryn worktree cleanup wt_1234abcd

Cleanup removes a checkout only when all of these are true:

• Holaryn created and owns the managed path;
• Git still registers that exact path and it is not locked;
• the worktree is clean and has no unresolved conflicts; and
• candidate commits are integrated.

Otherwise cleanup exits with a refusal and an archive/recovery recommendation. Holaryn never
recursively deletes an unrecognized directory and never removes an existing worktree it merely
attached. The Code panel places archive and cleanup behind explicit confirmations and closes the
Code session before releasing or removing its checkout.