Polymath Zero

Docs · Execution

Worktrees

Every Work item runs inside an isolated git worktree. This prevents branch contention when multiple Work items are active simultaneously.

Why per-Work worktrees

Zero uses git worktree to give each Work item its own working directory and branch. This means:

  • Sessions on different Work items never share a working tree — no file conflicts.
  • The main checkout stays clean while Work items are in progress.
  • Multiple Work items can be in IMPLEMENTING state at the same time without interference.
Each worktree is per-machine. Worktrees are not shared across devices or team members in the current release.

Where it lives

Worktrees are created inside the Zero memory root, under a directory named after the Work item's ID:

zero-memory/worktrees/<work-id>/

The branch name is generated by the /api/worktrees/branch-name endpoint before the worktree is created.

Branch naming

Call POST /api/worktrees/branch-name to generate a branch name before attaching a worktree. The name is derived from the Work item's title and ID to ensure uniqueness.

POST /api/worktrees/branch-name
Body: { "case_id": "<work-id>", "title": "auth timeout fix" }
→ { "branch": "zero/auth-timeout-fix-001a" }

Stale cleanup

Worktrees become stale when a Work item is resolved or when a session exits uncleanly. Two endpoints manage cleanup:

EndpointAction
GET /api/worktrees/staleList all worktrees with no active lock and no recent session activity.
POST /api/worktrees/cleanupRemove stale worktrees from disk. Operator-triggered — not automatic.
Cleanup is always operator-triggered. Zero does not automatically delete worktrees — even after a Work item reaches RESOLVED.

Verify isolation

Before a session starts Work mode, isolation can be verified:

POST /api/worktrees/:case_id/verify-isolation
→ { "isolated": true, "branch": "zero/auth-timeout-fix-001a", "clean": true }

This checks that no uncommitted changes from other sessions are present and that the worktree branch has not diverged unexpectedly.

API reference

MethodEndpointPurpose
POST/api/worktreesCreate a new worktree for a Work item.
POST/api/worktrees/:case_id/attachAttach an existing worktree to a Work item.
DELETE/api/cases/:id/worktreeRemove the worktree association from a Work item.
GET/api/worktrees/:case_id/healthCheck worktree health (branch status, lock state).
GET/api/worktrees/:case_id/statusCurrent working tree status (modified files, staged).
POST/api/worktrees/:case_id/verify-isolationConfirm isolation before starting Work mode.
GET/api/worktrees/staleList stale worktrees.
POST/api/worktrees/cleanupRemove stale worktrees.
POST/api/worktrees/branch-nameGenerate a branch name for a new worktree.
GET|PUT/api/worktrees/configRead or update worktree configuration.
GET/api/worktrees/:case_id/memory-rootReturn the memory root path for a Work item's worktree.