Harden branch recovery and cleanup retention

[aaltshuler]

Summary

• centralize Lance native branch create/delete classification around authoritative BranchContents and exact BranchIdentifier observations
• reclaim clone-only create residue, classify lost acknowledgements, fence delete/recreate ABA, and enforce path-prefix-disjoint live branch names at the lower control chokepoint
• preserve a leaf-first recovery path for legacy ancestor/child overlaps without deleting descendant storage
• make version cleanup preserve exact main-table versions inherited by live lazy graph branches, derive --keep cutoffs from available versions, and fail closed before GC on unresolved recovery, unopenable pins, or uncovered main HEAD drift
• align RFC-022, RFC-025, architecture, testing, and user/operator documentation with the shipped behavior

Why

Lance branch creation first materializes a shallow clone and then publishes the authoritative ref; deletion removes the ref before reclaiming the tree. An interrupted or ambiguously acknowledged native operation therefore needs classification from fresh authority rather than blind retry or cleanup.

Separately, a lazy OmniGraph branch can inherit an exact main-table version without owning a native Lance table branch. Cleanup previously had no native ref from which to discover that live pin and could prune it.

Impact

Branch controls remain native Lance operations and do not manufacture graph commits or a second branch authority. Same-process operations are serialized through the existing schema → branch → table gate envelope.

Cleanup can retain additional versions required by live branches and now refuses unsafe graph-wide preflight states before deleting any version. Per-table GC remains fault-isolated after that preflight.

Validation

• cargo test --workspace --locked
• cargo test -p omnigraph-engine --features failpoints --test failpoints --locked — 82 passed
• branching suite — 34 passed
• maintenance suite — 30 passed
• branch-control unit truth cells — 8 passed
• scripts/check-agents-md.sh
• git diff --check

---

Greptile Summary

This PR hardens branch recovery and cleanup retention across OmniGraph. The main changes are:

• Native Lance branch create/delete classification through BranchContents authority.
• Prefix-disjoint branch names and safer path-child cleanup handling.
• Recovery updates for clone-only branch residue and rollback cleanup ordering.
• Cleanup retention for live lazy branch pins and unsafe preflight states.
• Updated tests and docs for the new recovery and maintenance behavior.

Confidence Score: 5/5

This looks safe to merge.

• No blocking issues found in the changed code.

Important Files Changed

Filename	Overview
crates/omnigraph/src/db/manifest/recovery.rs	Recovery now defers legacy path-child cleanup explicitly and blocks rollback when owned effects cannot be cleaned safely.
crates/omnigraph/src/branch_control.rs	New branch-control helpers classify native create/delete outcomes from authoritative Lance branch metadata.
crates/omnigraph/src/db/omnigraph/optimize.rs	Cleanup now accounts for live lazy branch pins and fails before GC when protected versions cannot be classified.

_{Reviews (2): Last reviewed commit: "Fail closed on blocked partial rollback" | Re-trigger Greptile}

Context used:

• Context used - AGENTS.md (source)
• Context used - CLAUDE.md (source)

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.