gitvow 0.4.0__tar.gz → 0.5.0__tar.gz

{gitvow-0.4.0/src/gitvow.egg-info → gitvow-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitvow
-Version: 0.4.0
+Version: 0.5.0
 Summary: Provenance and policy gate for AI-agent coding sessions: session trailers on commits, redacted session notes in git, a tool-call gate, and a local ledger. No runtime dependencies.
 Author-email: Nikhil Bora <nikhil@wirevow.com>
 License: Apache-2.0

{gitvow-0.4.0 → gitvow-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gitvow"
-version = "0.4.0"
+version = "0.5.0"
 description = "Provenance and policy gate for AI-agent coding sessions: session trailers on commits, redacted session notes in git, a tool-call gate, and a local ledger. No runtime dependencies."
 readme = "README.md"
 license = {text = "Apache-2.0"}

{gitvow-0.4.0 → gitvow-0.5.0}/src/gitvow/cli.py

@@ -9,6 +9,7 @@ import re
 import sys
 
 from . import __version__
+from . import snapshots as snap
 from .collect import collect, summarize_text
 from .hooks import HANDLERS, LEGACY_NOTES_REF, notes_ref
 from .install import install_repo, install_user, uninstall_repo, uninstall_user
@@ -44,7 +45,7 @@ def cmd_uninstall(a: argparse.Namespace) -> int:
     done = (
         uninstall_user(os.path.expanduser("~"), a.purge_policy, a.purge_ledger)
         if a.user
-        else uninstall_repo(os.path.abspath(a.repo), a.purge_notes)
+        else uninstall_repo(os.path.abspath(a.repo), a.purge_notes, a.purge_snapshots)
     )
     print("\n".join(done))
     return 0
@@ -130,6 +131,61 @@ def cmd_report(a: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_snapshots(a: argparse.Namespace) -> int:
+    cwd = os.getcwd()
+    if a.sub == "prune":
+        days = None
+        if a.older_than:
+            m = re.fullmatch(r"(\d+)([dh]?)", a.older_than)
+            if not m:
+                print("--older-than takes a number of days, e.g. 14d", file=sys.stderr)
+                return 1
+            days = int(m.group(1)) / (24 if m.group(2) == "h" else 1)
+        print(f"pruned {snap.prune(cwd, days, a.session)} snapshot(s)")
+        return 0
+    rows = snap.list_snapshots(cwd, a.session)
+    if not rows:
+        print("no snapshots" + (f" for session {a.session}" if a.session else ""))
+        return 0
+    cur = None
+    for r in rows:
+        if r["session"] != cur:
+            cur = r["session"]
+            print(f"session {cur[:8]}   {sum(1 for x in rows if x['session'] == cur)} snapshots")
+            print("  n    taken                tool        file                                  changed vs HEAD")
+        print(
+            f"  {r['n']:<4d} {r['taken']:<20s} {r['tool']:<11s} {r['file'][:37]:<37s} {r['changed_files']} file{'s' if r['changed_files'] != 1 else ''}"
+        )
+    return 0
+
+
+def _resolve_or_fail(a: argparse.Namespace) -> str | None:
+    ref = snap.resolve(os.getcwd(), a.session, a.n)
+    if not ref:
+        print(f"no snapshot {a.n} for a unique session matching {a.session!r}", file=sys.stderr)
+    return ref
+
+
+def cmd_diff(a: argparse.Namespace) -> int:
+    ref = _resolve_or_fail(a)
+    if not ref:
+        return 1
+    print(snap.diff(os.getcwd(), ref, a.full))
+    return 0
+
+
+def cmd_restore(a: argparse.Namespace) -> int:
+    ref = _resolve_or_fail(a)
+    if not ref:
+        return 1
+    rc, msg = snap.restore(os.getcwd(), ref, a.to)
+    print(
+        f"restored {ref} into {msg} (detached worktree; remove with: git worktree remove {msg})" if rc == 0 else msg,
+        file=sys.stderr if rc else sys.stdout,
+    )
+    return rc
+
+
 def cmd_push_notes(a: argparse.Namespace) -> int:
     import subprocess
 
@@ -176,6 +232,7 @@ def main(argv: list[str] | None = None) -> int:
     s.add_argument("--purge-notes", action="store_true")
     s.add_argument("--purge-policy", action="store_true")
     s.add_argument("--purge-ledger", action="store_true")
+    s.add_argument("--purge-snapshots", action="store_true")
     s.set_defaults(f=cmd_uninstall)
     s = sub.add_parser("check", help="dry-run the policy: gitvow check -- git push --force")
     s.add_argument("command", nargs="*")
@@ -199,6 +256,24 @@ def main(argv: list[str] | None = None) -> int:
     s.add_argument("--json", action="store_true")
     s.add_argument("--require-notes", action="store_true")
     s.set_defaults(f=cmd_report)
+    s = sub.add_parser(
+        "snapshots", help="list working-tree snapshots taken after agent edits; 'snapshots prune' deletes"
+    )
+    s.add_argument("sub", nargs="?", choices=["prune"])
+    s.add_argument("--session")
+    s.add_argument("--all", action="store_true")
+    s.add_argument("--older-than")
+    s.set_defaults(f=cmd_snapshots)
+    s = sub.add_parser("diff", help="what the agent had changed at snapshot n: gitvow diff <session> <n>")
+    s.add_argument("session")
+    s.add_argument("n", type=int)
+    s.add_argument("--full", action="store_true")
+    s.set_defaults(f=cmd_diff)
+    s = sub.add_parser("restore", help="check a snapshot out into a detached scratch worktree")
+    s.add_argument("session")
+    s.add_argument("n", type=int)
+    s.add_argument("--to")
+    s.set_defaults(f=cmd_restore)
     s = sub.add_parser("push-notes", help="push refs/notes/gitvow/* to a remote (default origin)")
     s.add_argument("remote", nargs="?", default="origin")
     s.set_defaults(f=cmd_push_notes)

{gitvow-0.4.0 → gitvow-0.5.0}/src/gitvow/hooks/__init__.py

@@ -8,6 +8,7 @@ import re
 import time
 from typing import Any
 
+from .. import snapshots
 from ..policy import PolicyError, evaluate, load_policy, message_for
 from ..redact import RedactionError, load_rules, redact
 from ..state import git, load_state, log_event, save_state, toplevel
@@ -15,7 +16,7 @@ from ..transcript import summarize
 
 NOTES_REF_PREFIX = "gitvow"  # refs/notes/gitvow/<session-id>; gitvow 0.1 wrote the single ref refs/notes/sessions
 LEGACY_NOTES_REF = "sessions"
-NOTE_SCHEMA = 2
+NOTE_SCHEMA = 3
 COMMIT_RE = re.compile(r"\bgit\s+commit\b")
 EDIT_TOOLS = ("Edit", "Write", "MultiEdit", "NotebookEdit")
 REDACTION_UNAVAILABLE = "redaction rules invalid; nothing written for this event"
@@ -37,6 +38,8 @@ def session_start(h: dict[str, Any], home: str | None = None) -> tuple[int, str]
             "started": st.get("started") if same_session and st.get("started") else time.strftime("%Y-%m-%dT%H:%M:%S"),
             "steps": st.get("steps", 0) if same_session else 0,
             "agent_blobs": st.get("agent_blobs", {}) if same_session else {},
+            "snapshots": st.get("snapshots", 0) if same_session else 0,
+            "last_snapshot": st.get("last_snapshot") if same_session else None,
         }
     )
     st.pop("pending_commit", None)
@@ -160,8 +163,18 @@ def post_tool_use(h: dict[str, Any], home: str | None = None) -> tuple[int, str]
     tool = h.get("tool_name")
     inp = h.get("tool_input") or {}
     if tool in EDIT_TOOLS:
-        if inp.get("file_path"):
-            _record_agent_blob(cwd, str(inp["file_path"]))
+        fp = str(inp.get("file_path") or inp.get("notebook_path") or "")
+        if fp:
+            _record_agent_blob(cwd, fp)
+        try:
+            pol = load_policy(cwd, home)
+        except PolicyError:
+            pol = {}
+        cfg = snapshots.settings(pol)
+        if cfg.get("enabled", True):
+            ref = snapshots.take(cwd, h.get("session_id") or load_state(cwd).get("session_id"), tool, fp, cfg)
+            if ref:
+                log_event(cwd, "snapshot", {"ref": ref, "tool": tool})
         return 0, ""
     if tool != "Bash" or not COMMIT_RE.search(inp.get("command", "")):
         return 0, ""
@@ -194,6 +207,7 @@ def post_tool_use(h: dict[str, Any], home: str | None = None) -> tuple[int, str]
         "files_in_commit": [ln.strip() for ln in files.splitlines()[:-1]][:50] if files else [],
         "files_written_by_agent_this_session": [f["path"] for f in attribution["files"] if f["agent_wrote"]][:50],
         "attribution": attribution,
+        "snapshot": st.get("last_snapshot"),
         "transcript": "kept local; see ledger",
         "redaction": "secrets/PII patterns, high-entropy tokens and custom rules replaced at write time",
     }

{gitvow-0.4.0 → gitvow-0.5.0}/src/gitvow/install.py

@@ -189,7 +189,7 @@ def install_repo(repo: str, cmd_prefix: str = "gitvow") -> list[str]:
     ]
 
 
-def uninstall_repo(repo: str, purge_notes: bool = False) -> list[str]:
+def uninstall_repo(repo: str, purge_notes: bool = False, purge_snapshots: bool = False) -> list[str]:
     done = []
     unmerge_settings(os.path.join(repo, ".claude", "settings.json"))
     rc, cur, _ = git(["config", "--get", "core.hooksPath"], repo)
@@ -210,5 +210,9 @@ def uninstall_repo(repo: str, purge_notes: bool = False) -> list[str]:
         for ref in refs.split():
             git(["update-ref", "-d", ref], repo)
         done.append(f"{len(refs.split())} local session note ref(s) deleted (remote copies untouched)")
+    if purge_snapshots:
+        from . import snapshots as _snap
+
+        done.append(f"{_snap.purge_all(repo)} snapshot ref(s) deleted")
     done.append(".gitvow removed; commit trailers already in history remain")
     return done

{gitvow-0.4.0 → gitvow-0.5.0}/src/gitvow/policy.py

@@ -65,6 +65,9 @@ def _validate(pol: dict[str, Any], path: str) -> None:
                 re.compile(pat)
             except re.error as e:
                 raise PolicyError(f"{path}: bad regex in {key}: {pat} ({e})") from e
+    snap = pol.get("snapshots", {})
+    if not isinstance(snap, dict) or not isinstance(snap.get("exclude", []), list):
+        raise PolicyError(f"{path}: snapshots must be an object with an optional 'exclude' list")
     provs = pol.get("providers", [])
     if not isinstance(provs, list):
         raise PolicyError(f"{path}: providers must be a list")

{gitvow-0.4.0 → gitvow-0.5.0}/src/gitvow/selftest.py

@@ -88,6 +88,16 @@ def run() -> int:
         with open(os.path.join(repo, "a.txt"), "a") as fh:
             fh.write("b\n")
         post_tool_use({**base, "tool_name": "Edit", "tool_input": {"file_path": "a.txt"}}, home)
+        snaps = g("for-each-ref", "--format=%(refname)", "refs/gitvow/snapshots/").splitlines()
+        results.append(
+            (len(snaps) == 1 and snaps[0].endswith("/selftest-session/1"), "snapshot taken after the agent edit")
+        )
+        results.append(
+            (
+                g("show", f"{snaps[0]}:a.txt") == "a\nb" if snaps else False,
+                "snapshot holds the agent's version of the file",
+            )
+        )
         with open(os.path.join(repo, "a.txt"), "a") as fh:
             fh.write("human\n")
         pre_tool_use({**base, "tool_name": "Bash", "tool_input": {"command": "git commit -m x"}}, home)

gitvow-0.5.0/src/gitvow/snapshots.py

@@ -0,0 +1,183 @@
+"""Working-tree snapshots after agent edits: commits under refs/gitvow/snapshots/<session>/<n>, parented on HEAD."""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import re
+import subprocess
+import tempfile
+import time
+from typing import Any
+
+from .state import git, git_dir, load_state, save_state, toplevel
+
+REF_PREFIX = "refs/gitvow/snapshots"
+DEFAULTS: dict[str, Any] = {
+    "enabled": True,
+    "max_per_session": 200,
+    "exclude": [".env*", "*.pem", "*.key", "*secret*", "*credential*", ".gitvow/**", ".claude/**"],
+}
+
+
+def settings(pol: dict[str, Any] | None) -> dict[str, Any]:
+    out = dict(DEFAULTS)
+    out.update((pol or {}).get("snapshots") or {})
+    return out
+
+
+def _safe(session_id: str | None) -> str:
+    return re.sub(r"[^A-Za-z0-9._-]", "_", session_id or "unknown")
+
+
+def ref_for(session_id: str | None, n: int) -> str:
+    return f"{REF_PREFIX}/{_safe(session_id)}/{n}"
+
+
+def take(cwd: str, session_id: str | None, tool: str, file_path: str, cfg: dict[str, Any]) -> str | None:
+    """Write the working tree (minus ignored and excluded paths) as a commit and point a new session ref at it."""
+    top = toplevel(cwd)
+    gd = git_dir(cwd)
+    if not top or not gd:
+        return None
+    rc, head, _ = git(["rev-parse", "--verify", "HEAD"], top)
+    parent = head if rc == 0 else None
+    st = load_state(cwd)
+    n = int(st.get("snapshots", 0)) + 1
+    fd, tmp_index = tempfile.mkstemp(prefix="gitvow-index-", dir=gd)
+    os.close(fd)
+    os.remove(tmp_index)
+    env = {**os.environ, "GIT_INDEX_FILE": tmp_index}
+    try:
+        if parent:
+            subprocess.run(["git", "read-tree", parent], cwd=top, env=env, capture_output=True, check=False)
+        pathspec = ["--", "."] + [f":(exclude,glob){p}" for p in cfg.get("exclude", [])]
+        r = subprocess.run(
+            ["git", "add", "-A", *pathspec], cwd=top, env=env, capture_output=True, text=True, timeout=60, check=False
+        )
+        if r.returncode != 0:
+            return None
+        r = subprocess.run(["git", "write-tree"], cwd=top, env=env, capture_output=True, text=True, check=False)
+        if r.returncode != 0:
+            return None
+        tree = r.stdout.strip()
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    finally:
+        with contextlib.suppress(OSError):
+            os.remove(tmp_index)
+    rel = os.path.relpath(os.path.realpath(file_path), os.path.realpath(top)) if file_path else ""
+    msg = json.dumps(
+        {
+            "gitvow": "snapshot",
+            "session": session_id,
+            "n": n,
+            "tool": tool,
+            "file": rel,
+            "taken": time.strftime("%Y-%m-%dT%H:%M:%S"),
+        }
+    )
+    args = ["commit-tree", tree, "-m", msg] + (["-p", parent] if parent else [])
+    rc, commit, _ = git(args, top)
+    if rc != 0:
+        return None
+    ref = ref_for(session_id, n)
+    git(["update-ref", ref, commit], top)
+    st["snapshots"] = n
+    st["last_snapshot"] = ref
+    save_state(cwd, st)
+    keep = int(cfg.get("max_per_session", 200))
+    if n > keep:
+        git(["update-ref", "-d", ref_for(session_id, n - keep)], top)
+    return ref
+
+
+def list_snapshots(cwd: str, session_id: str | None = None) -> list[dict[str, Any]]:
+    top = toplevel(cwd) or cwd
+    prefix = f"{REF_PREFIX}/{_safe(session_id)}/" if session_id else REF_PREFIX + "/"
+    rc, out, _ = git(["for-each-ref", "--format=%(refname)%09%(objectname)%09%(contents:subject)", prefix], top)
+    rows: list[dict[str, Any]] = []
+    if rc != 0:
+        return rows
+    for line in out.splitlines():
+        parts = line.split("\t", 2)
+        if len(parts) < 3:
+            continue
+        ref, commit, subject = parts
+        try:
+            meta = json.loads(subject)
+        except json.JSONDecodeError:
+            meta = {}
+        _, stat, _ = git(["diff", "--shortstat", f"{commit}^", commit], top)
+        m = re.match(r"\s*(\d+) file", stat or "")
+        rows.append(
+            {
+                "ref": ref,
+                "commit": commit,
+                "session": meta.get("session") or ref.split("/")[-2],
+                "n": int(meta.get("n") or ref.split("/")[-1]),
+                "tool": meta.get("tool", ""),
+                "file": meta.get("file", ""),
+                "taken": meta.get("taken", ""),
+                "changed_files": int(m.group(1)) if m else 0,
+            }
+        )
+    rows.sort(key=lambda r: (r["session"], r["n"]))
+    return rows
+
+
+def resolve(cwd: str, session_prefix: str, n: int) -> str | None:
+    """Full ref for a session id or unique prefix and a snapshot number."""
+    top = toplevel(cwd) or cwd
+    rc, out, _ = git(["for-each-ref", "--format=%(refname)", REF_PREFIX + "/"], top)
+    if rc != 0:
+        return None
+    hits = {r.rsplit("/", 1)[0] for r in out.split() if r.split("/")[-2].startswith(_safe(session_prefix))}
+    if len(hits) != 1:
+        return None
+    ref = f"{hits.pop()}/{n}"
+    rc, _, _ = git(["rev-parse", "--verify", "--quiet", ref], top)
+    return ref if rc == 0 else None
+
+
+def diff(cwd: str, ref: str, full: bool = False) -> str:
+    top = toplevel(cwd) or cwd
+    args = ["diff"] + ([] if full else ["--stat"]) + [f"{ref}^", ref]
+    rc, out, err = git(args, top)
+    return out if rc == 0 else err
+
+
+def restore(cwd: str, ref: str, to: str | None = None) -> tuple[int, str]:
+    top = toplevel(cwd) or cwd
+    if not to:
+        sess, n = ref.split("/")[-2], ref.split("/")[-1]
+        to = os.path.join(tempfile.gettempdir(), "gitvow-restore", f"{sess[:8]}-{n}")
+    if os.path.exists(to) and os.listdir(to):
+        return 1, f"{to} exists and is not empty; choose another --to"
+    os.makedirs(os.path.dirname(to) or ".", exist_ok=True)
+    rc, _, err = git(["worktree", "add", "--detach", to, ref], top)
+    if rc != 0:
+        return 1, err
+    return 0, to
+
+
+def prune(cwd: str, older_than_days: float | None = None, session_id: str | None = None) -> int:
+    top = toplevel(cwd) or cwd
+    cutoff = time.time() - (older_than_days or 0) * 86400 if older_than_days is not None else None
+    removed = 0
+    for row in list_snapshots(cwd, session_id):
+        if cutoff is not None:
+            try:
+                taken = time.mktime(time.strptime(row["taken"], "%Y-%m-%dT%H:%M:%S"))
+            except (ValueError, TypeError):
+                taken = 0
+            if taken > cutoff:
+                continue
+        git(["update-ref", "-d", row["ref"]], top)
+        removed += 1
+    return removed
+
+
+def purge_all(cwd: str) -> int:
+    return prune(cwd, None, None)

{gitvow-0.4.0 → gitvow-0.5.0/src/gitvow.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitvow
-Version: 0.4.0
+Version: 0.5.0
 Summary: Provenance and policy gate for AI-agent coding sessions: session trailers on commits, redacted session notes in git, a tool-call gate, and a local ledger. No runtime dependencies.
 Author-email: Nikhil Bora <nikhil@wirevow.com>
 License: Apache-2.0

{gitvow-0.4.0 → gitvow-0.5.0}/src/gitvow.egg-info/SOURCES.txt

@@ -12,6 +12,7 @@ src/gitvow/providers.py
 src/gitvow/redact.py
 src/gitvow/report.py
 src/gitvow/selftest.py
+src/gitvow/snapshots.py
 src/gitvow/state.py
 src/gitvow/transcript.py
 src/gitvow.egg-info/PKG-INFO
@@ -28,4 +29,5 @@ tests/test_packaging.py
 tests/test_policy.py
 tests/test_providers.py
 tests/test_redact.py
-tests/test_report.py
+tests/test_report.py
+tests/test_snapshots.py

{gitvow-0.4.0 → gitvow-0.5.0}/tests/test_hooks.py

@@ -43,7 +43,7 @@ def test_commit_flow_trailer_note_and_attribution(repo, home, payload, transcrip
     note = git(repo, "notes", "--ref=gitvow/sess-1", "show", "HEAD")
     assert note.startswith("gitvow-session")
     data = json.loads(note.split("\n", 1)[1])
-    assert data["schema"] == 2 and data["step"] == 1 and data["tools_used"] == ["Bash", "Edit"]
+    assert data["schema"] == 3 and data["step"] == 1 and data["tools_used"] == ["Bash", "Edit"]
     assert "[github-token]" in data["last_stated_plan"] and "[email:" in data["last_stated_plan"]
     assert "ghp_" not in note and "ops@example.com" not in note
     att = data["attribution"]

gitvow-0.5.0/tests/test_snapshots.py

@@ -0,0 +1,136 @@
+import json
+import os
+
+from gitvow import cli
+from gitvow.hooks import post_tool_use, pre_tool_use, session_start
+from gitvow.install import _write_git_hook, uninstall_repo
+from tests.conftest import git
+
+
+def _edit(repo, home, payload, name, content, tool="Edit"):
+    (repo / name).parent.mkdir(parents=True, exist_ok=True)
+    (repo / name).write_text(content)
+    post_tool_use(payload("PostToolUse", tool, {"file_path": str(repo / name)}), str(home))
+
+
+def test_snapshot_per_edit_with_head_parent_and_exclusions(repo, home, payload):
+    session_start(payload("SessionStart"), str(home))
+    (repo / ".gitignore").write_text("build/\n")
+    (repo / "build").mkdir()
+    (repo / "build" / "out.o").write_text("bin")
+    (repo / ".env").write_text("SECRET=1\n")
+    _edit(repo, home, payload, "calc.py", "def add(a, b):\n    return a + b\n")
+    _edit(repo, home, payload, "calc.py", "def add(a, b):\n    return a + b\n\ndef sub(a, b):\n    return a - b\n")
+    refs = git(repo, "for-each-ref", "--format=%(refname)", "refs/gitvow/snapshots/").split()
+    assert refs == ["refs/gitvow/snapshots/sess-1/1", "refs/gitvow/snapshots/sess-1/2"]
+    head = git(repo, "rev-parse", "HEAD")
+    assert git(repo, "rev-parse", "refs/gitvow/snapshots/sess-1/1^") == head  # parented on HEAD at the time
+    assert git(repo, "show", "refs/gitvow/snapshots/sess-1/1:calc.py") == "def add(a, b):\n    return a + b"
+    assert "sub" in git(repo, "show", "refs/gitvow/snapshots/sess-1/2:calc.py")
+    tree = git(repo, "ls-tree", "-r", "--name-only", "refs/gitvow/snapshots/sess-1/2")
+    assert "calc.py" in tree and ".gitignore" in tree and "build/out.o" not in tree and ".env" not in tree
+    (repo / ".gitvow").mkdir(exist_ok=True)
+    (repo / ".gitvow" / "policy.json").write_text("{}")
+    _edit(repo, home, payload, "calc.py", "v3\n")
+    assert ".gitvow/policy.json" not in git(repo, "ls-tree", "-r", "--name-only", "refs/gitvow/snapshots/sess-1/3")
+    assert git(repo, "status", "--short").count("\n") >= 0  # the real index was never touched
+    assert "calc.py" not in git(repo, "diff", "--cached", "--name-only")
+    st = json.loads((repo / ".git" / "gitvow-session.json").read_text())
+    assert st["snapshots"] == 2 and st["last_snapshot"] == "refs/gitvow/snapshots/sess-1/2"
+    assert '"kind": "snapshot"' in (repo / ".git" / "gitvow-hooks.log").read_text()
+
+
+def test_note_names_last_snapshot_and_new_session_restarts_numbering(repo, home, payload):
+    session_start(payload("SessionStart"), str(home))
+    _edit(repo, home, payload, "a.txt", "agent\n")
+    _write_git_hook(str(repo / ".gitvow" / "git-hooks"))
+    git(repo, "config", "core.hooksPath", ".gitvow/git-hooks")
+    pre_tool_use(payload("PreToolUse", "Bash", {"command": "git commit -m x"}), str(home))
+    git(repo, "commit", "-qam", "agent commit")
+    post_tool_use(payload("PostToolUse", "Bash", {"command": "git commit -m x"}), str(home))
+    note = json.loads(git(repo, "notes", "--ref=gitvow/sess-1", "show", "HEAD").split("\n", 1)[1])
+    assert note["schema"] == 3 and note["snapshot"] == "refs/gitvow/snapshots/sess-1/1"
+    p = payload("SessionStart")
+    p["session_id"] = "sess-2"
+    session_start(p, str(home))
+    (repo / "a.txt").write_text("two\n")
+    post_tool_use({**p, "tool_name": "Write", "tool_input": {"file_path": str(repo / "a.txt")}}, str(home))
+    assert git(repo, "rev-parse", "--verify", "refs/gitvow/snapshots/sess-2/1")
+
+
+def test_cli_list_diff_restore_prune(repo, home, payload, monkeypatch, capsys, tmp_path):
+    session_start(payload("SessionStart"), str(home))
+    _edit(repo, home, payload, "calc.py", "v1\n")
+    _edit(repo, home, payload, "calc.py", "v2\n", tool="Write")
+    (repo / "calc.py").write_text("human v3\n")
+    monkeypatch.chdir(repo)
+    assert cli.main(["snapshots"]) == 0
+    out = capsys.readouterr().out
+    assert "session sess-1   2 snapshots" in out and "Write" in out and "calc.py" in out
+    assert cli.main(["diff", "sess", "1"]) == 0
+    assert "calc.py" in capsys.readouterr().out
+    assert cli.main(["diff", "sess", "1", "--full"]) == 0
+    assert "+v1" in capsys.readouterr().out
+    dest = tmp_path / "restore-here"
+    assert cli.main(["restore", "sess", "1", "--to", str(dest)]) == 0
+    assert (dest / "calc.py").read_text() == "v1\n"
+    assert (repo / "calc.py").read_text() == "human v3\n"  # the real tree is untouched
+    assert cli.main(["restore", "sess", "1", "--to", str(dest)]) == 1  # refuses a non-empty dir
+    assert cli.main(["diff", "nope", "1"]) == 1
+    assert cli.main(["diff", "sess", "9"]) == 1
+    git(repo, "worktree", "remove", "--force", str(dest))
+    assert cli.main(["snapshots", "prune", "--older-than", "14d"]) == 0
+    assert "pruned 0" in capsys.readouterr().out
+    assert cli.main(["snapshots", "prune", "--session", "sess-1"]) == 0
+    assert "pruned 2" in capsys.readouterr().out
+    assert cli.main(["snapshots"]) == 0 and "no snapshots" in capsys.readouterr().out
+
+
+def test_retention_disable_and_purge(repo, home, payload):
+    (repo / ".gitvow").mkdir()
+    (repo / ".gitvow" / "policy.json").write_text(json.dumps({"snapshots": {"max_per_session": 2}}))
+    session_start(payload("SessionStart"), str(home))
+    for i in range(4):
+        _edit(repo, home, payload, "a.txt", f"v{i}\n")
+    refs = git(repo, "for-each-ref", "--format=%(refname)", "refs/gitvow/snapshots/").split()
+    assert [r.split("/")[-1] for r in refs] == ["3", "4"]
+    (repo / ".gitvow" / "policy.json").write_text(json.dumps({"snapshots": {"enabled": False}}))
+    _edit(repo, home, payload, "a.txt", "v9\n")
+    assert len(git(repo, "for-each-ref", "refs/gitvow/snapshots/").split("\n")) == 2
+    uninstall_repo(str(repo), purge_snapshots=True)
+    assert git(repo, "for-each-ref", "refs/gitvow/snapshots/") == ""
+
+
+def test_pre_push_does_not_push_snapshots(repo, home, payload, tmp_path):
+    remote = tmp_path / "remote.git"
+    git(remote.parent, "init", "-q", "--bare", str(remote))
+    git(repo, "remote", "add", "origin", str(remote))
+    _write_git_hook(str(repo / ".gitvow" / "git-hooks"))
+    git(repo, "config", "core.hooksPath", ".gitvow/git-hooks")
+    session_start(payload("SessionStart"), str(home))
+    _edit(repo, home, payload, "a.txt", "x\n")
+    git(repo, "notes", "--ref=gitvow/sess-1", "add", "-m", "gitvow-session\n{}", "HEAD")
+    git(repo, "push", "-q", "origin", git(repo, "branch", "--show-current"))
+    remote_refs = git(remote, "for-each-ref", "--format=%(refname)")
+    assert "refs/notes/gitvow/sess-1" in remote_refs and "snapshots" not in remote_refs
+
+
+def test_invalid_snapshots_policy_fails_closed(repo, home, payload):
+    (repo / ".gitvow").mkdir()
+    (repo / ".gitvow" / "policy.json").write_text(json.dumps({"snapshots": "yes please"}))
+    code, msg = pre_tool_use(payload("PreToolUse", "Bash", {"command": "ls"}), str(home))
+    assert code == 2 and "snapshots must be an object" in msg
+
+
+def test_snapshot_in_repo_without_commits(tmp_path, home, payload):
+    r = tmp_path / "fresh"
+    r.mkdir()
+    git(r, "init", "-q")
+    (r / "f.txt").write_text("first\n")
+    p = payload("SessionStart")
+    p["cwd"] = str(r)
+    session_start(p, str(home))
+    post_tool_use({**p, "tool_name": "Write", "tool_input": {"file_path": str(r / "f.txt")}}, str(home))
+    ref = git(r, "for-each-ref", "--format=%(refname)", "refs/gitvow/snapshots/")
+    assert ref.endswith("/1") and git(r, "show", f"{ref}:f.txt") == "first"
+    assert os.path.exists(r / ".git")