v2: redesign filesystem snapshots around mutation epochs

Problem

V2 currently captures the Git worktree at the start of each physical LLM attempt and again at terminal settlement. This couples filesystem history to model orchestration rather than filesystem mutations.

Consequences:

• Text-only calls, read-only tools, retries, and adjacent steps perform redundant Git scans and write-tree calls.
• Changes from another session, a subagent, the user's editor, or an external process during the interval can be attributed to the assistant and later overwritten by revert.
• A crash after mutation but before terminal capture leaves a preimage without a changed-path manifest.
• Raw tree IDs lack project/worktree/location provenance, making movement and cross-worktree restoration fragile.
• Revert staging mutates the worktree before its recovery state is durably recorded.

Git content addressing means equal captures generally do not duplicate blobs or trees, so repeated clean captures primarily waste CPU and latency. Disk growth is a separate lifecycle problem: the local store measured about 1.2 GB across roughly 348 snapshot repositories/indexes and 126,000 loose objects, with no coherent V2 retention/GC policy.

Direction to grill

Model filesystem history as durable, mutation-owned epochs:

1. Open an epoch immediately before the first potentially mutating local tool, not before every model call.
2. Record exact touched paths for known mutations such as write/edit/patch.
3. Conservatively capture around shell, code execution, and opaque plugin tools.
4. Checkpoint or close the epoch after owned mutations settle.
5. Produce no filesystem snapshots for text-only calls, pre-output retries, compaction, or read-only tools.
6. Persist project/worktree/location provenance plus preimage, postimage, and expected current state.
7. Make revert write-ahead, recoverable, and conflict-aware instead of blindly restoring paths.

For storage, retain Git CAS but evaluate one shared object store per project, worktree-specific indexes, durable roots, packing, removed-worktree cleanup, and bounded age/budget retention.

Questions

• Is the mutation epoch scoped to one tool batch, one assistant message, or the full user turn?
• Do we serialize mutating tools, or allow parallel mutations behind one baseline/barrier?
• Which tools can declare exact touched paths, and which require conservative before/after capture?
• Should unrelated current-state edits cause a conflict, an inverse three-way apply, or an explicit force option?
• What snapshot-history guarantee do retained sessions receive under a bounded disk budget?
• How should open epochs be reconciled after process death?

Acceptance criteria

• Read-only/model-only attempts perform no filesystem capture.
• Every OpenCode-owned mutation has a durable preimage before side effects begin and recoverable path ownership afterward.
• Reverting one session cannot silently overwrite changes attributed to another actor.
• Session movement and worktree identity are explicit in snapshot restoration.
• Snapshot retention and missing-history behavior are documented and bounded.
• Crash and partial-stage failure tests cover recovery without losing the ability to clear a revert.

Related

• #36093
• #42597
• #32981
• #33940
• #35255
• #39513
• #37751
• #43774
• #43780

Start by tracing the existing V2 filesystem snapshot, mutation, revert, and retention flows, then review related issues #36093, #42597, #32981, #33940, #35255, #39513, #37751, #43774, and #43780. No file, test, or entry point is named, so first map the relevant code and tests. Done means mutation-owned durable epochs, provenance-aware recovery, conflict-safe revert behavior, bounded documented retention, and crash-recovery coverage.