feat(gc): add --snapshot LRU eviction flag

[CMGS]

Summary

Implements issue #33 (LRU snapshot GC + scheduled cleanup) by extending `cocoon gc` with opt-in LRU snapshot reclamation.

Flag	Effect
`--snapshot`	Bare flag: evict every non-pending snapshot
`--snapshot-keep N`	Keep N most-recently-accessed
`--snapshot-age DUR`	Evict snapshots last-accessed before DUR (e.g. `720h`)
`--snapshot-size SZ`	Evict oldest until total ≤ SZ (e.g. `100GB`)
`--dry-run`	Preview only

Sub-flags combine as union of evictions / intersection of kept — a snapshot survives only if it passes every active criterion. Mixing sub-flags without `--snapshot` is rejected.

What's added

• `snapshot.SnapshotRecord`: `LastAccessedAt` + `SizeBytes` fields. Touched on Restore / DataDir / Export; sized at Create / Import.
• `snapshot/localfile/gc.go`: `EvictionPolicy`, `pickLRU`, `logEvictions`, `cleanResolvedRecords` plus extended `gcModule` Resolve to apply LRU before returning candidates.
• `utils.DirSize` helper.
• `lookupRecord(ctx, ref, touch)` consolidates `resolveRecord` + `accessRecord` (deep-reuse).
• 13 new unit tests covering all policy combinations, dry-run, zero-time ordering, end-to-end via gcModule, and orphan dir cleanup.
• README "Snapshot LRU Eviction" + "Scheduled Snapshot GC" sections (systemd timer + cron templates).

Framework change (heads-up)

`gc.Module[S].Resolve` signature now takes `ctx` as the first arg — 6 implementations rippled (`hypervisor`, `images`, `network/bridge` linux+other, `network/cni`, `snapshot/localfile`). Needed so eviction logs reach the orchestrator ctx instead of `context.Background()`.

Design notes

• No back-compat for old records: zero `LastAccessedAt` sorts oldest and gets evicted first under `--snapshot-age`. Documented in the README.
• Pending records are still protected: `cleanResolvedRecords` only force-removes records that are non-pending; pending records still need the 24h `pendingGCGrace` window (protects in-flight Create).
• No daemon mode: scheduled execution delegated to systemd timer / cron — keeps `cocoon gc` a one-shot, lock-safe operation.

Verification

```
✓ make lint # 0 issues × Linux + Darwin
✓ go test ./... # all packages green; 13 new LRU tests pass
✓ /code SKILL line-by-line review (round 1: 6 issues fixed)
✓ /simplify 3 parallel agents (round 2: reuse + quality + efficiency, 2 actionable fixes)
```

Test plan

• On testbed: `cocoon gc --snapshot --snapshot-age=24h --dry-run` lists expected candidates
• `cocoon gc --snapshot --snapshot-keep=5` retains 5 most-recently-accessed
• `cocoon gc --snapshot --snapshot-size=10GB` enforces size cap
• Bare `cocoon gc --snapshot` deletes every non-pending snapshot
• `cocoon gc --snapshot-age=24h` (no `--snapshot`) errors out
• Existing `cocoon gc` behavior unchanged (orphans + stale-pending only)
• systemd timer template from README boots a daily `cocoon-gc.service`

[Copilot]

Pull request overview

Implements opt-in LRU snapshot reclamation in cocoon gc (issue #33 follow-up). Adds new CLI sub-flags driving an EvictionPolicy consumed by the localfile snapshot GC module, persists LastAccessedAt / SizeBytes on snapshot records, threads context.Context into every gc.Module.Resolve implementation, and documents systemd-timer / cron deployment patterns.

Changes:

• New --snapshot, --snapshot-keep|age|size, --snapshot-dry-run flags wired through cmd/others, parsed into localfile.EvictionPolicy, validated for negatives and required-with---snapshot.
• snapshot.SnapshotRecord gains LastAccessedAt + SizeBytes; touched on Restore/DataDir/Export, sized on Create/Import via new utils.DirSize. resolveRecord replaced with lookupRecord(ctx, ref, touch).
• snapshot/localfile/gc.go extended with pickLRU (union of age/keep/size, dry-run logging) and cleanResolvedRecords; gc.Module.Resolve signature now takes ctx, rippled across 6 backends.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
utils/file.go	Adds DirSize helper to sum regular file sizes under a tree.
snapshot/db.go	Adds SizeBytes and LastAccessedAt fields to SnapshotRecord.
snapshot/localfile/localfile.go	Adds Option/WithGCPolicy, replaces resolveRecord with lookupRecord, sizes & touches records on Create.
snapshot/localfile/import.go	Records SizeBytes + LastAccessedAt on Import.
snapshot/localfile/gc.go	Adds EvictionPolicy, pickLRU, logEvictions, cleanResolvedRecords; ctx-aware Resolve.
snapshot/localfile/gc_test.go	New unit tests covering LRU policy combinations, dry-run, end-to-end GC, orphan dirs.
gc/module.go, gc/runner.go, gc/orchestrator.go	Thread context.Context into Resolve / resolveTargets.
hypervisor/gc.go, images/gc.go, network/bridge/gc_{linux,other}.go, network/cni/gc.go	Update Resolve signature to accept ctx.
cmd/core/helpers.go	InitSnapshot accepts variadic localfile.Option.
cmd/others/commands.go	Defines new gc sub-flags.
cmd/others/handler.go	Parses sub-flags into EvictionPolicy, validates and wires to backend.
cmd/others/handler_test.go	Tests flag parsing (defaults, negatives, requires-snapshot, happy path).
README.md	New "Snapshot LRU Eviction" + "Scheduled Snapshot GC" sections.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 20 out of 20 changed files in this pull request and generated 4 comments.

Comments suppressed due to low confidence (1)

cmd/others/handler.go:95

• --snapshot-size is parsed with units.RAMInBytes, which interprets all SI-style suffixes as base-2 (e.g. 100GB → 100 × 2³⁰ ≈ 107 GB decimal), not base-10. The README example (--snapshot-size=100GB) and the flag help text (e.g. 100GB) don't tell the operator which interpretation is used, and "100GB" colloquially means 10⁹ bytes for most users when talking about disk usage. Either switch to units.FromHumanSize (decimal SI) or document explicitly that suffixes are binary (KiB/MiB/GiB semantics).

	if sizeStr != "" {
		n, err := units.RAMInBytes(sizeStr)
		if err != nil {
			return localfile.EvictionPolicy{}, fmt.Errorf("--snapshot-size %q: %w", sizeStr, err)
		}
		if n < 0 {
			return localfile.EvictionPolicy{}, fmt.Errorf("--snapshot-size must be >= 0, got %s", sizeStr)
		}
		size = n
	}

[Copilot]

Pull request overview

Copilot reviewed 20 out of 20 changed files in this pull request and generated 1 comment.