AceLM Workspace Isolation & Worktree Policy
This is a product design policy, not verification of implemented runtime isolation.
Core Architecture: Branches vs. Isolated Worktrees
In agentic development, concurrent agents require strictly isolated workspaces:
- A Git branch records a line of commit history.
- An Isolated Worktree (IWT) provides a distinct working directory with its own working files, staging index, and
HEAD, while sharing the underlying Git object storage.
A branch alone is insufficient for concurrent agent execution: two agents editing the same local checkout will overwrite each other's uncommitted files, even if their intended commits target different branches. AceLM therefore pairs task branches with isolated worktrees for every independently mutable agent task.
Workspace Allocation Matrix
| Activity | Default Workspace | Isolation Purpose |
|---|---|---|
| Authoring Specs & Plans | Dedicated IWT on an artifact/run branch | Isolates lifecycle metadata and document authoring. |
| Executing Implementation | Dedicated IWT on a task branch | Isolates source code modifications, build artifacts, and local tests. |
| Adversarial Review (RA) | Separate reviewer session on a pinned snapshot | Prevents Authoring Agent context contamination and prevents moving-target reviews. |
| Independent Verification (VA) | Separate verifier workspace pinned to EA result commit | Verifies actual repository outputs and prevents verifier side effects from polluting EA work. |
| Plan-Set Integration | Dedicated orchestration worktree | Serializes integration of child branches and validates combined results. |
Ownership, Leases, and Crash Recovery
- Single-Writer Leases and Fencing: Every workspace is assigned a single active owner, run ID, and fencing token to prevent concurrent multi-agent write collisions (Gate G15). Stale mutation authority is revoked before allocating replacement workers.
- Persistent Daemons and Disconnect Safety: Execution processes run under background process supervision. A dropped terminal connection or SSH disconnect does not terminate active tasks, declare process death, or discard worktree state.
- Confirmed Death vs. Uncertain Liveness: Missing heartbeats, unreachable hosts, or terminal disconnects do not justify
diedorfail-diedtransitions on their own. Startup and periodic reconciliation confirm worker identity and termination using durable run records, host/boot IDs, process-start timestamps, and ownership leases (Gate G35). - Post-Failure Preservation Invariant: In the event of a test failure, crash, power loss, reboot, or interrupt, worktrees, branches, checkpoints, uncommitted diffs, and execution logs are strictly preserved for inspection and recovery.
diednever means discard or blindly reexecute; recovery resumes only unestablished work. - Recover-Before-Cleanup: Worktrees cannot be pruned or removed while uncommitted diffs or unintegrated commits remain (Gate G39). Cleanup failures do not revoke valid product completions.
- Attributed Publication: Lifecycle status transitions are published through the central transition service with optimistic concurrency checks and portable metadata commits.
Security and Sandboxing Boundaries
Git worktrees provide filesystem isolation for concurrent agent tasks. They are not security sandboxes. They share operating system processes, network access, environment variables, and filesystem access outside the repository root. AceLM layers credential redaction, scoped permissions, and isolated process groups on top of Git worktrees to enforce secure multi-agent execution.