Worktrees vs LayerFS
Allternit's git worktree pain points, what LayerFS does about each, and the fix we can build now
Lead: Most of our worktree pain comes from one gap. A worktree copies the source but not the build state, so every agent rebuilds or shares target/ and node_modules/. LayerFS fixes that with a deduplicated store. APFS copy-on-write clones on this Mac do most of the same today, with no new filesystem.
Today, measured
kv cols=3
Disk: 798 GB used, 98 GB free (90%)
Worktrees: 31 (10 platform, 21 allternit-ai)
Biggest: desktop-build 57 GB, .shared-target 33 GB, wt-art-rt 21 GB
Manual cleanups: 5 since 2026-09-30, each freeing 100–170 GB
Factory create: plain git worktree add, with no dependency or build setup
Pain points, ranked
| # | Pain | Evidence | What LayerFS does | Fix we can build now |
|---|---|---|---|---|
| 1 | Disk fills with build output | 100% full 2026-09-30 from ~127 worktrees; 61 GB target in minutes 2026-10-09 | Content is stored once; unmount drops the overlay | Clone target/ and node_modules/ from a warm base with APFS cp -c; disk is spent only on changes |
| 2 | Each worktree starts cold | pnpm install 30 s, 26 min under swap; Rust rebuilds per tree | Dependencies come with every mount | The same clone gives a warm tree in about 1 s |
| 3 | .shared-target gives false passes |
AGENTS.md exception: crates overwrite each other, tests pass on other code | Each workspace has its own overlay | A per-worktree cloned target ends the need for a shared one |
| 4 | Shared checkout gets corrupted | Commit 850a31905 reverted 86 files; Desktop shipped UI 164 commits old; salvage branches | main is a read-only layer |
Keep the shared checkout read-only and synced to origin/main; save stray edits to a salvage branch automatically |
| 5 | Cleanup is manual and risky | merged + idle + lsof rules; bfs -newermt gotcha; Eoj stopped removal of live trees |
Unmount ends the workspace; history stays | A lease per worktree plus a reaper that applies the merged-and-idle rule in code |
| 6 | Dev servers and builds swamp the Mac | fseventsd 32 GB from 6 vite servers left 3–9 days; build starvation | Compute exists only while a command runs | Dev servers get a TTL from the same lease; workers stay code-only |
| 7 | Conflicts show up at merge time | Parallel Factory branches merged one by one by hand | Conflicting commits are refused per file | Warn early when two active branches change the same file |
| 8 | No undo for one bad agent step | Only git commits the agent chose to make | Every tool call is a checkpoint | A hook saves git stash create to refs/checkpoints/ after each edit |
Clone test on this Mac
callout ok APFS clone works here
cp -c -R copied .shared-target/debug/deps (4.6 GB) in 0.91 s and used about 47 MB of disk. The clone shares blocks until a file changes, which is the core LayerFS storage idea for one machine.
Still to test: cargo stores absolute paths, so workspace crates rebuild after a clone; crates.io deps stay warm. pnpm links must resolve from the new path.
Proposed flow
Where LayerFS itself fits
- Not on the Mac now: macOS goes only through DeepSeek Harness, and the store has no crash durability.
- Later, on Linux cloud computers: Factory remote workers could share one store across machines. This is where the clone fix cannot reach.
- Borrow the ideas, not the code: checkpoint per step, lease per workspace, refuse conflicts early.
Build order
- Seed by clone in
factory/pane/src/worktree.rsandsession-worktree.sh: warm base,cp -c, test the cargo and pnpm paths. Biggest win. - Lease + reaper: owner marker, TTL, merged-and-idle check in code, dev server TTL.
- Read-only shared checkout: sync to origin/main, auto-salvage stray edits.
- Overlap warning in Factory merge_locks.
- Checkpoint refs hook, shown in Agent watch and Teach Replay.