Snapshot Dirty Worktrees

Before integration begins, Kavi checks each agent worktree for uncommitted changes. Any dirty state is committed as a snapshot:

codex worktree:
  - 3 staged files, 1 unstaged modification
  - Snapshot commit: abc1234 "kavi: snapshot codex worktree"

claude worktree:
  - Clean (no uncommitted changes)

Snapshots ensure no work is lost during the merge process. Snapshot commits are marked with a kavi: prefix so they can be identified in the git history.

Integration Worktree

Kavi maintains a transient integration worktree specifically for merging. This worktree:

• Starts from the current head of your target branch (e.g., main)
• Is separate from both agent worktrees and your main working directory
• Is used exclusively for the merge and validation process
• Is reset between landing attempts

Merge Agent Changes

Kavi merges each agent's changes into the integration worktree. The merge strategy depends on the nature of the changes:

• Non-overlapping changes -- applied cleanly via merge
• Overlapping changes -- Kavi attempts automatic resolution; if conflicts arise, the operator is notified and can resolve manually

The merge order is determined by task dependencies in the plan. Tasks that were completed first are merged first, establishing a clear base for later merges.

Validation

After merging, Kavi runs your configured validation command in the integration worktree:

validation_command = "npm test"

The validation command should be a comprehensive check that verifies the integrated code is correct. Common choices:

• npm test or pnpm test -- run the test suite
• npm run build && npm test -- build and test
• make check -- custom validation script
• A script that runs linting, type checking, and tests

If validation fails:

• The landing is aborted
• The integration worktree is preserved for inspection
• The failure details are included in the landing report
• Agent worktrees are not affected (they retain their changes)

You can fix issues and retry the landing after addressing validation failures.

Fast-Forward Target Branch

On successful validation, Kavi fast-forwards your target branch to the integration worktree's head:

Before:
  main: A ─── B ─── C

After:
  main: A ─── B ─── C ─── D (merged codex + claude changes)

The fast-forward is a safe operation -- it only moves the branch pointer forward. If the target branch has moved since the session started (someone else pushed commits), Kavi will rebase the integration onto the new head and re-run validation.

Landing Report

Every landing attempt generates a report that includes:

• Status -- success or failure
• Merged branches -- which agent worktrees were included
• Validation output -- stdout/stderr from the validation command
• Conflict details -- any merge conflicts encountered and how they were resolved
• Commit hashes -- the final commit on the target branch
• Timestamp -- when the landing completed

Landing reports are persisted in the session state and can be reviewed through the TUI or by inspecting the .kavi/ directory.