v2: define snapshot retention and disk GC policy #36093

Activity

1. opencode-agent

   added

   2.0

   on Jul 9, 2026
2. Dante-dan commented on Oct 2, 2026

   

   Dante-dan

   on Oct 2, 2026

   Contributor

   More actions

   I suggest a strong guarantee for available snapshots referenced by recoverable durable session state, with a first slice that only adds protection. #51996 explicitly leaves retention/GC policy out; its capture/compaction work would remain separate.

   Proposed contract:

   • Snapshot age alone must not make a recoverable session's undo/diff history disappear. Persisted message snapshot start/end and the session's revert snapshot are roots. The root inventory must also include snapshot references in durable events used for supported replay/recovery: deleting a projected message row is not evidence that its objects are safe to collect.
   • Pin each new snapshot tree, including its reachable trees/blobs, in the correct project snapshot store before publishing its durable reference. Use durable Git refs rather than only an in-memory set. The snapshot-store write protocol must serialize pinning with any future collector; a failure to pin must not publish a newly promised recoverable snapshot.
   • For existing stores, add pins for available referenced trees before enabling any destructive collection. Inventory projected state and replayable events, report missing objects separately, and make the backfill resumable/idempotent. A partial inventory or interrupted migration must never authorize pruning.
   • Missing legacy objects cannot be restored by migration. Preserve session text/history, return an explicit snapshot-unavailable result for operations requiring absent objects, and never report a successful undo that did not restore its target.

   The first implementation would not remove pins or prune objects, change retention defaults, or add a disk budget. Compaction may pack objects but must preserve this reachable closure. Session deletion, event compaction, shared snapshot references/forks, and a later budget policy need an explicit release rule before collection is introduced; a database row's disappearance alone would not be that rule. A future budget should surface pressure rather than silently discard reachable undo history. This makes the initial change additive and keeps current capture/diff/restore behavior for available objects.

   Acceptance cases for that first slice: a snapshot older than seven days survives an explicit Git prune/GC and still produces the same diff/restore result; restart preserves pins; two durable references to the same tree remain usable; revert state stays protected after message projection trimming; interruption between pinning and persistence leaves at worst an extra protected tree; interrupted backfill never enables deletion; and a missing legacy tree gives a recoverable unavailable result without changing the session or claiming a successful restore. The historical root inventory is a prerequisite to claiming migration coverage, not something this proposal assumes is already complete.

   Could the core team review this strong-reachability contract and approve the non-destructive pinning/backfill first slice? In particular, should the supported replayable event history remain a root until an explicit event-retention decision releases it?
3. kobayashiHawtin commented on Oct 11, 2026

   

   kobayashiHawtin

   on Oct 11, 2026

   More actions

   Additional field evidence for the retention/GC gap (verified on v2.0.25, Windows 11).

   Snapshot store (%USERPROFILE%\.local\share\opencode\snapshot\) before cleanup:

   566.7 MB / 132,570 files across 24 per-project gitdirs
   oldest snapshot:  2026-05-27
   newest snapshot:  today
   

   Nothing is reclaimed over months — the oldest per-project gitdir had not been touched since 2026-05-27 despite the machine being in active use.

   Two concrete observations relevant to the policy question:

   1. The per-project gitdir is keyed by a project-family hash, and one hash holds the snapshots of every worktree of that project. Example: a single hash held 13 snapshots / 243.8 MB for one project family. So the unit of reclaim is the project family, not the session or worktree.

   2. There is no reconciliation against deleted sessions/worktrees. I found snapshot gitdirs whose core.worktree no longer exists on disk (e.g. ...\my_dev\_od-probe, ...\my_dev\item-images); their newest snapshot was ~1 month old and nothing reaped them. So orphaned snapshots from removed projects persist indefinitely.

   I manually removed the stale/orphaned per-project gitdirs (133.8 MB freed), but nothing prevents unbounded regrowth: retention is only age-based at the Git object level (git gc --prune=...), and there is no user-facing opencode snapshot prune command or age/size retention config (the snapshot config is a single boolean).

   Interim mitigation question (same as the issue): would an explicit retention knob (age/size) or a maintenance command be acceptable before the reachability-pin design lands? That would let users bound the store without disabling snapshots entirely.
4. lovasoa commented on Oct 22, 2026

   

   lovasoa

   on Oct 22, 2026

   More actions

   If you are considering a GC, please also look at git worktrees disk usage ! If I'm correct, currently old git worktrees just accumulate forever.