Worktree Isolation

In-Tree Tasks Get Managed Worktrees

When the daemon dispatches a task workflow backed by the built-in task store, Animus creates a dedicated git worktree for that task. This lets an agent write code, run tests, and commit without interfering with other running tasks or the main checkout.

Tasks resolved from an installed subject_backend plugin are different: the workflow runtime can resolve them by subject id, but there is no in-tree task record to provision against, so execution stays in project_root unless the plugin manages its own checkout strategy.

---

Managed Worktree Path

Worktrees are stored under the repository-scoped state directory:

~/.animus/<repo-scope>/worktrees/<task-id>/

Where <repo-scope> is the sanitized repository name plus a SHA-256 hash prefix (see State Management for the scoping rules).

For example:

~/.animus/my-saas-a1b2c3d4e5f6/worktrees/TASK-042/

---

Managed Branch Naming

Each managed worktree gets a dedicated branch:

animus/<sanitized-task-id>

For example, task TASK-042 gets branch animus/task-042. The task ID is sanitized to lowercase with special characters replaced by hyphens, using the same sanitize_identifier function used for repository scoping.

---

Isolation Guarantees

Because built-in task execution runs in its own worktree:

• No file conflicts -- Two agents implementing different tasks modify files independently.
• Independent test runs -- cargo test (or any test command) runs against the task's own working tree.
• Clean git history -- Each task's commits are on its own branch, making PRs clean and reviewable.
• No main branch pollution -- The main checkout stays untouched while tasks execute.

---

Worktree Lifecycle

A built-in task subject and a plugin-owned subject take different cwd paths, and merge/PR work happens as ordinary command phases (not runner automation) before the worktree is pruned:

1. Create

When the daemon spawns workflow-runner for a built-in task subject, it creates a git worktree from the current main branch. The worktree is checked out to a new branch named animus/<task-id>.

2. Execute

For built-in task subjects, all workflow phases run inside the worktree directory. Agents can:

• Read and write files
• Run build and test commands
• Create git commits
• Access MCP tools

The agent's working directory is set to the managed worktree path.

For plugin-owned task subjects, the execution cwd is project_root. That keeps plugin-backed task workflows runnable even when the plugin does not expose an Animus-managed worktree path.

3. Post-success actions

The post_success.merge block (and auto_merge) was removed in v0.5.x — Animus no longer performs git operations (commit, push, PR, merge) as runner automation, and a workflow YAML that still sets post_success.merge is rejected at parse time. Express commit, push, and PR creation as ordinary command phases that run git or gh in the task worktree:

phases:
  create-pr:
    mode: command
    directive: Open a GitHub PR from the current branch
    command:
      program: gh
      args: ["pr", "create", "--fill", "--base", "main"]
      cwd_mode: task_root

A human still merges the PR. See Workflow YAML.

4. Cleanup

After a run, clean up managed worktrees for done/cancelled tasks with animus git worktree prune. If cleanup is not run, the worktree persists for manual inspection.

---

Merge Conflict Recovery

If the task branch has conflicts with the target branch, workflow-runner can attempt AI-powered conflict resolution as a workflow phase. The merge recovery logic detects conflicts, presents them to an agent, and the agent resolves them before committing.

If automatic resolution fails, the workflow is marked as blocked and the conflict is reported for manual intervention.

---

Managing Worktrees

animus git worktree list          # List active worktrees
animus git worktree prune         # Remove managed worktrees for done/cancelled tasks
animus doctor --check orphan_cli_processes  # Detect orphaned CLI processes in stale worktrees

The daemon performs orphan recovery on startup for workflows whose runner processes are no longer alive, but it skips workflows started within the last 90 seconds so async workflow run dispatch has time to register its pid/run metadata before reconciliation.