awgit 0.1.0__py3-none-any.whl

awgit/cli.py

@@ -0,0 +1,488 @@
+"""CLI entrypoint for the semantic-VCS layer (`python -m lib.awgit.cli`).
+
+Used by git hooks (capture, lease-check) and by agents (status, diff, lease).
+Runs as its own sync process — no event loop is active, so the blocking file
+locks in the stores are PQ010-compliant.
+
+Actor attribution prefers an explicit ``--actor``, then ``AITHER_ACTOR``, then
+the VERIFIED GitHub login (the Aitherium GitHub OAuth-app identity via ``gh``,
+cached), then the commit author. Every op records ``actor_verified`` /
+``verified_actor`` so a self-asserted agent name is never mistaken for verified
+identity — the verified half is the authoritative attribution.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import List, Optional
+
+from awgit.capture import capture_ops
+from awgit.diff import diff_git, render
+from awgit.leases import LeaseConflictError, LeaseRegistry, coverage_gap
+from awgit.merge import list_conflicts, merge_ops, resolve_conflict
+from awgit.oplog import OpLog
+
+
+def _actor(args: argparse.Namespace) -> str:
+    return (
+        getattr(args, "actor", None)
+        or os.environ.get("AITHER_ACTOR")
+        or "unknown"
+    )
+
+
+def _cmd_capture(args: argparse.Namespace) -> int:
+    try:
+        op = capture_ops(
+            args.sha,
+            actor=args.actor,
+            data_root=Path(args.data_root) if args.data_root else None,
+        )
+    except ValueError as exc:
+        print(f"vcs: {exc}", file=sys.stderr)
+        return 2
+    if op is None:
+        print(f"vcs: no semantic changes for {args.sha}")
+        return 0
+    print(f"vcs: op {op.op_id} recorded ({op.summary})")
+    return 0
+
+
+def _cmd_diff(args: argparse.Namespace) -> int:
+    try:
+        changes = diff_git(args.a, args.b)
+    except ValueError as exc:
+        print(f"vcs: {exc}", file=sys.stderr)
+        return 2
+    if not changes:
+        print("vcs: no semantic changes")
+        return 0
+    for line in render(changes):
+        print(line)
+    return 0
+
+
+def _cmd_merge_preview(args: argparse.Namespace) -> int:
+    op_a = capture_ops(args.a, actor=args.actor)
+    op_b = capture_ops(args.b, actor=args.actor)
+    a_ops = [op_a] if op_a else []
+    b_ops = [op_b] if op_b else []
+    result = merge_ops(a_ops, b_ops)
+    print(f"vcs: merge status: {result.status}")
+    for note in result.notes:
+        print(f"  {note}")
+    for c in result.conflicts:
+        print(f"  CONFLICT {c.node_id} ({c.symbol}) — escalate for human review")
+    return 0 if result.status != "conflict" else 1
+
+
+def _cmd_merge_conflicts(args: argparse.Namespace) -> int:
+    for c in list_conflicts():
+        print(f"{c.conflict_id} {c.node_id} {c.symbol} [{c.status}]")
+    return 0
+
+
+def _cmd_resolve_conflict(args: argparse.Namespace) -> int:
+    if not args.body:
+        print("vcs: --body <file> required", file=sys.stderr)
+        return 2
+    try:
+        body = Path(args.body).read_text(encoding="utf-8")
+    except OSError as exc:
+        print(f"vcs: cannot read {args.body}: {exc}", file=sys.stderr)
+        return 2
+    resolver = args.resolver or os.environ.get("AITHER_ACTOR") or "unknown"
+    op = resolve_conflict(args.conflict_id, resolved_body=body, resolver=resolver)
+    if op is None:
+        print(f"vcs: conflict {args.conflict_id} not found", file=sys.stderr)
+        return 1
+    print(f"vcs: conflict resolved; synthetic op {op.op_id} recorded")
+    return 0
+
+
+def _cmd_status(args: argparse.Namespace) -> int:
+    log = OpLog()
+    ops = log.all_ops()
+    last = max(ops, key=lambda o: o.ts) if ops else None
+    print(f"vcs: {len(ops)} ops in {log.path}")
+    if last is not None:
+        print(f"  last: {last.ts} {last.actor} {last.summary}")
+    return 0
+
+
+def _cmd_lease(args: argparse.Namespace) -> int:
+    registry = LeaseRegistry()
+    cmd = args.lease_cmd
+    who = _actor(args)
+    if cmd == "acquire":
+        try:
+            leases = registry.acquire(
+                who, args.targets, ttl_sec=args.ttl, reason=args.reason
+            )
+        except LeaseConflictError as exc:
+            print(f"vcs: {exc}", file=sys.stderr)
+            return 1
+        for lz in leases:
+            print(f"vcs: lease {lz.lease_id} {lz.target} until {lz.expires_ts}")
+        return 0
+    if cmd == "heartbeat":
+        print(f"vcs: heartbeat refreshed {registry.heartbeat(who, args.ids)} leases")
+        return 0
+    if cmd == "release":
+        print(f"vcs: released {registry.release(who, args.ids)} leases")
+        return 0
+    if cmd == "list":
+        for lz in sorted(registry.active_leases(), key=lambda x: x.target):
+            print(f"{lz.lease_id} {lz.status} {lz.actor} {lz.kind} {lz.target} "
+                  f"until {lz.expires_ts}")
+        return 0
+    if cmd == "sweep":
+        print(f"vcs: swept {registry.sweep_expired()} expired leases")
+        return 0
+    return 2
+
+
+def _staged_files(repo: Path) -> List[str]:
+    out = subprocess.run(
+        ["git", "diff", "--cached", "--name-only"],
+        cwd=str(repo),
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    ).stdout
+    return [ln for ln in out.splitlines() if ln.strip()]
+
+
+def _cmd_lease_check(args: argparse.Namespace) -> int:
+    if os.environ.get("VCS_LEASES_ENFORCE", "0") != "1":
+        print("vcs: lease-check not enforced (VCS_LEASES_ENFORCE=0)")
+        return 0
+    repo = Path(os.environ.get("VCS_REPO_ROOT", os.getcwd()))
+    who = _actor(args)
+    if who == "unknown":
+        print("vcs: lease-check requires AITHER_ACTOR (or --actor)", file=sys.stderr)
+        return 1
+    gap = coverage_gap(_staged_files(repo), who)
+    if gap:
+        print(
+            "vcs: commit rejected — no active lease covering: " + ", ".join(gap),
+            file=sys.stderr,
+        )
+        return 1
+    print("vcs: lease-check OK")
+    return 0
+
+
+def _cmd_bodies(args: argparse.Namespace) -> int:
+    from awgit.bodies import BodyStore
+
+    store = BodyStore()
+    if not args.get:
+        st = store.stats()
+        print(f"vcs: body store: {st['blobs']} blobs, {st['bytes']:,} bytes")
+        return 0
+    body = store.get(args.get)
+    if body is None:
+        print(f"vcs: no body for {args.get}", file=sys.stderr)
+        return 1
+    if args.out:
+        try:
+            Path(args.out).write_bytes(body)
+        except OSError as exc:
+            print(f"vcs: cannot write {args.out}: {exc}", file=sys.stderr)
+            return 2
+        print(f"vcs: wrote {len(body)} bytes to {args.out}")
+    else:
+        sys.stdout.write(body.decode("utf-8", errors="replace"))
+    return 0
+
+
+def _cmd_dedupe(args: argparse.Namespace) -> int:
+    from awgit.bodies import BodyStore, dedupe_report, op_referenced_shas
+
+    if args.scan:
+        rep = dedupe_report([Path(p) for p in args.scan])
+        print(
+            f"vcs: dedupe across {len(args.scan)} trees: "
+            f"{rep['groups']} identical-content groups, "
+            f"{rep['duplicate_files']} duplicate files, "
+            f"{rep['wasted_bytes']:,} bytes duplicated"
+        )
+        return 0
+    if args.reclaim:
+        from awgit.bodies import reclaim
+
+        res = reclaim([Path(p) for p in args.reclaim], dry_run=not args.apply)
+        verb = "linked" if args.apply else "would link"
+        print(
+            f"vcs: reclaim {verb} {res['linked']} duplicate files across "
+            f"{res['groups']} groups ({res['reclaimed_bytes']:,} bytes)"
+        )
+        print(
+            f"vcs:   skipped {res['skipped_tracked']} git-tracked files (never linked)"
+        )
+        if not args.apply:
+            print("vcs: dry-run — pass --apply to actually hard-link")
+        return 0
+    store = BodyStore()
+    st = store.stats()
+    if args.gc:
+        referenced = op_referenced_shas()
+        res = store.gc(referenced, dry_run=not args.apply)
+        verb = "removed" if args.apply else "would remove"
+        print(
+            f"vcs: gc {verb} {res['removed']} orphaned blobs "
+            f"({res['freed']:,} bytes)"
+        )
+        if not args.apply:
+            print("vcs: dry-run — pass --apply to actually delete")
+        return 0
+    referenced = op_referenced_shas()
+    orphaned = len(store.blob_shas() - referenced)
+    print(
+        f"vcs: body store: {st['blobs']} blobs, {st['bytes']:,} bytes, "
+        f"{len(referenced)} referenced by op-log, {orphaned} orphaned"
+    )
+    if orphaned:
+        print("vcs: run `awgit dedupe --gc` (dry-run) to see reclaimable space")
+    return 0
+
+
+def _cmd_ledger(args: argparse.Namespace) -> int:
+    """Attribution view — who changed what, under a verified GitHub identity."""
+    from awgit.ledger import op_to_ledger_entry
+    from awgit.oplog import OpLog
+
+    ops = OpLog().all_ops()
+    if args.op:
+        ops = [o for o in ops if o.op_id == args.op]
+    elif args.sha:
+        ops = [o for o in ops if o.git_sha == args.sha]
+    if not ops:
+        print("vcs: ledger: no ops match", file=sys.stderr)
+        return 1
+    for op in ops:
+        entry = op_to_ledger_entry(op)
+        verified = (
+            f" (verified {entry.verified_actor})" if entry.actor_verified else ""
+        )
+        print(
+            f"{entry.ledger_ref} {entry.actor}{verified} "
+            f"{entry.git_sha[:10]} {entry.node_changes} node_changes {entry.ts}"
+        )
+    return 0
+
+
+def _cmd_sync(args: argparse.Namespace) -> int:
+    import json as _json
+
+    from awgit.sync import export_delta, import_delta, sync_status
+
+    data_root = Path(args.data_root) if args.data_root else None
+    if args.export:
+        # export the ops a PEER is missing; default full-clone (known empty).
+        known = set(args.known) if args.known else set()
+        bundle = export_delta(
+            known, data_root=data_root, include_bodies=not args.meta_only
+        )
+        out = args.out or "awgit-delta.json"
+        try:
+            Path(out).write_text(_json.dumps(bundle), encoding="utf-8")
+        except OSError as exc:
+            print(f"vcs: cannot write {out}: {exc}", file=sys.stderr)
+            return 2
+        print(
+            f"vcs: exported {bundle['op_count']} ops, {bundle['body_count']} bodies -> {out}"
+        )
+        return 0
+    if args.import_file:
+        try:
+            bundle = _json.loads(Path(args.import_file).read_text(encoding="utf-8"))
+        except (OSError, ValueError) as exc:
+            print(f"vcs: cannot read bundle {args.import_file}: {exc}", file=sys.stderr)
+            return 2
+        res = import_delta(bundle, data_root=data_root)
+        print(
+            f"vcs: imported {res['imported_ops']} ops, {res['bodies']} bodies "
+            f"(skipped {res['skipped']}); applied {res['applied']}"
+        )
+        return 0
+    st = sync_status(data_root=data_root)
+    print(
+        f"vcs: sync {st['ops']} ops, {st['applied']} applied, {st['missing']} missing, "
+        f"{st['bodies']} bodies ({st['bytes']:,} bytes)"
+    )
+    return 0
+
+
+def _cmd_hooks(args: argparse.Namespace) -> int:
+    """Install/uninstall the chained capture hooks (see bridge.install_hooks)."""
+    from awgit.bridge import install_hooks, uninstall_hooks
+
+    if args.action == "install":
+        installed = install_hooks(args.repo)
+        for p in installed:
+            print(f"vcs: installed hook {p}")
+        if not installed:
+            print("vcs: no hooks installed", file=sys.stderr)
+            return 2
+        return 0
+    if args.action == "uninstall":
+        for p in uninstall_hooks(args.repo):
+            print(f"vcs: restored hook {p}")
+        return 0
+    return 2
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="awgit",
+        description="awgit — Aither World-Graph git: semantic version control on top of git",
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_capture = sub.add_parser("capture", help="capture a commit as an EditOp")
+    p_capture.add_argument("--sha", required=True)
+    p_capture.add_argument("--actor", default=None)
+    p_capture.add_argument(
+        "--data-root",
+        default=None,
+        help="vcs store directory (default: ~/.aither/awgit/data, or $VCS_DATA_ROOT)",
+    )
+
+    p_diff = sub.add_parser("diff", help="node-level diff between two shas")
+    p_diff.add_argument("a", help="base sha")
+    p_diff.add_argument("b", help="target sha")
+
+    sub.add_parser("status", help="op-log status")
+
+    p_mp = sub.add_parser("merge-preview", help="node-level merge preview of two shas")
+    p_mp.add_argument("a", help="base-side sha")
+    p_mp.add_argument("b", help="merge-side sha")
+    p_mp.add_argument("--actor", default=None)
+
+    sub.add_parser("merge-conflicts", help="list escalated merge conflicts")
+
+    p_rc = sub.add_parser("resolve-conflict", help="mark a conflict resolved (human)")
+    p_rc.add_argument("conflict_id")
+    p_rc.add_argument("--body", default=None, help="file with the resolved node body")
+    p_rc.add_argument("--resolver", default=None)
+
+    p_lease = sub.add_parser("lease", help="lease registry operations")
+    lsub = p_lease.add_subparsers(dest="lease_cmd", required=True)
+    p_la = lsub.add_parser("acquire", help="acquire leases for targets")
+    p_la.add_argument("targets", nargs="+")
+    p_la.add_argument("--ttl", type=int, default=300)
+    p_la.add_argument("--reason", default="")
+    p_la.add_argument("--actor", default=None)
+    p_lh = lsub.add_parser("heartbeat", help="refresh leases")
+    p_lh.add_argument("ids", nargs="+")
+    p_lh.add_argument("--actor", default=None)
+    p_lr = lsub.add_parser("release", help="release leases")
+    p_lr.add_argument("ids", nargs="+")
+    p_lr.add_argument("--actor", default=None)
+    lsub.add_parser("list", help="list active leases")
+    lsub.add_parser("sweep", help="sweep expired leases")
+
+    p_lc = sub.add_parser("lease-check", help="pre-commit lease gate")
+    p_lc.add_argument("--actor", default=None)
+
+    p_bodies = sub.add_parser(
+        "bodies", help="content-addressed body store (read a sha / stats)"
+    )
+    p_bodies.add_argument("--get", default=None, help="content address (sha) to read")
+    p_bodies.add_argument("--out", default=None, help="write the body to this file")
+
+    p_dedupe = sub.add_parser(
+        "dedupe", help="body store stats / gc / disk dedupe scan for duplicate files"
+    )
+    p_dedupe.add_argument(
+        "--scan", nargs="*", default=None, help="trees to hash for duplicate files"
+    )
+    p_dedupe.add_argument(
+        "--reclaim", nargs="*", default=None,
+        help="hard-link duplicate files under these trees (dry-run unless --apply)",
+    )
+    p_dedupe.add_argument(
+        "--gc", action="store_true",
+        help="remove body blobs the op-log does not reference (dry-run unless --apply)",
+    )
+    p_dedupe.add_argument(
+        "--apply", action="store_true",
+        help="with --reclaim/--gc: actually act (never touches git-tracked / referenced)",
+    )
+
+    p_ledger = sub.add_parser(
+        "ledger", help="op-log as attribution records (who changed what)"
+    )
+    p_ledger.add_argument("--op", default=None, help="op_id to show")
+    p_ledger.add_argument("--sha", default=None, help="git sha to show")
+
+    p_sync = sub.add_parser(
+        "sync", help="differential sync over the mesh (ops + bodies)"
+    )
+    p_sync.add_argument(
+        "--export", action="store_true", help="export the delta to a bundle file"
+    )
+    p_sync.add_argument("--out", default=None, help="bundle path for --export")
+    p_sync.add_argument(
+        "--known", nargs="*", default=None,
+        help="op_ids the peer already has (default: none = full clone)",
+    )
+    p_sync.add_argument(
+        "--meta-only", action="store_true",
+        help="export ops WITHOUT bodies (peers pull bodies on-demand by sha)",
+    )
+    p_sync.add_argument(
+        "--import", dest="import_file", default=None, help="bundle file to import"
+    )
+    p_sync.add_argument(
+        "--data-root", default=None, help="vcs store directory (default: Library/Data/vcs)"
+    )
+
+    p_hooks = sub.add_parser(
+        "hooks", help="install/uninstall the chained capture hooks"
+    )
+    p_hooks.add_argument("action", choices=["install", "uninstall"])
+    p_hooks.add_argument(
+        "--repo", default=None, help="repo root (default: current directory)"
+    )
+
+    args = parser.parse_args(argv)
+    if args.cmd == "capture":
+        return _cmd_capture(args)
+    if args.cmd == "diff":
+        return _cmd_diff(args)
+    if args.cmd == "status":
+        return _cmd_status(args)
+    if args.cmd == "merge-preview":
+        return _cmd_merge_preview(args)
+    if args.cmd == "merge-conflicts":
+        return _cmd_merge_conflicts(args)
+    if args.cmd == "resolve-conflict":
+        return _cmd_resolve_conflict(args)
+    if args.cmd == "lease":
+        return _cmd_lease(args)
+    if args.cmd == "lease-check":
+        return _cmd_lease_check(args)
+    if args.cmd == "bodies":
+        return _cmd_bodies(args)
+    if args.cmd == "dedupe":
+        return _cmd_dedupe(args)
+    if args.cmd == "ledger":
+        return _cmd_ledger(args)
+    if args.cmd == "sync":
+        return _cmd_sync(args)
+    if args.cmd == "hooks":
+        return _cmd_hooks(args)
+    parser.error(f"unknown command {args.cmd}")
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

awgit/data_root.py

@@ -0,0 +1,30 @@
+"""VCS data-root resolution (standalone).
+
+The op-log, node registry, body store, and lease stores must all live under
+ONE root so a stable node id from any store resolves to the same
+``(name, path)`` coordinate space. Standalone awgit keeps the durable store
+OUTSIDE the git tree — ``~/.aither/awgit/data`` by default, overridable with
+``VCS_DATA_ROOT`` (the same env the in-repo capture hooks use). A passed
+``root_path`` preserves the monorepo convention ``<root>/Library/Data/vcs``
+for callers that want the store under a project root.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Optional
+
+
+def vcs_data_root(root_path: Optional[str] = None) -> Path:
+    """Absolute path of the durable vcs store directory (created lazily).
+
+    Priority: ``VCS_DATA_ROOT`` env → ``root_path/Library/Data/vcs`` when a
+    project root is supplied → ``~/.aither/awgit/data``.
+    """
+    override = os.environ.get("VCS_DATA_ROOT")
+    if override:
+        return Path(override)
+    if root_path:
+        return Path(root_path) / "Library" / "Data" / "vcs"
+    return Path.home() / ".aither" / "awgit" / "data"

awgit/diff.py

@@ -0,0 +1,82 @@
+"""Semantic diff — 'what changed' at node granularity.
+
+Renders the difference between two git shas (or two op-sets) as a list of
+``NodeChange`` records, replacing raw unified diffs for review. The primitive
+reuses capture's blob→nodes pipeline, so the ids shown are the same stable
+node ids the op-log stores — the graph is the query plane over node history.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from awgit.capture import (
+    default_repo,
+    diff_sources,
+    git_blob,
+    git_changed_files,
+    load_node_manager,
+)
+from awgit.data_root import vcs_data_root
+from awgit.schema import EditOp, NodeChange
+
+
+def diff_git(
+    a_sha: str,
+    b_sha: str,
+    *,
+    repo_path: Optional[str] = None,
+    root_path: Optional[str] = None,
+    data_root: Optional[Path] = None,
+) -> List[NodeChange]:
+    """Node-level diff between two git shas (Python files only)."""
+    repo = Path(repo_path or default_repo())
+    files = sorted(
+        set(git_changed_files(repo, a_sha)) | set(git_changed_files(repo, b_sha))
+    )
+    data = data_root or vcs_data_root(root_path=root_path)
+    manager = load_node_manager(data)
+    changes: List[NodeChange] = []
+    for rel in files:
+        if not rel.endswith(".py"):
+            continue
+        changes.extend(
+            diff_sources(
+                git_blob(repo, a_sha, rel),
+                git_blob(repo, b_sha, rel),
+                rel,
+                manager,
+            )
+        )
+    return changes
+
+
+def diff_opsets(a_ops: List[EditOp], b_ops: List[EditOp]) -> Dict[str, List[str]]:
+    """Overlap summary of two op-sets — the merge engine's collision primitive."""
+    a = {nc.node_id for op in a_ops for nc in op.node_changes}
+    b = {nc.node_id for op in b_ops for nc in op.node_changes}
+    return {
+        "only_a": sorted(a - b),
+        "only_b": sorted(b - a),
+        "shared": sorted(a & b),
+    }
+
+
+def render(changes: List[NodeChange]) -> List[str]:
+    """Human/agent-readable lines for a node-level diff."""
+    out: List[str] = []
+    for c in changes:
+        loc = c.path
+        if c.symbol:
+            loc = f"{c.path}:{c.symbol}"
+        if c.change_type == "body_rewrite":
+            detail = f"body {c.old_body_sha[:8] or '?'} -> {c.new_body_sha[:8] or '?'}"
+        elif c.change_type == "added":
+            detail = "added"
+        elif c.change_type == "deleted":
+            detail = "deleted"
+        else:
+            detail = c.change_type
+        out.append(f"[{c.change_type}] {loc} — {detail}")
+    return out

awgit/hooks/chain.sh

@@ -0,0 +1,38 @@
+#!/bin/sh
+# aither-vcs-chain — generated by install_hooks, do not edit by hand.
+# Runs the pre-existing hook body (<hook>.org) in a SUBSHELL so an `exec`
+# inside it (the original pre-commit ends in `exec python tools/secret_scan.py`)
+# cannot terminate this chain, then runs the .d fragments.
+#
+# Exit-code contract: the FIRST non-zero exit among the .org body and the
+# fragments is propagated. A pre-existing gate (the secret scanner) that fails
+# must STILL fail the hook — a chain that swallowed it would silently disable
+# it. Fragments always run, so a failure in one never silently skips another
+# (the post-commit capture still runs even if the CD-autosync trigger failed).
+# Both the .org and each fragment run in a SUBSHELL: an `exec` (the real
+# pre-commit) or a bare `exit 0` (the lease-check guard) must never terminate
+# the chain before the exit-code decision at the bottom.
+set -u
+HOOK_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
+HOOK_NAME="$(basename -- "$0")"
+
+ORG_RC=0
+if [ -f "$HOOK_DIR/$HOOK_NAME.org" ]; then
+  ( . "$HOOK_DIR/$HOOK_NAME.org" "$@" )
+  ORG_RC=$?
+fi
+
+FRAG_RC=0
+FRAG_DIR="$HOOK_DIR/$HOOK_NAME.d"
+if [ -d "$FRAG_DIR" ]; then
+  for frag in "$FRAG_DIR"/*; do
+    [ -f "$frag" ] || continue
+    [ -x "$frag" ] || continue
+    ( . "$frag" "$@" ) || { FRAG_RC=$?; break; }
+  done
+fi
+
+if [ "$ORG_RC" -ne 0 ]; then
+  exit "$ORG_RC"
+fi
+exit "$FRAG_RC"

awgit/hooks/post-commit.d/vcs-capture

@@ -0,0 +1,38 @@
+#!/bin/sh
+# aither-vcs-fragment — capture the new commit as a semantic edit-op.
+# Best-effort: the commit already happened, so a capture failure is logged to
+# <git-dir>/vcs-capture.log and NEVER breaks the commit. Skip paths are LOUD,
+# never silent: if the fragment cannot resolve HEAD or the awgit CLI it logs
+# why — a silent skip is how a dead capture reads as "nothing to capture".
+#
+# GOTCHA: git invokes post-commit with NO arguments. The fragment must resolve
+# the new commit from `git rev-parse --verify HEAD` — assuming `$1` is the sha
+# made the automatic capture exit silently on every real commit while manual
+# invocations (which passed the sha) worked fine.
+set -u
+GITDIR="$(git rev-parse --git-dir 2>/dev/null)" || GITDIR=".git"
+LOG="$GITDIR/vcs-capture.log"
+SHA="${1:-}"
+if [ -z "$SHA" ]; then
+  SHA="$(git rev-parse --verify HEAD 2>/dev/null)"
+fi
+[ -n "$SHA" ] || {
+  echo "vcs: capture skipped — no sha and cannot resolve HEAD" >> "$LOG" 2>&1
+  exit 0
+}
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null)" || {
+  echo "vcs: capture skipped — not a git worktree (hook cwd: $PWD)" >> "$LOG" 2>&1
+  exit 0
+}
+if ! command -v awgit >/dev/null 2>&1 && ! command -v python >/dev/null 2>&1; then
+  echo "vcs: capture skipped — neither awgit nor python on PATH" >> "$LOG" 2>&1
+  exit 0
+fi
+{
+  if command -v awgit >/dev/null 2>&1; then
+    awgit capture --sha "$SHA"
+  else
+    python -m awgit.cli capture --sha "$SHA"
+  fi
+} >> "$LOG" 2>&1 || true
+exit 0

awgit/hooks/pre-commit.d/vcs-lease-check

@@ -0,0 +1,15 @@
+#!/bin/sh
+# aither-vcs-fragment — lease gate. Enforced ONLY when VCS_LEASES_ENFORCE=1.
+# Default OFF: agents that never lease can still commit; their ops are flagged
+# leased=false.
+set -u
+[ "${VCS_LEASES_ENFORCE:-0}" = "1" ] || exit 0
+if command -v awgit >/dev/null 2>&1; then
+  awgit lease-check
+else
+  python -m awgit.cli lease-check
+fi || {
+  echo "vcs: pre-commit lease gate rejected the commit" >&2
+  exit 1
+}
+exit 0