v2: redesign filesystem snapshots around mutation epochs

[kitlangton]

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

• v2: define snapshot retention and disk GC policy #36093
• "Snapshot mechanism stalls on large workspaces: ~1min per git snapshot, permanent index.lock deadlock after a crash" #42597
• Snapshot on home directory hangs opencode indefinitely #32981
• Undo in one session reverts all sessions #33940
• Session-create unrevert can restore a snapshot from another worktree #35255
• Snapshot restore from a subdirectory can overwrite sibling files #39513
• V2 session revert can race with session execution #37751
• fix(core): reduce snapshot Git scans #43774
• fix(core): coordinate snapshot writers #43780

[luizfneves404]

Related user-facing gap: revert the conversation while keeping file changes (the "undo message only" ask on #7963 / #16447, closed by inactivity). Since this redesign defines the snapshot/revert surface, should that be a revert mode at the epoch/message level without restoring files, or is it explicitly out of scope? Would implementing the feature have to wait until this redesign is done? I really wanted to have this ability, and others too as mentioned in #7963

[Dante-dan]

I traced the current v2 path before suggesting an implementation boundary. SessionProcessor.create() captures before llm.stream(), and step-finish captures again; each Snapshot.track() scans changed/untracked paths and runs write-tree, even when the attempt never mutates files. The stream event is also too late for ownership: the AI SDK can execute a tool before step-start. The earlier usable boundary is the SessionTools.resolve() execute wrapper, before tool.execute.before and the tool implementation.

I suggest a bounded first slice:

• Scope one epoch to one mutating tool invocation, not a whole message/turn. Serialize mutating invocations by worktree initially; read-only tools remain concurrent.
• Classify built-ins as read-only, exact-path (write, edit, apply_patch), or opaque (shell, code execution, plugin tools). Exact paths come from validated input; opaque tools use a conservative whole-worktree pre/post capture.
• Persist an open epoch keyed by worktree plus session/message/call provenance before any plugin hook or tool side effect. Settlement records postimage, owned paths, and expected current state. A process restart leaves an explicit reconciliation record rather than attributing whatever is currently on disk.
• Make revert write-ahead: persist the restore plan and expected-current hashes before touching files. A mismatch becomes a conflict in this first slice—no silent overwrite or force fallback—then completion/clear is persisted after the worktree operation.
• Keep retention/shared-object-store policy and “undo message only” outside this first slice. Preserve the scoped-restore behavior from fix(snapshot): severe data loss on restore from a subdirectory #45141 while the epoch model is introduced.

I would verify behavior with integration tests that assert: model-only/retry/read-only paths invoke no snapshot Git work; the durable preimage happens before a mutating side effect; concurrent sessions serialize worktree mutations; an external edit causes a conflict instead of being overwritten; and crashes before/after restore leave a recoverable operation that can still be cleared.

If this tool-invocation scope and conflict-first first slice matches the intended design, please approve it and assign me; I can implement it without starting the retention or message-only-undo work.