awgit 1.1.2__tar.gz → 1.3.0__tar.gz

{awgit-1.1.2/awgit.egg-info → awgit-1.3.0}/PKG-INFO

@@ -1,16 +1,18 @@
 Metadata-Version: 2.4
 Name: awgit
-Version: 1.1.2
+Version: 1.3.0
 Summary: Aither World-Graph git — semantic version control on top of git: edit-ops keyed on stable node ids, content-addressed bodies, differential sync.
 License: Apache-2.0
+Project-URL: Homepage, https://github.com/Aitherium/awgit
+Project-URL: Documentation, https://aitherium.github.io/awgit/
+Project-URL: Repository, https://github.com/Aitherium/awgit.git
+Project-URL: Issues, https://github.com/Aitherium/awgit/issues
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: httpx>=0.25.0
 Provides-Extra: multilang
 Requires-Dist: repowise>=0.31.0; extra == "multilang"
-Provides-Extra: tabular
-Requires-Dist: pyarrow>=15.0.0; extra == "tabular"
 Dynamic: license-file
 
 # awgit — the git that knows a function from a line
@@ -205,42 +207,8 @@ awgit ledger --sha <sha>      # who changed what, under a verified identity
 awgit evidence                # the measurable claim, from your own op-log
 awgit bodies --get <sha>      # read a body from the content-addressed store
 awgit dedupe --scan <trees>   # quantify duplication; --reclaim to hard-link
-awgit data diff <a> <b> --key id   # ROW-level diff of CSV/TSV/parquet
 ```
 
-### Data files get the same treatment as code
-
-A line diff is useless on a table: sort it and every line "changed"; reorder two
-rows and a review drowns. So a row gets the same pair a function gets — an
-**identity** and a **content address**:
-
-```
-row identity = H(the --key columns)   # which row is this?
-row content  = H(every column)        # has it changed?
-```
-
-The diff is then set algebra on identity, so rows can be reordered freely and
-nothing is reported:
-
-```bash
-awgit data diff old.csv new.csv --key id          # 1 added, 1 removed, 1 modified
-awgit data diff old.csv new.csv --key id --json   # before/after per modified row
-```
-
-Without `--key` there is no identity, so it degrades to a content set-diff and
-**says so** — every edit reads as an add plus a remove, and `modified` stays
-empty rather than being guessed at. A key column that exists in neither table is
-an error, not an empty result: silently keying on a missing column would report
-every row as added *and* removed, which looks exactly like data loss.
-
-CSV and TSV need nothing beyond the stdlib. Parquet needs the optional extra:
-`pip install awgit[tabular]`.
-
-*The two-hash row model is adapted from [Oxen](https://github.com/oxen-ai/Oxen)
-(Apache-2.0). No Oxen code is vendored, and awgit's byte encoding deliberately
-differs — it length-prefixes each field so that two different rows cannot share
-a content address — so hashes are not comparable between the two tools.*
-
 - **Merge** at node granularity: disjoint node sets merge clean by
   construction, and a genuine collision escalates naming the exact function
   (`awgit merge-preview`, `awgit merge-conflicts`, `awgit resolve-conflict`).
@@ -296,3 +264,66 @@ cd awgit && python -m pytest tests/ -q
 ## License
 
 Apache-2.0. Built by Aitherium — the git that scales to agents.
+
+---
+
+<!-- aither-ecosystem:start GENERATED from the ecosystem registry. Edits here are overwritten; change the registry instead. -->
+
+## The aw family
+
+Standalone tools that share one idea: **replace something you would otherwise have to _trust_ with something you can _check_.**
+
+Each installs on its own, works offline, and needs no account.
+
+| | instead of trusting | you check |
+|---|---|---|
+| [awdk](https://github.com/Aitherium/awdk) | a framework's idea of how your agents should run | one loop you can read, pointed at a backend you already pay for |
+| [awskills](https://github.com/Aitherium/awskills) | that an agent knows your procedure | the procedure written down, versioned, and loadable by any agent |
+| [awm](https://github.com/Aitherium/awm) | that memory stayed in its lane | tenant:user:project scopes, so a write cannot cross a boundary |
+| [awnode](https://github.com/Aitherium/awnode) | a vendor's cloud with every prompt | a local gateway routing to backends you chose |
+| [awgraph](https://github.com/Aitherium/awgraph) | that grep found everything | an AST + tree-sitter call graph an agent can traverse |
+| **awgit** _(you are here)_ | that no one else is editing this file | a lease, refused at commit time if you do not hold it |
+| [awseal](https://github.com/Aitherium/awseal) | that the artifact came from who you think | an Ed25519 seal — the key that verifies is not the key that forges |
+| [awshare](https://github.com/Aitherium/awshare) | that the download is intact | content-addressed bundles, verified on fetch |
+| [awnest](https://github.com/Aitherium/awnest) | that there is a person on the other end | a verdict with evidence, where "we could not tell" is not "yes" |
+| [awnboard](https://github.com/Aitherium/awnboard) | a share link anyone who sees it can use | an invitation addressed to one person, for one gate, revocable |
+| [awnix](https://github.com/Aitherium/awnix) | that the box is what you left it as | an immutable image you built, with atomic rollback |
+| [awrecover](https://github.com/Aitherium/awrecover) | that the restore worked | a restore that fully lands or does not land at all |
+| [awrelay](https://github.com/Aitherium/awrelay) | a SaaS in the middle of your agents | findings, alerts and coordination over your own transport |
+| [awmail](https://github.com/Aitherium/awmail) | a mailbox somebody else can read | mail your agents send and receive over your own server |
+| [awfind](https://github.com/Aitherium/awfind) | one vendor's idea of the web | results from whichever providers you configured |
+| [awbrowse](https://github.com/Aitherium/awbrowse) | that the page said what you were told | the render, the DOM and the requests it made |
+| [aitherkvcache](https://github.com/Aitherium/aitherkvcache) | a vendor's quantisation defaults | sub-byte KV cache kernels you can benchmark yourself |
+| [AitherZero](https://github.com/Aitherium/AitherZero) | a pile of scripts nobody has numbered | numbered, discoverable automation with declarative playbooks |
+| [AitherConnect](https://github.com/Aitherium/AitherConnect) | what a page tells your browser to do | a federated search and desktop bridge you host |
+
+[**awnix**](https://github.com/Aitherium/awnix) is the ground floor — A Linux you can hand to an agent — immutable base, capabilities included.
+
+## The Aitherium ecosystem
+
+Every repository here is public. Each publishes an `aither-manifest.json` beside its page, so any surface can read every sibling's — the network is browsable from any node in it.
+
+| repo | what it is | pages |
+|---|---|---|
+| [awdk](https://github.com/Aitherium/awdk) | Build AI agent fleets — 3 lines, any backend, local or cloud | [docs](https://aitherium.github.io/awdk/) |
+| [awskills](https://github.com/Aitherium/awskills) | Portable agent skills — self-contained procedures an agent loads on demand | [docs](https://aitherium.github.io/awskills/) |
+| [awm](https://github.com/Aitherium/awm) | A portable, scoped agent memory | [docs](https://aitherium.github.io/awm/) |
+| [awnode](https://github.com/Aitherium/awnode) | A lightweight local gateway — bridges your apps to the AI backends you chose | [docs](https://aitherium.github.io/awnode/) |
+| [awrun](https://github.com/Aitherium/awrun) | A priority-aware queue and dispatcher for agentic runs and ad-hoc CI builds | [docs](https://aitherium.github.io/awrun/) |
+| [awgraph](https://github.com/Aitherium/awgraph) | A semantic code graph for agents — AST + tree-sitter, call graphs | [docs](https://aitherium.github.io/awgraph/) |
+| **awgit** _(you are here)_ | Semantic version control on top of git — edit-ops and leases | [docs](https://aitherium.github.io/awgit/) |
+| [awseal](https://github.com/Aitherium/awseal) | Sign an artifact so a stranger can verify it | [docs](https://aitherium.github.io/awseal/) |
+| [awshare](https://github.com/Aitherium/awshare) | Publish an artifact and fetch it back verified | [docs](https://aitherium.github.io/awshare/) |
+| [awnest](https://github.com/Aitherium/awnest) | Prove there is a human before you let them into the nest | — |
+| [awnboard](https://github.com/Aitherium/awnboard) | A front gate you can put in front of anything, and hand someone the key to | — |
+| [awnix](https://github.com/Aitherium/awnix) | A Linux you can hand to an agent — immutable base, capabilities included | [docs](https://aitherium.github.io/awnix/) |
+| [awrecover](https://github.com/Aitherium/awrecover) | Labelled snapshots with an all-or-nothing restore | [docs](https://aitherium.github.io/awrecover/) |
+| [awrelay](https://github.com/Aitherium/awrelay) | Portable agent messaging — findings, alerts, coordination | [docs](https://aitherium.github.io/awrelay/) |
+| [awmail](https://github.com/Aitherium/awmail) | Give an agent an email address — send, and actually receive | — |
+| [awfind](https://github.com/Aitherium/awfind) | A portable search client — query, results, ranking | — |
+| [awbrowse](https://github.com/Aitherium/awbrowse) | A portable browser client — navigate, console, network, DOM, screenshot | — |
+| [aitherkvcache](https://github.com/Aitherium/aitherkvcache) | Near-optimal KV cache quantization for LLM inference — sub-byte compression | [docs](https://aitherium.github.io/aitherkvcache/) |
+| [AitherZero](https://github.com/Aitherium/AitherZero) | PowerShell 7+ automation framework — numbered, self-describing scripts | [docs](https://aitherium.github.io/AitherZero/) |
+| [AitherConnect](https://github.com/Aitherium/AitherConnect) | Browser extension — federated AI search, page context, and the Living OS overlay | — |
+
+<!-- aither-ecosystem:end -->

awgit-1.1.2/PKG-INFO → awgit-1.3.0/README.md

@@ -1,18 +1,3 @@
-Metadata-Version: 2.4
-Name: awgit
-Version: 1.1.2
-Summary: Aither World-Graph git — semantic version control on top of git: edit-ops keyed on stable node ids, content-addressed bodies, differential sync.
-License: Apache-2.0
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: httpx>=0.25.0
-Provides-Extra: multilang
-Requires-Dist: repowise>=0.31.0; extra == "multilang"
-Provides-Extra: tabular
-Requires-Dist: pyarrow>=15.0.0; extra == "tabular"
-Dynamic: license-file
-
 # awgit — the git that knows a function from a line
 
 Git has no world model. It knows which lines moved, not what a function is — so
@@ -205,42 +190,8 @@ awgit ledger --sha <sha>      # who changed what, under a verified identity
 awgit evidence                # the measurable claim, from your own op-log
 awgit bodies --get <sha>      # read a body from the content-addressed store
 awgit dedupe --scan <trees>   # quantify duplication; --reclaim to hard-link
-awgit data diff <a> <b> --key id   # ROW-level diff of CSV/TSV/parquet
-```
-
-### Data files get the same treatment as code
-
-A line diff is useless on a table: sort it and every line "changed"; reorder two
-rows and a review drowns. So a row gets the same pair a function gets — an
-**identity** and a **content address**:
-
-```
-row identity = H(the --key columns)   # which row is this?
-row content  = H(every column)        # has it changed?
-```
-
-The diff is then set algebra on identity, so rows can be reordered freely and
-nothing is reported:
-
-```bash
-awgit data diff old.csv new.csv --key id          # 1 added, 1 removed, 1 modified
-awgit data diff old.csv new.csv --key id --json   # before/after per modified row
 ```
 
-Without `--key` there is no identity, so it degrades to a content set-diff and
-**says so** — every edit reads as an add plus a remove, and `modified` stays
-empty rather than being guessed at. A key column that exists in neither table is
-an error, not an empty result: silently keying on a missing column would report
-every row as added *and* removed, which looks exactly like data loss.
-
-CSV and TSV need nothing beyond the stdlib. Parquet needs the optional extra:
-`pip install awgit[tabular]`.
-
-*The two-hash row model is adapted from [Oxen](https://github.com/oxen-ai/Oxen)
-(Apache-2.0). No Oxen code is vendored, and awgit's byte encoding deliberately
-differs — it length-prefixes each field so that two different rows cannot share
-a content address — so hashes are not comparable between the two tools.*
-
 - **Merge** at node granularity: disjoint node sets merge clean by
   construction, and a genuine collision escalates naming the exact function
   (`awgit merge-preview`, `awgit merge-conflicts`, `awgit resolve-conflict`).
@@ -296,3 +247,66 @@ cd awgit && python -m pytest tests/ -q
 ## License
 
 Apache-2.0. Built by Aitherium — the git that scales to agents.
+
+---
+
+<!-- aither-ecosystem:start GENERATED from the ecosystem registry. Edits here are overwritten; change the registry instead. -->
+
+## The aw family
+
+Standalone tools that share one idea: **replace something you would otherwise have to _trust_ with something you can _check_.**
+
+Each installs on its own, works offline, and needs no account.
+
+| | instead of trusting | you check |
+|---|---|---|
+| [awdk](https://github.com/Aitherium/awdk) | a framework's idea of how your agents should run | one loop you can read, pointed at a backend you already pay for |
+| [awskills](https://github.com/Aitherium/awskills) | that an agent knows your procedure | the procedure written down, versioned, and loadable by any agent |
+| [awm](https://github.com/Aitherium/awm) | that memory stayed in its lane | tenant:user:project scopes, so a write cannot cross a boundary |
+| [awnode](https://github.com/Aitherium/awnode) | a vendor's cloud with every prompt | a local gateway routing to backends you chose |
+| [awgraph](https://github.com/Aitherium/awgraph) | that grep found everything | an AST + tree-sitter call graph an agent can traverse |
+| **awgit** _(you are here)_ | that no one else is editing this file | a lease, refused at commit time if you do not hold it |
+| [awseal](https://github.com/Aitherium/awseal) | that the artifact came from who you think | an Ed25519 seal — the key that verifies is not the key that forges |
+| [awshare](https://github.com/Aitherium/awshare) | that the download is intact | content-addressed bundles, verified on fetch |
+| [awnest](https://github.com/Aitherium/awnest) | that there is a person on the other end | a verdict with evidence, where "we could not tell" is not "yes" |
+| [awnboard](https://github.com/Aitherium/awnboard) | a share link anyone who sees it can use | an invitation addressed to one person, for one gate, revocable |
+| [awnix](https://github.com/Aitherium/awnix) | that the box is what you left it as | an immutable image you built, with atomic rollback |
+| [awrecover](https://github.com/Aitherium/awrecover) | that the restore worked | a restore that fully lands or does not land at all |
+| [awrelay](https://github.com/Aitherium/awrelay) | a SaaS in the middle of your agents | findings, alerts and coordination over your own transport |
+| [awmail](https://github.com/Aitherium/awmail) | a mailbox somebody else can read | mail your agents send and receive over your own server |
+| [awfind](https://github.com/Aitherium/awfind) | one vendor's idea of the web | results from whichever providers you configured |
+| [awbrowse](https://github.com/Aitherium/awbrowse) | that the page said what you were told | the render, the DOM and the requests it made |
+| [aitherkvcache](https://github.com/Aitherium/aitherkvcache) | a vendor's quantisation defaults | sub-byte KV cache kernels you can benchmark yourself |
+| [AitherZero](https://github.com/Aitherium/AitherZero) | a pile of scripts nobody has numbered | numbered, discoverable automation with declarative playbooks |
+| [AitherConnect](https://github.com/Aitherium/AitherConnect) | what a page tells your browser to do | a federated search and desktop bridge you host |
+
+[**awnix**](https://github.com/Aitherium/awnix) is the ground floor — A Linux you can hand to an agent — immutable base, capabilities included.
+
+## The Aitherium ecosystem
+
+Every repository here is public. Each publishes an `aither-manifest.json` beside its page, so any surface can read every sibling's — the network is browsable from any node in it.
+
+| repo | what it is | pages |
+|---|---|---|
+| [awdk](https://github.com/Aitherium/awdk) | Build AI agent fleets — 3 lines, any backend, local or cloud | [docs](https://aitherium.github.io/awdk/) |
+| [awskills](https://github.com/Aitherium/awskills) | Portable agent skills — self-contained procedures an agent loads on demand | [docs](https://aitherium.github.io/awskills/) |
+| [awm](https://github.com/Aitherium/awm) | A portable, scoped agent memory | [docs](https://aitherium.github.io/awm/) |
+| [awnode](https://github.com/Aitherium/awnode) | A lightweight local gateway — bridges your apps to the AI backends you chose | [docs](https://aitherium.github.io/awnode/) |
+| [awrun](https://github.com/Aitherium/awrun) | A priority-aware queue and dispatcher for agentic runs and ad-hoc CI builds | [docs](https://aitherium.github.io/awrun/) |
+| [awgraph](https://github.com/Aitherium/awgraph) | A semantic code graph for agents — AST + tree-sitter, call graphs | [docs](https://aitherium.github.io/awgraph/) |
+| **awgit** _(you are here)_ | Semantic version control on top of git — edit-ops and leases | [docs](https://aitherium.github.io/awgit/) |
+| [awseal](https://github.com/Aitherium/awseal) | Sign an artifact so a stranger can verify it | [docs](https://aitherium.github.io/awseal/) |
+| [awshare](https://github.com/Aitherium/awshare) | Publish an artifact and fetch it back verified | [docs](https://aitherium.github.io/awshare/) |
+| [awnest](https://github.com/Aitherium/awnest) | Prove there is a human before you let them into the nest | — |
+| [awnboard](https://github.com/Aitherium/awnboard) | A front gate you can put in front of anything, and hand someone the key to | — |
+| [awnix](https://github.com/Aitherium/awnix) | A Linux you can hand to an agent — immutable base, capabilities included | [docs](https://aitherium.github.io/awnix/) |
+| [awrecover](https://github.com/Aitherium/awrecover) | Labelled snapshots with an all-or-nothing restore | [docs](https://aitherium.github.io/awrecover/) |
+| [awrelay](https://github.com/Aitherium/awrelay) | Portable agent messaging — findings, alerts, coordination | [docs](https://aitherium.github.io/awrelay/) |
+| [awmail](https://github.com/Aitherium/awmail) | Give an agent an email address — send, and actually receive | — |
+| [awfind](https://github.com/Aitherium/awfind) | A portable search client — query, results, ranking | — |
+| [awbrowse](https://github.com/Aitherium/awbrowse) | A portable browser client — navigate, console, network, DOM, screenshot | — |
+| [aitherkvcache](https://github.com/Aitherium/aitherkvcache) | Near-optimal KV cache quantization for LLM inference — sub-byte compression | [docs](https://aitherium.github.io/aitherkvcache/) |
+| [AitherZero](https://github.com/Aitherium/AitherZero) | PowerShell 7+ automation framework — numbered, self-describing scripts | [docs](https://aitherium.github.io/AitherZero/) |
+| [AitherConnect](https://github.com/Aitherium/AitherConnect) | Browser extension — federated AI search, page context, and the Living OS overlay | — |
+
+<!-- aither-ecosystem:end -->

{awgit-1.1.2 → awgit-1.3.0}/awgit/cli.py

@@ -91,6 +91,19 @@ def _cmd_capture(args: argparse.Namespace) -> int:
         print(f"vcs: no semantic changes for {args.sha}")
         return 0
     print(f"vcs: op {op.op_id} recorded ({op.summary})")
+
+    # Record proof of verification if requested
+    if getattr(args, "prove", False):
+        try:
+            from awgit.outcomes import record_outcome
+            from awgit.prove import run_gates
+            data_root = Path(args.data_root) if args.data_root else None
+            gates = run_gates(op.file_paths)
+            outcome = record_outcome(args.sha, gates, data_root=data_root)
+            print(f"vcs: outcome {outcome.outcome_id} recorded ({outcome.verdict})")
+        except Exception as exc:
+            print(f"vcs: proof recording failed (non-fatal): {exc}", file=sys.stderr)
+
     return 0
 
 
@@ -232,10 +245,45 @@ def _cmd_status(args: argparse.Namespace) -> int:
     return 0
 
 
+def _resolve_lease_args(registry, who, raw):
+    """Map release/heartbeat arguments to lease ids, accepting leased PATHS too.
+
+    `acquire` takes paths and `release` takes ids, so passing the same string to
+    both is the natural mistake -- and it used to be a silent one, because an
+    unmatched id simply released nothing and still printed success.
+
+    Returns (ids, unresolved). Anything that is neither one of this actor's
+    active lease ids nor one of its leased targets comes back in `unresolved`,
+    so the caller can fail rather than report a count of zero.
+    """
+    mine = [lz for lz in registry.active_leases() if lz.actor == who]
+    by_id = {lz.lease_id: lz.lease_id for lz in mine}
+    by_target = {}
+    for lz in mine:
+        # Last writer wins is fine: releasing any lease on that path is the
+        # intent, and a duplicate target for one actor is already a bug.
+        by_target[str(lz.target).replace("\\", "/").strip("/")] = lz.lease_id
+    ids, unresolved = [], []
+    for arg in raw or []:
+        if arg in by_id:
+            ids.append(arg)
+            continue
+        key = str(arg).replace("\\", "/").strip("/")
+        if key in by_target:
+            ids.append(by_target[key])
+            continue
+        unresolved.append(arg)
+    return ids, unresolved
+
+
 def _cmd_lease(args: argparse.Namespace) -> int:
     registry = LeaseRegistry()
     cmd = args.lease_cmd
     who = _actor(args)
+    if cmd == "contact":
+        return _cmd_lease_contact(args)
+    if cmd == "requests":
+        return _cmd_lease_requests(args)
     if cmd == "acquire":
         targets = list(args.targets or [])
         if getattr(args, "staged", False):
@@ -290,7 +338,19 @@ def _cmd_lease(args: argparse.Namespace) -> int:
                 who, targets, ttl_sec=args.ttl, reason=args.reason
             )
         except LeaseConflictError as exc:
+            # Flush stdout FIRST. It is block-buffered when redirected to a file
+            # or a pipe and stderr is not, so this line otherwise lands
+            # INTERLEAVED in the middle of whatever stdout had buffered rather
+            # than at the end where anyone looks. Measured 2026-08-19:
+            # `lease acquire --staged --adopt` over 1776 files refused correctly
+            # on a real conflict, and the one line saying why was glued onto the
+            # middle of the adoption list at line 1657 of 1778 -- head and tail
+            # both missed it, and a correct refusal got reported as "awgit exits
+            # 1 and persists nothing". A diagnostic nobody can find is worse than
+            # none: it gets diagnosed as a different bug.
+            sys.stdout.flush()
             print(f"vcs: {exc}", file=sys.stderr)
+            sys.stderr.flush()
             return 1
         # A lease over an ALREADY-DIRTY file captures a baseline that contains work
         # which is not yours, and `stage-mine` computes (baseline -> worktree), so it
@@ -316,11 +376,28 @@ def _cmd_lease(args: argparse.Namespace) -> int:
                   "`git diff --stat -- <path>` must match the size of YOUR edit.",
                   file=sys.stderr)
         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")
+    if cmd in ("heartbeat", "release"):
+        # `release`/`heartbeat` take lease IDS. Passing a PATH -- the same string
+        # `acquire` takes, and the obvious guess -- matched no id, so the registry
+        # returned 0 and this printed "released 0 leases" and exited 0 while the
+        # lease sat there in `lease list`. A command that reports success for
+        # having done nothing is the silent-no-op class in
+        # .claude/rules/security-review-patterns.md #5, and it cost a session on
+        # 2026-08-16: the release "succeeded", the lease stayed held, and the next
+        # edit was blocked by the caller's own lease.
+        # Resolve path-shaped arguments against this actor's active leases, and
+        # refuse anything that resolves to nothing rather than reporting 0.
+        ids, unresolved = _resolve_lease_args(registry, who, args.ids)
+        if unresolved:
+            print("vcs: no active lease of yours matches: " + ", ".join(unresolved),
+                  file=sys.stderr)
+            print("vcs: pass a lease id or a leased path (`awgit lease list`)",
+                  file=sys.stderr)
+            return 1
+        if cmd == "heartbeat":
+            print(f"vcs: heartbeat refreshed {registry.heartbeat(who, ids)} leases")
+        else:
+            print(f"vcs: released {registry.release(who, ids)} leases")
         return 0
     if cmd == "list":
         for lz in sorted(registry.active_leases(), key=lambda x: x.target):
@@ -561,6 +638,95 @@ def _merge_hand_resolved(repo: Path, staged: List[str]) -> List[str]:
     return hand
 
 
+def _requests_store():
+    """(LeaseRequests, registry) or (None, None) if the plane is unreadable."""
+    try:
+        from .lease_requests import LeaseRequests
+        from .leases import LeaseRegistry, vcs_data_root
+        reg = LeaseRegistry()
+        return LeaseRequests(vcs_data_root()), reg
+    except Exception as exc:            # noqa: BLE001 - never fatal
+        print(f"vcs: lease-request store unavailable ({exc})", file=sys.stderr)
+        return None, None
+
+
+def _relay_notify(to_actor: str, target: str, message: str) -> bool:
+    """Best-effort async ping. NEVER the only delivery path.
+
+    Returns False when it could not send, so the caller can say so rather than
+    implying the holder was reached. Relay is optional here on purpose: if the
+    only notification depended on a running service, this feature would be
+    unavailable in exactly the degraded conditions that produce lease pile-ups.
+    """
+    try:
+        from awrelay.client import RelayClient       # type: ignore
+    except ImportError:
+        return False
+    try:
+        who = to_actor.split(":")[-1][:8]
+        RelayClient().send(
+            channel="lease-negotiation",
+            text=f"@{who} please release `{target}` — {message or 'another '
+                 'session is blocked on it'}")
+        return True
+    except Exception:                    # noqa: BLE001
+        return False
+
+
+def _cmd_lease_contact(args) -> int:
+    """Ask whoever holds a path's lease to let it go."""
+    store, reg = _requests_store()
+    if store is None or reg is None:
+        return 2
+    me = _actor(args)
+    target = args.path
+
+    holder = None
+    for lz in reg.active_leases():
+        if lz.target == target:
+            holder = lz
+            break
+    if holder is None:
+        print(f"vcs: no active lease on {target!r} — nothing to ask for. "
+              f"If a commit was refused, re-run `awgit lease acquire`.")
+        return 0
+    if holder.actor == me:
+        print(f"vcs: {target!r} is held by YOU ({me}); "
+              f"`awgit lease release {holder.lease_id}` frees it.")
+        return 0
+
+    store.add(target, holder.actor, me, getattr(args, "message", "") or "")
+    relayed = _relay_notify(holder.actor, target,
+                            getattr(args, "message", "") or "")
+    print(f"vcs: asked {holder.actor} to release {target!r} "
+          f"(expires {holder.expires_ts}).")
+    print("vcs: they see it on their next `awgit lease list`"
+          + (" and on relay #lease-negotiation." if relayed
+             else " (relay unavailable — the awgit path still delivers)."))
+    return 0
+
+
+def _cmd_lease_requests(args) -> int:
+    """What am I blocking, and what am I waiting on?"""
+    store, _ = _requests_store()
+    if store is None:
+        return 2
+    me = _actor(args)
+    from .lease_requests import format_pending
+
+    incoming = store.for_actor(me)
+    outgoing = store.by_actor(me)
+    if incoming:
+        print(format_pending(incoming))
+    else:
+        print("vcs: nobody is blocked on leases you hold.")
+    if outgoing:
+        print(f"vcs: you have asked for {len(outgoing)} lease(s):")
+        for r in outgoing[:10]:
+            print(f"vcs:   {r.get('target')} <- {str(r.get('to_actor'))[:24]}")
+    return 0
+
+
 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)")
@@ -1477,6 +1643,11 @@ def build_parser() -> argparse.ArgumentParser:
         default=None,
         help="vcs store directory (default: ~/.aither/awgit/data, or $VCS_DATA_ROOT)",
     )
+    p_capture.add_argument(
+        "--prove",
+        action="store_true",
+        help="run gates and record the outcome after capture",
+    )
 
     p_diff = sub.add_parser("diff", help="node-level diff between two shas")
     p_diff.add_argument("a", help="base sha")
@@ -1555,6 +1726,17 @@ def build_parser() -> argparse.ArgumentParser:
     p_ll = lsub.add_parser("list", help="list active leases")
     p_ll.add_argument("--json", action="store_true", dest="as_json")
     lsub.add_parser("sweep", help="sweep expired leases")
+    p_lc = lsub.add_parser(
+        "contact",
+        help="ask whoever holds a path's lease to release it -- the missing "
+             "half of 'talk to them or wait'")
+    p_lc.add_argument("path")
+    p_lc.add_argument("-m", "--message", default="", help="why you need it")
+    p_lc.add_argument("--actor", default=None)
+    p_lq = lsub.add_parser(
+        "requests",
+        help="who is blocked on YOUR leases, and what you are waiting on")
+    p_lq.add_argument("--actor", default=None)
 
     p_lc = sub.add_parser("lease-check", help="pre-commit lease gate")
     p_lc.add_argument("--actor", default=None)

{awgit-1.1.2 → awgit-1.3.0}/awgit/guard.py

@@ -144,6 +144,123 @@ def check(actor: str, cwd: Optional[Path] = None) -> Verdict:
     return Verdict(True, basis="no other actor holds a lease in this worktree")
 
 
+#: The branch a PUBLISHED artifact is supposed to come from. Overridable, because
+#: a product with its own release branch is a real thing -- but it has a default,
+#: because "which branch should this have been built from" is not a question the
+#: person mid-deploy should have to answer.
+DEFAULT_DEPLOY_REF = "origin/develop"
+
+
+@dataclass
+class ShipVerdict:
+    """Is this working tree fit to build a PUBLISHED artifact from?
+
+    Separate from `Verdict` on purpose: that one asks whether rewriting history
+    here would destroy a peer's work, this one asks whether shipping from here
+    would publish something old. Same tree, different danger.
+    """
+
+    ok: bool
+    behind: int = 0
+    ahead: int = 0
+    ref: str = DEFAULT_DEPLOY_REF
+    head: str = ""
+    reasons: List[str] = field(default_factory=list)
+    fix: List[str] = field(default_factory=list)
+    #: True when the question could not be ANSWERED (no such ref, not a repo).
+    #: Callers must treat this as a refusal, never as a pass -- an unanswerable
+    #: staleness check is exactly the state that let a stale build ship.
+    unknown: bool = False
+
+    def report(self) -> str:
+        head, *rest = self.reasons or ["unfit to publish from"]
+        lines = [f"awgit: refusing to publish — {head}"]
+        lines += [f"awgit: {r}" for r in rest]
+        lines += [f"awgit: {f}" for f in self.fix]
+        return "\n".join(lines)
+
+
+def behind_deploy_ref(
+    cwd: Optional[Path] = None, ref: str = DEFAULT_DEPLOY_REF
+) -> ShipVerdict:
+    """How far the current checkout is behind the branch releases come from.
+
+    🚨 WHY THIS EXISTS, measured 2026-08-20. Two customer-facing sites were
+    published from a feature branch **587 commits behind the deploy branch**. The build succeeded, every gate
+    passed, the export was byte-valid, and the sites came up looking right. What
+    shipped was a desktop carrying a bug that had been FIXED on develop earlier
+    that same day (the Aeon window could not be dragged, because its body was not
+    a containing block, so app content painted over the only drag handle).
+
+    Nothing in the pipeline could see it. A build does not know what it is missing;
+    `git status` is clean on a stale branch; and the artifact is *correct*, just
+    old. The only signal was the owner recognising a bug he had already had fixed.
+
+    Two hours of that session were also spent re-deriving fixes that already
+    existed on develop -- the same route exclusion, the same malformed blog post.
+    Staleness does not only ship old code, it burns the time spent rebuilding what
+    someone already built.
+
+    Answers from the LOCAL ref: this must be usable in a publish path that may have
+    no network, and a fetch that silently fails would turn "up to date" into a lie.
+    `stale_ref_age_days` reports how old the local ref is so a caller can insist on
+    a fetch when it matters, rather than this function pretending to know.
+    """
+    repo = repo_root(cwd)
+    if repo is None:
+        return ShipVerdict(
+            ok=False, unknown=True, ref=ref,
+            reasons=["not inside a git repository, so staleness cannot be judged"],
+            fix=["run this from the repo, or pass an explicit --allow-stale reason"],
+        )
+
+    head = _git(repo, "rev-parse", "--short", "HEAD").strip()
+    # `rev-list --count A..B` counts commits in B not in A.
+    raw = _git(repo, "rev-list", "--left-right", "--count", f"HEAD...{ref}").strip()
+    parts = raw.split()
+    if len(parts) != 2 or not all(x.isdigit() for x in parts):
+        return ShipVerdict(
+            ok=False, unknown=True, ref=ref, head=head,
+            reasons=[f"could not compare HEAD against {ref} (is it fetched?)"],
+            fix=[f"git fetch origin && retry, or pass --allow-stale with a reason"],
+        )
+    ahead, behind = int(parts[0]), int(parts[1])
+    if behind == 0:
+        return ShipVerdict(ok=True, behind=0, ahead=ahead, ref=ref, head=head)
+
+    return ShipVerdict(
+        ok=False, behind=behind, ahead=ahead, ref=ref, head=head,
+        reasons=[
+            f"HEAD ({head}) is {behind} commit(s) BEHIND {ref}",
+            "a build from here succeeds and ships code that was already fixed —"
+            " there is no other signal, because the artifact is correct, just old",
+        ],
+        fix=[
+            f"fix: git fetch origin && git merge {ref}   (or rebuild from {ref})",
+            "override only with a stated reason: --allow-stale '<why>'",
+        ],
+    )
+
+
+def stale_ref_age_days(cwd: Optional[Path] = None,
+                       ref: str = DEFAULT_DEPLOY_REF) -> Optional[float]:
+    """Age in days of the LOCAL copy of `ref`, or None if it cannot be read.
+
+    `behind_deploy_ref` compares against whatever was last fetched. A ref fetched
+    a week ago can report "0 behind" and be badly wrong, so the age is the second
+    half of the answer and callers should surface it.
+    """
+    repo = repo_root(cwd)
+    if repo is None:
+        return None
+    out = _git(repo, "log", "-1", "--format=%ct", ref).strip()
+    if not out.isdigit():
+        return None
+    import time
+
+    return max(0.0, (time.time() - int(out)) / 86400.0)
+
+
 def require(actor: str, cwd: Optional[Path] = None) -> Optional[int]:
     """``None`` when a rewrite may proceed, else an exit code after reporting.