gitvow 0.6.0__tar.gz → 0.7.1__tar.gz

{gitvow-0.6.0/src/gitvow.egg-info → gitvow-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitvow
-Version: 0.6.0
+Version: 0.7.1
 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.6.0 → gitvow-0.7.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gitvow"
-version = "0.6.0"
+version = "0.7.1"
 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.6.0 → gitvow-0.7.1}/src/gitvow/cli.py

@@ -9,6 +9,7 @@ import re
 import sys
 
 from . import __version__
+from . import recall as rec
 from . import snapshots as snap
 from .collect import collect, summarize_text
 from .hooks import HANDLERS, LEGACY_NOTES_REF, notes_ref
@@ -211,6 +212,26 @@ def cmd_restore(a: argparse.Namespace) -> int:
     return rc
 
 
+def cmd_why(a: argparse.Namespace) -> int:
+    print(rec.why(os.getcwd(), a.path))
+    return 0
+
+
+def cmd_trace(a: argparse.Namespace) -> int:
+    print(rec.trace(os.getcwd(), a.spec))
+    return 0
+
+
+def cmd_recall(a: argparse.Namespace) -> int:
+    print(rec.recall(os.getcwd(), a.words, None, a.limit))
+    return 0
+
+
+def cmd_handoff(a: argparse.Namespace) -> int:
+    print(rec.handoff(os.getcwd(), a.session))
+    return 0
+
+
 def cmd_push_notes(a: argparse.Namespace) -> int:
     import subprocess
 
@@ -304,6 +325,19 @@ def main(argv: list[str] | None = None) -> int:
     s.add_argument("n", type=int)
     s.add_argument("--to")
     s.set_defaults(f=cmd_restore)
+    s = sub.add_parser("why", help="which sessions shaped a file: commits, plans, attribution")
+    s.add_argument("path")
+    s.set_defaults(f=cmd_why)
+    s = sub.add_parser("trace", help="who wrote these lines: gitvow trace path[:start-end]")
+    s.add_argument("spec")
+    s.set_defaults(f=cmd_trace)
+    s = sub.add_parser("recall", help="sessions whose notes or ledger mention the words")
+    s.add_argument("words", nargs="+")
+    s.add_argument("--limit", type=int, default=10)
+    s.set_defaults(f=cmd_recall)
+    s = sub.add_parser("handoff", help="markdown summary for the next agent")
+    s.add_argument("--session")
+    s.set_defaults(f=cmd_handoff)
     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.7.1/src/gitvow/recall.py

@@ -0,0 +1,285 @@
+"""The record answers the next session: why, trace, recall, handoff. Read-only over trailers, notes, snapshots, ledger."""
+
+from __future__ import annotations
+
+import glob
+import json
+import os
+import re
+from typing import Any
+
+from .hooks import LEGACY_NOTES_REF, notes_ref
+from .report import STEP_RE, TRAILER_RE
+from .snapshots import list_snapshots
+from .state import git, load_state, toplevel
+
+MAX_PLAN = 200
+
+
+def _note(cwd: str, sha: str, sid: str) -> dict[str, Any] | None:
+    for ref in (notes_ref(sid), LEGACY_NOTES_REF):
+        rc, body, _ = git(["notes", f"--ref={ref}", "show", sha], cwd)
+        if rc == 0 and body.startswith("gitvow-session"):
+            try:
+                return json.loads(body.split("\n", 1)[1])
+            except (json.JSONDecodeError, IndexError):
+                return None
+    return None
+
+
+def _commits(cwd: str, path: str | None = None, limit: int = 200) -> list[dict[str, Any]]:
+    args = ["log", f"-{limit}", "--format=%H%x00%ad%x00%s%x00%B%x01", "--date=short"]
+    if path:
+        args += ["--follow", "--", path]
+    rc, out, _ = git(args, cwd)
+    rows: list[dict[str, Any]] = []
+    if rc != 0:
+        return rows
+    for rec in out.split("\x01"):
+        rec = rec.strip("\n")
+        if not rec.strip():
+            continue
+        sha, date, subject, body = rec.split("\x00", 3)
+        m = TRAILER_RE.search(body)
+        row: dict[str, Any] = {
+            "sha": sha,
+            "short": sha[:7],
+            "date": date,
+            "subject": subject,
+            "kind": "person",
+            "session": None,
+            "step": None,
+            "note": None,
+        }
+        if m:
+            sm = STEP_RE.search(body)
+            row.update(
+                {
+                    "kind": "agent",
+                    "session": m.group(1),
+                    "step": int(sm.group(1)) if sm else None,
+                    "note": _note(cwd, sha, m.group(1)),
+                }
+            )
+        rows.append(row)
+    return rows
+
+
+def _plan(note: dict[str, Any] | None) -> str:
+    p = ((note or {}).get("last_stated_plan") or "").strip().replace("\n", " ")
+    return (p[: MAX_PLAN - 1] + "…") if len(p) > MAX_PLAN else p
+
+
+def why(cwd: str, path: str) -> str:
+    top = toplevel(cwd) or cwd
+    rel = os.path.relpath(os.path.abspath(path), top) if os.path.isabs(path) else path
+    rows = _commits(top, rel)
+    if not rows:
+        return f"{rel}: no commits found"
+    agent = [r for r in rows if r["kind"] == "agent"]
+    sessions = {r["session"] for r in agent}
+    lines = [
+        f"{rel} · {len(agent)} agent commit{'s' if len(agent) != 1 else ''}, {len(rows) - len(agent)} human commit{'s' if len(rows) - len(agent) != 1 else ''}, {len(sessions)} session{'s' if len(sessions) != 1 else ''}",
+        "",
+    ]
+    snaps = {s["ref"] for s in list_snapshots(top) if s.get("file") == rel}
+    for r in rows[:30]:
+        if r["kind"] == "person":
+            lines.append(f"{r['date']}  {r['short']}  (person)  {r['subject'][:70]}")
+            continue
+        att = (r["note"] or {}).get("attribution") or {}
+        share = att.get("agent_share")
+        human = att.get("lines_changed_by_human_after_agent") or 0
+        extra = f"agent share {share:.2f}" if isinstance(share, (int, float)) else "attribution n/a"
+        if human:
+            extra += f" · {human} line{'s' if human != 1 else ''} changed by a person afterwards"
+        step = f"step {r['step']}" if r["step"] is not None else ""
+        lines.append(f"{r['date']}  {r['short']}  session {r['session'][:8]} {step:<8} {extra}")
+        plan = _plan(r["note"])
+        lines.append(
+            f"  {plan}"
+            if plan
+            else "  (no plan stated before committing)"
+            if r["note"]
+            else "  (session note not available; run gitvow push-notes on the author's machine)"
+        )
+    if snaps:
+        lines += [
+            "",
+            f"{len(snaps)} snapshot{'s' if len(snaps) != 1 else ''} of this file from agent edits; see gitvow snapshots",
+        ]
+    return "\n".join(lines)
+
+
+def trace(cwd: str, spec: str) -> str:
+    top = toplevel(cwd) or cwd
+    m = re.match(r"^(.*?)(?::(\d+)(?:-(\d+))?)?$", spec)
+    path = m.group(1) if m else spec
+    rel = os.path.relpath(os.path.abspath(path), top) if os.path.isabs(path) else path
+    args = ["blame", "--line-porcelain"]
+    if m and m.group(2):
+        args += ["-L", f"{m.group(2)},{m.group(3) or m.group(2)}"]
+    rc, out, err = git([*args, "--", rel], top)
+    if rc != 0:
+        return err or f"cannot blame {rel}"
+    shas: list[str] = []
+    line_no = int(m.group(2)) if m and m.group(2) else 1
+    lines_by_sha: dict[str, list[int]] = {}
+    for ln in out.splitlines():
+        if re.match(r"^[0-9a-f]{40} ", ln):
+            sha = ln.split()[0]
+            parts = ln.split()
+            final = int(parts[2]) if len(parts) > 2 else line_no
+            lines_by_sha.setdefault(sha, []).append(final)
+            if sha not in shas:
+                shas.append(sha)
+    info: dict[str, dict[str, Any]] = {}
+    for sha in shas:
+        rc, body, _ = git(["log", "-1", "--format=%B", sha], top)
+        tm = TRAILER_RE.search(body or "")
+        if tm:
+            sm = STEP_RE.search(body)
+            info[sha] = {
+                "kind": "agent",
+                "session": tm.group(1),
+                "step": int(sm.group(1)) if sm else None,
+                "note": _note(top, sha, tm.group(1)),
+            }
+        else:
+            info[sha] = {"kind": "person"}
+    # group consecutive lines per sha
+    out_lines = [f"{rel}" + (f":{m.group(2)}-{m.group(3) or m.group(2)}" if m and m.group(2) else "")]
+    for sha in shas:
+        nums = sorted(lines_by_sha[sha])
+        ranges, start, prev = [], nums[0], nums[0]
+        for n in nums[1:]:
+            if n != prev + 1:
+                ranges.append((start, prev))
+                start = n
+            prev = n
+        ranges.append((start, prev))
+        rtxt = ", ".join(f"{a}-{b}" if a != b else str(a) for a, b in ranges[:6]) + (" …" if len(ranges) > 6 else "")
+        i = info[sha]
+        if i["kind"] == "agent":
+            step = f"step {i['step']}" if i["step"] is not None else ""
+            plan = _plan(i["note"])
+            out_lines.append(
+                f"lines {rtxt:<14} agent   {sha[:7]}  session {i['session'][:8]} {step}"
+                + (f'  "{plan}"' if plan else "")
+            )
+        else:
+            out_lines.append(f"lines {rtxt:<14} person  {sha[:7]}")
+    return "\n".join(out_lines)
+
+
+def recall(cwd: str, words: list[str], home: str | None = None, limit: int = 10) -> str:
+    top = toplevel(cwd) or cwd
+    terms = [w.lower() for w in words if w.strip()]
+    if not terms:
+        return "give one or more words to recall"
+    hits: dict[str, dict[str, Any]] = {}
+    for r in _commits(top, None, 2000):
+        if r["kind"] != "agent":
+            continue
+        hay = " ".join(
+            [
+                r["subject"],
+                _plan(r["note"]),
+                " ".join((r["note"] or {}).get("files_written_by_agent_this_session") or []),
+            ]
+        ).lower()
+        score = sum(1 for t in terms if t in hay)
+        if not score:
+            continue
+        h = hits.setdefault(
+            r["session"],
+            {"session": r["session"], "date": r["date"], "commits": 0, "plan": "", "score": 0, "source": "notes"},
+        )
+        h["commits"] += 1
+        h["score"] = max(h["score"], score)
+        h["plan"] = h["plan"] or _plan(r["note"]) or r["subject"]
+    led = os.path.join(home or os.path.expanduser("~"), ".gitvow", "ledger")
+    for f in glob.glob(os.path.join(led, "*.json")):
+        try:
+            rec = json.load(open(f))  # noqa: SIM115
+        except (OSError, json.JSONDecodeError):
+            continue
+        if os.path.realpath(rec.get("repo") or "") != os.path.realpath(top):
+            continue
+        hay = (
+            " ".join([rec.get("last_stated_plan") or ""] + [t.get("arg", "") for t in rec.get("tool_calls", [])])
+        ).lower()
+        score = sum(1 for t in terms if t in hay)
+        if score and rec.get("session_id") not in hits:
+            hits[rec["session_id"]] = {
+                "session": rec["session_id"],
+                "date": (rec.get("started") or "")[:10],
+                "commits": len(rec.get("commits_during_session") or []),
+                "plan": _plan(rec),
+                "score": score,
+                "source": "ledger",
+            }
+    if not hits:
+        return f"nothing recorded mentions: {' '.join(words)}"
+    rows = sorted(hits.values(), key=lambda h: (-h["score"], h["date"]), reverse=False)[:limit]
+    out = [f"{len(hits)} session{'s' if len(hits) != 1 else ''} mention {' '.join(words)}:"]
+    for h in rows:
+        out.append(
+            f'session {h["session"][:8]}  {h["date"]}  {h["commits"]} commit{"s" if h["commits"] != 1 else ""}  "{h["plan"]}"'
+            + ("  (ledger only)" if h["source"] == "ledger" else "")
+        )
+    return "\n".join(out)
+
+
+def handoff(cwd: str, session_id: str | None = None, home: str | None = None) -> str:
+    top = toplevel(cwd) or cwd
+    st = load_state(top)
+    sid = session_id or st.get("session_id")
+    led_dir = os.path.join(home or os.path.expanduser("~"), ".gitvow", "ledger")
+    rec: dict[str, Any] = {}
+    if sid and os.path.exists(os.path.join(led_dir, f"{sid}.json")):
+        try:
+            rec = json.load(open(os.path.join(led_dir, f"{sid}.json")))  # noqa: SIM115
+        except (OSError, json.JSONDecodeError):
+            rec = {}
+    if not sid:
+        return "no session known in this repository; pass --session <id>"
+    commits = [r for r in _commits(top, None, 500) if r["session"] == sid]
+    files = sorted(
+        {f for r in commits for f in ((r["note"] or {}).get("files_written_by_agent_this_session") or [])}
+        | set(st.get("agent_blobs", {}).keys() if st.get("session_id") == sid else [])
+    )
+    _, dirty, _ = git(["diff", "--shortstat", "HEAD"], top)
+    snaps = list_snapshots(top, sid)
+    plan = _plan(rec) or next((_plan(r["note"]) for r in commits if _plan(r["note"])), "")
+    confirms = []
+    gd_log = os.path.join(top, ".git", "gitvow-hooks.log")
+    if os.path.exists(gd_log):
+        with open(gd_log) as fh:
+            for ln in fh:
+                try:
+                    e = json.loads(ln)
+                except json.JSONDecodeError:
+                    continue
+                if e.get("kind") == "confirm_required" and e.get("session_id") == sid:
+                    confirms.append(f"{e.get('detail', '')[:60]} ({e.get('reason', '')[:60]})")
+    out = [f"# Handoff · session {sid[:8]} · repo {os.path.basename(top)}", ""]
+    out.append(f"Last stated plan: {plan or '(none recorded)'}")
+    out.append(
+        "Commits this session: "
+        + (", ".join(f"{r['short']} {r['subject'][:50]}" for r in commits) if commits else "none")
+    )
+    out.append("Files the agent wrote: " + (", ".join(files[:20]) if files else "none recorded"))
+    out.append(
+        f"Uncommitted now: {dirty.strip() or 'clean'}" + (f" · last snapshot {snaps[-1]['ref']}" if snaps else "")
+    )
+    out.append(
+        f"Open confirmations: {len(confirms)}" + ("".join(f"\n  - {c}" for c in confirms[-5:]) if confirms else "")
+    )
+    if rec.get("tool_calls"):
+        out.append(f"Tool calls in session: {len(rec['tool_calls'])}")
+    out += [
+        "",
+        "Next agent: read `gitvow why <file>` for any file above before changing it; snapshots hold the exact versions this session produced.",
+    ]
+    return "\n".join(out)

gitvow-0.7.1/src/gitvow/transcript.py

@@ -0,0 +1,187 @@
+"""Structural, redacted summary of an agent transcript (Claude Code JSONL). Tool output is never read."""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Iterable
+from typing import Any
+
+from .redact import redact
+
+
+def _detect(first: dict[str, Any]) -> str:
+    """Which agent wrote this transcript: claude (default), codex (rollout records), gemini (chat recording)."""
+    t = first.get("type")
+    if t in ("session_meta", "response_item", "event_msg", "turn_context", "compacted") and "payload" in first:
+        return "codex"
+    if "sessionId" in first and "projectHash" in first:
+        return "gemini"
+    if first.get("type") in ("user", "gemini", "info", "error") and "content" in first and "message" not in first:
+        return "gemini"
+    return "claude"
+
+
+def _text_of(content: Any) -> str:
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts = []
+        for c in content:
+            if isinstance(c, dict):
+                if c.get("type") in ("text", "output_text", "input_text") and c.get("text"):
+                    parts.append(str(c["text"]))
+                elif "text" in c and isinstance(c["text"], str):
+                    parts.append(c["text"])
+            elif isinstance(c, str):
+                parts.append(c)
+        return "\n".join(parts)
+    return ""
+
+
+def _patch_files(text: str) -> list[str]:
+    import re
+
+    return re.findall(r"^\*\*\* (?:Update|Add|Delete) File: (.+)$", text or "", re.M)
+
+
+def _codex_tool(name: str, arguments: Any) -> tuple[str, str, list[str]]:
+    """Codex function names -> (gitvow tool, brief argument, files written)."""
+    args: dict[str, Any] = {}
+    if isinstance(arguments, str):
+        try:
+            args = json.loads(arguments) if arguments.strip().startswith("{") else {"input": arguments}
+        except json.JSONDecodeError:
+            args = {"input": arguments}
+    elif isinstance(arguments, dict):
+        args = arguments
+    if name in ("exec_command", "shell", "container.exec", "local_shell"):
+        cmd = args.get("cmd") or args.get("command") or ""
+        cmd = " ".join(cmd) if isinstance(cmd, list) else str(cmd)
+        return "Bash", cmd, []
+    if name == "apply_patch":
+        patch = str(args.get("input") or args.get("patch") or args.get("command") or "")
+        files = _patch_files(patch)
+        return "Edit", files[0] if files else "apply_patch", files
+    return name, json.dumps(args)[:160] if args else "", []
+
+
+def _gemini_tool(name: str, args: Any) -> tuple[str, str, list[str]]:
+    a = args if isinstance(args, dict) else {}
+    if name == "run_shell_command":
+        return "Bash", str(a.get("command") or ""), []
+    if name in ("write_file", "replace", "edit"):
+        fp = str(a.get("file_path") or a.get("path") or "")
+        return ("Write" if name == "write_file" else "Edit"), fp, [fp] if fp else []
+    return name, json.dumps(a)[:160] if a else "", []
+
+
+def summarize(path: str | None, max_tools: int = 500, rules: Iterable[tuple[str, str]] = ()) -> dict[str, Any]:
+    """Structural summary of a transcript. Reads Claude Code, Codex and Gemini CLI formats; tool output is never read."""
+    out: dict[str, Any] = {
+        "turns": 0,
+        "tool_calls": [],
+        "last_assistant_text": "",
+        "files_written": [],
+        "format": "claude",
+    }
+    if not path or not os.path.exists(path):
+        return out
+    rules = list(rules)
+    written: set[str] = set()
+    fmt: str | None = None
+    with open(path, errors="ignore") as fh:
+        for line in fh:
+            try:
+                ev = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if not isinstance(ev, dict):
+                continue
+            if fmt is None:
+                fmt = _detect(ev)
+                out["format"] = fmt
+            if fmt == "codex":
+                _codex_event(ev, out, written, rules, max_tools)
+            elif fmt == "gemini":
+                _gemini_event(ev, out, written, rules, max_tools)
+            else:
+                _claude_event(ev, out, written, rules, max_tools)
+    out["files_written"] = sorted(written)
+    return out
+
+
+def _add_tool(out: dict[str, Any], tool: str, brief: str, rules: list[tuple[str, str]], max_tools: int) -> None:
+    if len(out["tool_calls"]) < max_tools:
+        out["tool_calls"].append({"tool": tool, "arg": redact(str(brief), rules)[:160]})
+
+
+def _claude_event(
+    ev: dict[str, Any], out: dict[str, Any], written: set[str], rules: list[tuple[str, str]], max_tools: int
+) -> None:
+    msg = ev.get("message") or {}
+    role = msg.get("role") or ev.get("type")
+    content = msg.get("content")
+    if role != "assistant":
+        return
+    out["turns"] += 1
+    if isinstance(content, str):
+        if content.strip():
+            out["last_assistant_text"] = redact(content, rules)[:600]
+        return
+    if not isinstance(content, list):
+        return
+    for c in content:
+        if not isinstance(c, dict):
+            continue
+        if c.get("type") == "tool_use":
+            inp = c.get("input") or {}
+            brief = inp.get("command") or inp.get("file_path") or inp.get("query") or inp.get("pattern") or ""
+            _add_tool(out, str(c.get("name")), brief, rules, max_tools)
+            if c.get("name") in ("Edit", "Write", "MultiEdit", "NotebookEdit") and inp.get("file_path"):
+                written.add(str(inp["file_path"]))
+        elif c.get("type") == "text" and str(c.get("text", "")).strip():
+            out["last_assistant_text"] = redact(c["text"], rules)[:600]
+
+
+def _codex_event(
+    ev: dict[str, Any], out: dict[str, Any], written: set[str], rules: list[tuple[str, str]], max_tools: int
+) -> None:
+    t, p = ev.get("type"), ev.get("payload") or {}
+    if not isinstance(p, dict):
+        return
+    if t == "response_item":
+        pt = p.get("type")
+        if pt == "message" and p.get("role") == "assistant":
+            out["turns"] += 1
+            text = _text_of(p.get("content"))
+            if text.strip():
+                out["last_assistant_text"] = redact(text, rules)[:600]
+        elif pt in ("function_call", "custom_tool_call", "local_shell_call"):
+            name = str(p.get("name") or ("local_shell" if pt == "local_shell_call" else ""))
+            arguments = p.get("arguments") if pt == "function_call" else (p.get("input") or p.get("action") or "")
+            tool, brief, files = _codex_tool(name, arguments)
+            _add_tool(out, tool, brief, rules, max_tools)
+            written.update(files)
+    elif t == "event_msg":
+        pt = p.get("type")
+        if pt == "agent_message" and p.get("message"):
+            out["turns"] += 1
+            out["last_assistant_text"] = redact(str(p["message"]), rules)[:600]
+
+
+def _gemini_event(
+    ev: dict[str, Any], out: dict[str, Any], written: set[str], rules: list[tuple[str, str]], max_tools: int
+) -> None:
+    if ev.get("type") != "gemini":
+        return
+    out["turns"] += 1
+    text = _text_of(ev.get("content"))
+    if text.strip():
+        out["last_assistant_text"] = redact(text, rules)[:600]
+    for tc in ev.get("toolCalls") or []:
+        if not isinstance(tc, dict):
+            continue
+        tool, brief, files = _gemini_tool(str(tc.get("name") or ""), tc.get("args"))
+        _add_tool(out, tool, brief, rules, max_tools)
+        written.update(files)

{gitvow-0.6.0 → gitvow-0.7.1/src/gitvow.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitvow
-Version: 0.6.0
+Version: 0.7.1
 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.6.0 → gitvow-0.7.1}/src/gitvow.egg-info/SOURCES.txt

@@ -10,6 +10,7 @@ src/gitvow/default_policy.json
 src/gitvow/install.py
 src/gitvow/policy.py
 src/gitvow/providers.py
+src/gitvow/recall.py
 src/gitvow/redact.py
 src/gitvow/report.py
 src/gitvow/selftest.py
@@ -30,6 +31,8 @@ tests/test_install_cli.py
 tests/test_packaging.py
 tests/test_policy.py
 tests/test_providers.py
+tests/test_recall.py
 tests/test_redact.py
 tests/test_report.py
-tests/test_snapshots.py
+tests/test_snapshots.py
+tests/test_transcript_formats.py

gitvow-0.7.1/tests/test_recall.py

@@ -0,0 +1,107 @@
+import json
+
+from gitvow import cli
+from gitvow.hooks import post_tool_use, pre_tool_use, session_start, stop
+from gitvow.install import _write_git_hook
+from tests.conftest import git
+
+
+def _agent_session(repo, home, payload, sid, file, content, subject, transcript=""):
+    p = payload("SessionStart", transcript=transcript)
+    p["session_id"] = sid
+    session_start(p, str(home))
+    (repo / file).write_text(content)
+    post_tool_use({**p, "tool_name": "Edit", "tool_input": {"file_path": str(repo / file)}}, str(home))
+    git(repo, "add", file)
+    pre_tool_use(
+        {**p, "tool_name": "Bash", "tool_input": {"command": "git commit -m x"}, "transcript_path": transcript},
+        str(home),
+    )
+    git(repo, "commit", "-qm", subject)
+    post_tool_use(
+        {**p, "tool_name": "Bash", "tool_input": {"command": "git commit -m x"}, "transcript_path": transcript},
+        str(home),
+    )
+    stop({**p, "transcript_path": transcript}, str(home))
+    return p
+
+
+def test_why_trace_recall_handoff(repo, home, payload, transcript, monkeypatch, capsys, tmp_path):
+    _write_git_hook(str(repo / ".gitvow" / "git-hooks"))
+    git(repo, "config", "core.hooksPath", ".gitvow/git-hooks")
+    # a transcript whose plan mentions "cache key" for session one
+    t2 = tmp_path / "t2.jsonl"
+    t2.write_text(
+        json.dumps(
+            {
+                "type": "assistant",
+                "message": {
+                    "role": "assistant",
+                    "content": [{"type": "text", "text": "Plan: change the cache key to include week start."}],
+                },
+            }
+        )
+        + "\n"
+    )
+    _agent_session(
+        repo, home, payload, "sess-one", "calc.py", "def add(a, b):\n    return a + b\n", "Add calc", str(t2)
+    )
+    # a person edits calc.py and commits without a session
+    (repo / "calc.py").write_text("def add(a, b):\n    return a + b\n\ndef human():\n    return 1\n")
+    git(repo, "commit", "-qam", "human adds helper")
+    # second agent session touches another file and mentions "export"
+    _agent_session(
+        repo, home, payload, "sess-two", "orders.py", "route = '/v1/orders/export'\n", "Add export", transcript
+    )
+    monkeypatch.chdir(repo)
+
+    assert cli.main(["why", "calc.py"]) == 0
+    out = capsys.readouterr().out
+    assert "1 agent commit, 1 human commit, 1 session" in out
+    assert "session sess-one" in out and "cache key" in out and "(person)" in out and "agent share 1.00" in out
+    assert "1 snapshot of this file" in out
+
+    assert cli.main(["trace", "calc.py:1-5"]) == 0
+    out = capsys.readouterr().out
+    assert "agent" in out and "session sess-one" in out and "person" in out
+    assert cli.main(["trace", "calc.py"]) == 0
+    assert cli.main(["trace", "nope.py"]) == 0  # reports the git error instead of crashing
+
+    assert cli.main(["recall", "cache", "key"]) == 0
+    out = capsys.readouterr().out
+    assert "1 session mention" in out and "sess-one" in out and "sess-two" not in out
+    assert cli.main(["recall", "export"]) == 0
+    assert "sess-two" in capsys.readouterr().out
+    assert cli.main(["recall", "zzzunlikely"]) == 0
+    assert "nothing recorded" in capsys.readouterr().out
+    # a session that ended without committing is found through the ledger alone
+    p3 = payload("SessionStart", transcript=str(t2))
+    p3["session_id"] = "sess-three"
+    session_start(p3, str(home))
+    pre_tool_use({**p3, "tool_name": "Bash", "tool_input": {"command": "kubectl apply -f x.yaml"}}, str(home))
+    stop(p3, str(home))
+    assert cli.main(["recall", "week", "start"]) == 0
+    out = capsys.readouterr().out
+    assert "2 sessions mention" in out and "sess-thr" in out and "(ledger only)" in out
+    assert cli.main(["handoff", "--session", "sess-three"]) == 0
+    out = capsys.readouterr().out
+    assert "Open confirmations: 1" in out and "kubectl apply" in out and "Commits this session: none" in out
+
+    (repo / "orders.py").write_text("route = '/v1/orders/export'\nx = 1\n")  # uncommitted work
+    p2 = payload("SessionStart")
+    p2["session_id"] = "sess-two"
+    session_start(p2, str(home))  # resume session two so handoff defaults to it
+    assert cli.main(["handoff"]) == 0
+    out = capsys.readouterr().out
+    assert out.startswith("# Handoff · session sess-two") and "Add export" in out and "orders.py" in out
+    assert "Uncommitted now: 1 file changed" in out and "last snapshot refs/gitvow/snapshots/sess-two/1" in out
+    assert cli.main(["handoff", "--session", "sess-one"]) == 0
+    assert "Add calc" in capsys.readouterr().out
+
+
+def test_handoff_without_session(repo, monkeypatch, capsys):
+    monkeypatch.chdir(repo)
+    assert cli.main(["handoff"]) == 0
+    assert "no session known" in capsys.readouterr().out
+    assert cli.main(["why", "a.txt"]) == 0
+    assert "0 agent commits, 1 human commit" in capsys.readouterr().out

gitvow-0.7.1/tests/test_transcript_formats.py

@@ -0,0 +1,128 @@
+import json
+
+from gitvow.transcript import summarize
+
+CODEX = [
+    {
+        "timestamp": "t",
+        "type": "session_meta",
+        "payload": {"id": "abc", "cwd": "/r", "cli_version": "0.130.0", "git": {"branch": "main"}},
+    },
+    {"timestamp": "t", "type": "turn_context", "payload": {"cwd": "/r", "model": "gpt-5"}},
+    {
+        "timestamp": "t",
+        "type": "response_item",
+        "payload": {"type": "message", "role": "user", "content": [{"type": "input_text", "text": "fix add"}]},
+    },
+    {
+        "timestamp": "t",
+        "type": "response_item",
+        "payload": {
+            "type": "message",
+            "role": "assistant",
+            "content": [
+                {
+                    "type": "output_text",
+                    "text": "I will fix add() in calc.py; token ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 stays out.",
+                }
+            ],
+        },
+    },
+    {
+        "timestamp": "t",
+        "type": "response_item",
+        "payload": {
+            "type": "function_call",
+            "name": "exec_command",
+            "arguments": json.dumps({"cmd": ["git", "status"]}),
+            "call_id": "c1",
+        },
+    },
+    {
+        "timestamp": "t",
+        "type": "response_item",
+        "payload": {"type": "function_call_output", "call_id": "c1", "output": "clean SECRET=hunter2 (never read)"},
+    },
+    {
+        "timestamp": "t",
+        "type": "response_item",
+        "payload": {
+            "type": "custom_tool_call",
+            "name": "apply_patch",
+            "input": "*** Begin Patch\n*** Update File: calc.py\n-    return a - b\n+    return a + b\n*** End Patch\n",
+            "call_id": "c2",
+        },
+    },
+    {
+        "timestamp": "t",
+        "type": "event_msg",
+        "payload": {"type": "agent_message", "message": "Done: fixed add() in calc.py."},
+    },
+    {
+        "timestamp": "t",
+        "type": "event_msg",
+        "payload": {"type": "token_count", "info": {"total_token_usage": {"input_tokens": 10}}},
+    },
+]
+
+GEMINI = [
+    {"sessionId": "g1", "projectHash": "h", "startTime": "t", "lastUpdated": "t", "kind": "main"},
+    {"id": "m1", "timestamp": "t", "type": "user", "content": "fix add"},
+    {
+        "id": "m2",
+        "timestamp": "t",
+        "type": "gemini",
+        "content": [{"text": "Fixing add() in calc.py now."}],
+        "model": "gemini-2.5-pro",
+        "toolCalls": [
+            {"id": "t1", "name": "run_shell_command", "args": {"command": "git status"}, "status": "success"},
+            {
+                "id": "t2",
+                "name": "replace",
+                "args": {"file_path": "/r/calc.py", "old_string": "a - b", "new_string": "a + b"},
+                "status": "success",
+            },
+            {"id": "t3", "name": "write_file", "args": {"file_path": "/r/new.py", "content": "x"}, "status": "success"},
+        ],
+    },
+    {"$set": {"lastUpdated": "t2"}},
+    {"id": "m3", "timestamp": "t", "type": "gemini", "content": "All done in calc.py and new.py."},
+]
+
+
+def _write(tmp_path, name, rows):
+    p = tmp_path / name
+    p.write_text("\n".join(json.dumps(r) for r in rows) + "\n")
+    return str(p)
+
+
+def test_codex_rollout_is_read(tmp_path):
+    s = summarize(_write(tmp_path, "rollout.jsonl", CODEX))
+    assert s["format"] == "codex" and s["turns"] == 2
+    assert [t["tool"] for t in s["tool_calls"]] == ["Bash", "Edit"]
+    assert s["tool_calls"][0]["arg"] == "git status" and s["tool_calls"][1]["arg"] == "calc.py"
+    assert s["files_written"] == ["calc.py"]
+    assert s["last_assistant_text"] == "Done: fixed add() in calc.py."
+    assert "hunter2" not in json.dumps(s)  # tool output is never read
+
+
+def test_gemini_chat_recording_is_read(tmp_path):
+    s = summarize(_write(tmp_path, "session-1.jsonl", GEMINI))
+    assert s["format"] == "gemini" and s["turns"] == 2
+    assert [t["tool"] for t in s["tool_calls"]] == ["Bash", "Edit", "Write"]
+    assert sorted(s["files_written"]) == ["/r/calc.py", "/r/new.py"]
+    assert s["last_assistant_text"] == "All done in calc.py and new.py."
+
+
+def test_claude_format_still_default(transcript):
+    s = summarize(transcript)
+    assert (
+        s["format"] == "claude"
+        and s["tool_calls"][0]["tool"] == "Bash"
+        and "[github-token]" in s["last_assistant_text"]
+    )
+
+
+def test_redaction_applies_to_all_formats(tmp_path):
+    s = summarize(_write(tmp_path, "rollout.jsonl", CODEX[:4]))
+    assert "[github-token]" in s["last_assistant_text"] and "ghp_" not in s["last_assistant_text"]

gitvow-0.6.0/src/gitvow/transcript.py

@@ -1,49 +0,0 @@
-"""Structural, redacted summary of an agent transcript (Claude Code JSONL). Tool output is never read."""
-
-from __future__ import annotations
-
-import json
-import os
-from collections.abc import Iterable
-from typing import Any
-
-from .redact import redact
-
-
-def summarize(path: str | None, max_tools: int = 500, rules: Iterable[tuple[str, str]] = ()) -> dict[str, Any]:
-    out: dict[str, Any] = {"turns": 0, "tool_calls": [], "last_assistant_text": "", "files_written": []}
-    if not path or not os.path.exists(path):
-        return out
-    written: set[str] = set()
-    rules = list(rules)
-    with open(path, errors="ignore") as fh:
-        for line in fh:
-            try:
-                ev = json.loads(line)
-            except json.JSONDecodeError:
-                continue
-            msg = ev.get("message") or {}
-            role = msg.get("role") or ev.get("type")
-            content = msg.get("content")
-            if role != "assistant":
-                continue
-            out["turns"] += 1
-            if isinstance(content, str):
-                if content.strip():
-                    out["last_assistant_text"] = redact(content, rules)[:600]
-                continue
-            if not isinstance(content, list):
-                continue
-            for c in content:
-                if not isinstance(c, dict):
-                    continue
-                if c.get("type") == "tool_use" and len(out["tool_calls"]) < max_tools:
-                    inp = c.get("input") or {}
-                    brief = inp.get("command") or inp.get("file_path") or inp.get("query") or inp.get("pattern") or ""
-                    out["tool_calls"].append({"tool": c.get("name"), "arg": redact(str(brief), rules)[:160]})
-                    if c.get("name") in ("Edit", "Write", "MultiEdit", "NotebookEdit") and inp.get("file_path"):
-                        written.add(str(inp["file_path"]))
-                elif c.get("type") == "text" and str(c.get("text", "")).strip():
-                    out["last_assistant_text"] = redact(c["text"], rules)[:600]
-    out["files_written"] = sorted(written)
-    return out