Cargo Worktree Hygiene

---
name: cargo-worktree-hygiene
description: Manages compilation concurrency, per-worktree target isolation, and disk safety when coordinating parallel Rust builders across multiple git worktrees. Use when dispatching fleet builders, creating Rust worktrees, or operating on storage-constrained environments.
---

# Cargo Worktree Hygiene

## Overview

When running autonomous agents in parallel across multiple git worktrees (e.g., during Playbook 4: Fleet Batch or multi-slice pipelines), compiling Rust crates naively leads to two critical system failure modes:
1. **CPU Thrashing & Starvation**: By default, `cargo` and `rustc` saturate all available CPU threads (`nproc`). When 3 or 4 builders run tests concurrently, 24–32 compilation threads compete aggressively for 8 physical cores, causing extreme scheduling latency, WebSocket timeouts, and build slowdowns.
2. **Disk Starvation (Storage Explosion)**: A full Cargo debug build target directory frequently consumes 7–12 GB. Four independent worktrees will consume 30–50 GB, quickly filling developer and CI disks and causing hard filesystem write failures. This skill controls disk use with the disk guard, the `hygiene` size report, `cargo sweep`, and worktree pruning.

`cargo-worktree-hygiene` eliminates both failure modes through four systematic practices enforced by tooling and fleet coordination.

---

## When to Use

- When dispatching 2 or more autonomous builders in parallel across git worktrees on a Rust repository.
- When working on machines or VMs with constrained storage (less than 30 GB free headroom).
- When configuring worktree provisioning in lead coordination scripts (`worktree.ts`).
- When diagnosing slow multi-agent compilation or unexpected test timeouts.

---

## Workflow: The 4 Hygiene Pillars

```mermaid
flowchart TD
    A["Pre-Flight Disk Guard (df / hygiene check)"] --> B{"Headroom >= 15 GB?"}
    B -- No --> C["Prune stale worktrees / cargo sweep"]
    B -- Yes --> D["Isolated target/ per worktree (pool config sets jobs only)"]
    D --> E["Throttled Concurrency (CARGO_BUILD_JOBS = nproc / builders)"]
    E --> F["Post-PR Teardown (remove worktree and scrub residual target)"]
```

### 1. Pre-Flight Disk Guard
Before spawning fleet builders or creating new worktrees, check filesystem headroom:
- **CLI Inspection**: Run `bun scripts/worktree.ts hygiene` to inspect disk space, the worktree pool, Cargo target isolation, and target sizes.
- **Critical Floor (5 GB)**: Never allow builders to proceed if available disk space is under 5 GB. `worktree create` will halt with an error unless overridden.
- **Warning Margin (15 GB)**: If disk space is under 15 GB, trigger maintenance:
  - Sweep old build artifacts: `cargo sweep -t 3d` (or `cargo sweep -i` for installed binaries).
  - Prune merged worktrees: `bun scripts/worktree.ts remove <branch> -d`.

### 2. Isolated Target per Worktree
Every worktree must compile into its own isolated `target/` directory:
- Worktrees should live in a unified sibling pool (e.g., `<repoRoot>/.worktrees/<branch>`).
- The worktree pool root contains `.worktrees/.cargo/config.toml` to configure CPU concurrency:
  ```toml
  # Generated by worktree.ts for Cargo concurrency hygiene. Each worktree keeps its own target/ directory.
  [build]
  jobs = 4
  ```
- **Stale Artifact Risk**: When worktrees share one target directory, Cargo gives workspace crates the same artifact names across checkouts using paths relative to the workspace root. Cargo determines freshness of local crates by file modification time rather than content hashing. When one worktree builds at time T and another worktree has older sources, Cargo marks the second worktree as fresh and executes stale artifacts from the first. This causes false test failures and incorrect test counts.
- **Build Serialization**: Sharing a target directory also does not accelerate parallel builds because Cargo locks `target/<profile>/` for the full duration of a build, serializing concurrent builders.
- **Dependency Caching**: For shared dependency caching across worktrees, use a content-hashed tool such as `sccache` (`RUSTC_WRAPPER=sccache`).
- **Target Overrides**: Do not export `CARGO_TARGET_DIR` across checkouts, as an exported path persists across shell directory changes and forces checkouts to share build artifacts. Clear overrides with `unset CARGO_TARGET_DIR CARGO_BUILD_TARGET_DIR CARGO_BUILD_BUILD_DIR`.

### 3. Concurrency Throttling (`CARGO_BUILD_JOBS`)
Calculate CPU core budgets before dispatching parallel builders:
- **Formula**:
  $$\text{CARGO\_BUILD\_JOBS} = \max\left(1, \left\lfloor \frac{\text{nproc}}{\text{active\_builders}} \right\rfloor\right)$$
- **Helper**: Use `bun scripts/worktree.ts env <active_builders>` to generate exact shell export commands. The command prints `export CARGO_BUILD_JOBS=<n>` and `unset CARGO_TARGET_DIR CARGO_BUILD_TARGET_DIR CARGO_BUILD_BUILD_DIR` to clear shared target overrides.
  - Example (8 physical cores, 2 active builders):
    `export CARGO_BUILD_JOBS=4`
  - Example (8 physical cores, 4 active builders):
    `export CARGO_BUILD_JOBS=2`
- Pass `CARGO_BUILD_JOBS` explicitly in the builder dispatch prompt or environment.
- When running integration tests that bind TCP/WebSocket ports or shared hardware mocks, enforce serialized test execution: `cargo test -- --test-threads=1`.

### 4. Post-PR Cleanup & Scrubbing
- When a PR is approved and merged, immediately remove the worktree:
  `bun scripts/worktree.ts remove <branch> -d`
- Every worktree maintains a local `target/` directory; `bun scripts/worktree.ts remove` automatically purges `<worktree>/target` before git pruning to prevent disk bloat.