@ssheleg/agent-sync 1.15.0 → 1.16.0

package/CHANGELOG.md

@@ -1,3 +1,53 @@
+## Unreleased — both `AS-01` halves exercised outside their fixtures
+
+The two rows sat at priority `unverified`: shipped, and confirmed by nothing but their own
+fixtures. Both are now exercised against real state, and both hold. **Nothing in the tool
+changed** — this records that the mechanism was watched working on something other than its
+own test data, which is what `unverified` meant.
+
+**The git plane, on a real remote.** A git-mode checkout was built against a local bare
+remote, a lease taken at `ttl 2`, and its local note **deleted** — exactly the state a ref
+won on another machine leaves behind, and the state the row said `residue` could not see.
+`residue` printed *nothing in the lock directory* and then enumerated the git plane:
+`refs/agent-sync/leases/DEMO-KEY @ 495370743e`, run `r-rverifya`, **expired 18s ago**,
+`foreign`, closing with *1 ref(s) on the remote, 0 this run can prove it owns and has spent*.
+
+**Reap, in both directions.** Reaping as a **different** run left the ref standing and said so
+by name. Reaping as the run that took it removed it and reported *confirmed gone by re-reading
+the remote* — the proof coming from `ls-remote`, not from a push's exit code.
+
+**And on live residue.** `~/DATA/0xDEV` carries a genuine foreign expired lock —
+`BLOG-SITEMAP`, run `r-blog-1429e`, **expired 4d 22h ago**. `reap` named it, said *left alone
+— it belongs to run r-blog-1429e, not to this one*, and **deleted nothing**: both lock files
+byte-identical afterwards. State a run cannot prove is its own is reported and untouched.
+
+## v1.16.0 — the release that closes one version string over two trees
+
+**281 lines of shipped behaviour had been sitting behind the tag.** `AS-01a` (the
+git plane is swept, not only disclosed) and `AS-01b` (an ambiguous lock is
+clearable by a person, per key, attributably) landed on `main`, were pinned by the
+umbrella, and were never tagged. So three channels served `1.15.0` and two
+different trees:
+
+| channel | source | `agent_sync.py` |
+|---|---|---|
+| npm `@ssheleg/agent-sync@1.15.0` | the tag | 4344 lines |
+| the plugin marketplace | the branch tip | 4575 lines |
+| the skills CLI | the branch tip | 4575 lines |
+
+All three reported `1.15.0`. `check_pins.py` was green throughout — correctly,
+because it compares the version STRING, and the string did match. A version that
+identifies two artefacts cannot be reasoned about, and the family's own invariant
+("the pin is the promise") was satisfied to the letter while being false in
+substance.
+
+Found on 2026-08-23 by fetching the npm tarball and counting lines in all three
+channels rather than trusting any of them. This release makes the number true.
+
+Also in this range: the release workflow refuses a tag whose commit no clone can
+reach, and the evidence ledger records both `AS-01` halves exercised on a real
+remote rather than in a fixture.
+
 ## v1.15.0 — a claim tag outlived its lease, and no command reached it
 
 **GitHub issue #5, filed 2026-08-17, reproduced verbatim at v1.14.0.** A board row shipped

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssheleg/agent-sync",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "description": "Let concurrent coding agents share one project without colliding — leases with TTL, race-free id reservation, a run journal and a generated board, over a pluggable knowledge cloud.",
   "bin": {
     "agent-sync": "bin/agent-sync.js"

package/plugins/agent-sync/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-sync",
   "displayName": "Agent Sync",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "description": "Coordination layer for multi-agent repositories — leases with TTL, race-free ID reservation, a run journal, a cross-repo signal feed and a generated board, over a pluggable knowledge cloud.",
   "author": {
     "name": "ssheleg",

package/plugins/agent-sync/skills/agent-sync/SKILL.md

@@ -4,7 +4,7 @@ description: "Use when several coding agents work one repository at the same tim
 compatibility: "Requires the task-pipeline skill for its stages (npx sshlg-skills install). Needs python3 3.9+ (stdlib only, HTTP included - nothing to pip install) and bash for the hooks. The knowledge backend is configured per project; with none configured it degrades to git-file leases. Enforcement hooks are Claude Code only - on other agents the same checks run as a self-check."
 license: MIT
 metadata:
-  version: "1.15.0"
+  version: "1.16.0"
   author: ssheleg
 ---
 

package/plugins/agent-sync/skills/agent-sync/references/lease-protocol.md

@@ -112,6 +112,21 @@ renewed in between.
 
 The tool reports which guarantee is in force; it never implies the stronger one.
 
+**Residue in this mode is on the remote, and the enumerating read goes there.** The local
+directory holds a *note* — `_note_local` writes one only for the run that won the key on
+this machine — so a ref won elsewhere leaves nothing to walk, and for a while `residue`
+could print `nothing on disk` over an expired lease sitting on the remote. That is the one
+shape a residue report must never take. `residue` and `reap` now sweep
+`refs/agent-sync/leases/*` on the configured remote and classify each ref with **the same
+classifier the local plane uses**, because whose lease this is must have one definition.
+`reap` deletes with the same `--force-with-lease=<ref>:<sha>` compare-and-swap `release`
+uses, and proves the ref went by re-reading `ls-remote` — a push's exit code is the wish,
+the second read is the state.
+
+**A remote that cannot be reached is `COULD NOT LOOK`, never an empty sweep.** The two read
+identically to an operator and mean opposite things, so they are printed differently and
+`reap` exits non-zero on the first.
+
 ## Expiry and stealing
 
 A lock is expired when `now > ts + ttl` for the timestamp inside it.
@@ -182,6 +197,28 @@ only thing that removes any of it. The split between the two kinds is the mechan
 In doubt the answer is `ambiguous`, never `reapable`. A classifier that resolves doubt by
 deleting is worse than none, because it deletes under a claim of authority.
 
+**And that has a consequence the classifier cannot fix: nobody could ever clear an
+`ambiguous` lock.** A shell with no session id answers to the shared identity, so a
+matching run id proves nothing, so the lock is `ambiguous`, so no run reaps it — for ever.
+28 of them had accumulated on this machine by 2026-08-20, the oldest overdue by 21 days
+against a 2700-second TTL, every one of them correctly refused.
+
+`reap --i-own-this <key>` is the way out, and it is a **person's** decision rather than a
+run's proof. M-50 forbids a RUN from deleting what it cannot establish; it does not forbid
+an operator from deciding. Three things keep it a decision instead of a sweep:
+
+* **named keys, and it refuses to run without them** — a blanket override is the sweep the
+  classifier exists to refuse, wearing a flag. Use `--` before a key that starts with a
+  dash: the tool slugifies guarded-file paths into keys like
+  `-claude-plugin-marketplace-json`, and a key the tool writes must be a key the tool can
+  address;
+* **it refuses a LIVE lease** — residue is what it clears, and a live lease belongs to a run
+  that may still be working;
+* **it prints the payload it destroyed** — run, timestamp, machine, how long expired — and
+  journals the decision where a record plane is configured. The classifier's verdict is
+  printed unchanged beside it, because the override does not make the lock provably yours;
+  it makes the deletion attributable.
+
 **Teardown is verified by re-reading the state, never by the delete's return value.**
 `unlink` returns nothing and raises nothing on a filesystem where the entry survives the
 call — a read-only mount, an NFS write that never lands, another process recreating the

package/plugins/agent-sync/skills/agent-sync/scripts/agent_sync.py

@@ -33,7 +33,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
-VERSION = "1.15.0"
+VERSION = "1.16.0"
 
 CONFIG_PATH = Path(".claude/agent-sync.json")
 ENV_FILE = Path(".env.agent-sync")
@@ -1544,6 +1544,102 @@ class Sync:
         """
         return bool(self.identity[0])
 
+    # -- the git plane's own enumerating read (AS-01a) -------------------------
+
+    def _git_lease_refs(self) -> tuple[list[tuple[str, str]], str | None]:
+        """Every lease ref on the remote as (sha, key), or the reason it could not look.
+
+        The authority in git mode is `refs/agent-sync/leases/*` on the remote, and a ref
+        won on another machine leaves NO local note — `_note_local` only fires for the run
+        that won it here. So the local directory walk cannot see it, and for a while
+        `residue` could print `nothing on disk` over an expired lease sitting on the
+        remote. That is the one shape a residue report must never take.
+
+        The failure is returned rather than raised, because the caller has to be able to
+        say `could not look` instead of `nothing there`.
+        """
+        remote = self._git_remote()
+        r = subprocess.run(["git", "ls-remote", remote, "refs/agent-sync/leases/*"],
+                           capture_output=True, text=True)
+        if r.returncode != 0:
+            why = (r.stderr or r.stdout or "").strip().splitlines()
+            return [], (why[-1] if why else f"`git ls-remote {remote}` failed")
+        out = []
+        for line in r.stdout.strip().splitlines():
+            parts = line.split()
+            if len(parts) != 2 or not parts[1].startswith("refs/agent-sync/leases/"):
+                continue
+            out.append((parts[0], parts[1].rsplit("/", 1)[-1]))
+        return out, None
+
+    def _git_lease_payload(self, sha: str) -> str:
+        """The lease object's body — the same JSON the local note carries.
+
+        One shape for both planes, so `classify_lock` is the only classifier in this file.
+        A second one would be a second definition of *whose lease this is*, which is the
+        question the whole tool exists to answer once.
+        """
+        body = git("log", "-1", "--format=%B", sha)
+        if body:
+            return body.strip()
+        # The object may not be local yet: the ref lives on the remote.
+        subprocess.run(["git", "fetch", "-q", self._git_remote(), sha],
+                       capture_output=True, text=True)
+        return (git("log", "-1", "--format=%B", sha) or "").strip()
+
+    def git_residue(self) -> tuple[list[dict[str, Any]], str | None]:
+        """The git plane, classified by the same rules as the local one."""
+        refs, why = self._git_lease_refs()
+        if why is not None:
+            return [], why
+        now, host, repo = time.time(), platform.node(), repo_name()
+        out: list[dict[str, Any]] = []
+        for sha, key in sorted(refs, key=lambda x: x[1]):
+            raw = self._git_lease_payload(sha)
+            if raw:
+                entry = classify_lock(key, raw, rid=self.rid,
+                                      identity_is_strong=self.identity_is_strong,
+                                      repo=repo, host=host, default_ttl=self.ttl, at=now)
+            else:
+                entry = {"key": key, "state": AMBIGUOUS, "run": None, "repo": None,
+                         "host": None, "ts": "", "expired_for": None,
+                         "why": "the lease object carries no readable payload"}
+            entry["plane"] = "git"
+            entry["ref"] = self._ref(key)
+            entry["sha"] = sha
+            entry["path"] = None
+            out.append(entry)
+        return out, None
+
+    def git_reap(self, entries: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        """Delete a reapable lease ref, and prove it went by looking again.
+
+        Same compare-and-swap `_git_release` uses: `--force-with-lease=<ref>:<sha>` refuses
+        if somebody won the key between the read and the delete, which is the whole reason
+        the sha travels with the entry. And the verdict comes from a second `ls-remote`,
+        not from the push's exit code — a teardown that reports success out of its own
+        return value is reporting the wish rather than the state.
+        """
+        done: list[dict[str, Any]] = []
+        for e in entries:
+            r = subprocess.run(["git", "push", self._git_remote(),
+                                f"--force-with-lease={e['ref']}:{e['sha']}",
+                                f":{e['ref']}"], capture_output=True, text=True)
+            after, why = self._git_lease_refs()
+            still = {k for _s, k in after}
+            if why is not None:
+                e["gone"] = None
+                e["why_gone"] = f"could not re-read the remote to prove it went ({why})"
+            elif e["key"] in still:
+                e["gone"] = False
+                e["why_gone"] = ((r.stderr or "").strip().splitlines() or
+                                 ["the ref is still on the remote"])[-1]
+            else:
+                e["gone"] = True
+                e["why_gone"] = ""
+            done.append(e)
+        return done
+
     def residue(self) -> list[dict[str, Any]]:
         """Every lock file in this checkout, classified — the live ones included.
 
@@ -3185,24 +3281,48 @@ def cmd_residue(_args: argparse.Namespace) -> int:
         print("\n  claim tags: not configured here, so none are swept "
               "(`claimTags` in the config)")
 
-    # AS-01a. Said where the report prints, not only on a board: a check that cannot look
-    # must not read as one that looked.
+    # AS-01a. The sweep, and the disclosure is now about what it COULD NOT reach rather
+    # than about a plane nobody read. A check that cannot look must not read as one that
+    # looked — and a check that CAN look must not keep printing that it cannot.
     if s.lease_mode == "git":
-        print("\n  ⚠ INCOMPLETE IN THIS MODE. The read above walks "
-              f"{STATE_DIR}/leases only, and in\n"
-              "  git mode the authority is `refs/agent-sync/leases/*` on "
-              f"{s.cfg.get('leaseRemote') or 'origin'}.\n"
-              "  A ref won on ANOTHER machine leaves no local note here, so it is absent "
-              "from this\n  report — absent, not proven gone. Sweeping the refs is board row "
-              "AS-01a; until it\n  lands, enumerate them by hand:\n"
-              f"    git ls-remote {s.cfg.get('leaseRemote') or 'origin'} "
-              "'refs/agent-sync/leases/*'")
+        remote = s.cfg.get("leaseRemote") or "origin"
+        refs, why = s.git_residue()
+        print(f"\n  git plane · {remote} · refs/agent-sync/leases/*")
+        if why is not None:
+            print(f"    ⚠ COULD NOT LOOK — {why}")
+            print("    So this is not an empty sweep: the refs may be there and unread. "
+                  "Fix the remote, or")
+            print(f"    enumerate by hand: git ls-remote {remote} "
+                  "'refs/agent-sync/leases/*'")
+        elif not refs:
+            print("    no lease refs on the remote — swept and empty, not unread")
+        else:
+            local_keys = {e["key"] for e in entries}
+            reapable = [e for e in refs if e["state"] == REAPABLE]
+            for e in refs:
+                also = " · also noted locally" if e["key"] in local_keys else ""
+                print(f"    · {e['key']}  [{e['state']}]{also}")
+                print(f"      ref   : {e['ref']} @ {e['sha'][:10]}")
+                if e.get("run"):
+                    print(f"      run   : {e['run']}"
+                          + (f" · host {e['host']}" if e.get("host") else ""))
+                # `spent()` says this once for both planes: a second phrasing here is a
+                # second definition of what residue means.
+                print(f"      state : {spent(e)}")
+                if e.get("why"):
+                    print(f"      why   : {e['why']}")
+                if e["state"] == REAPABLE:
+                    print(f"      clear : agent_sync.py reap {e['key']}")
+            print(f"    {len(refs)} ref(s) on the remote, {len(reapable)} this run can prove "
+                  "it owns and has spent")
     return 0
 
 
 def cmd_reap(args: argparse.Namespace) -> int:
     """Clear this run's spent locks, and verify the teardown by reading the state again."""
     s = Sync()
+    if getattr(args, "own", False):
+        return _reap_by_operator_decision(s, args.keys)
     result = s.reap(args.keys or None)
     for e in result["reaped"]:
         print(f"  reaped {e['key']} — {e['why']}, confirmed gone by re-reading "
@@ -3217,9 +3337,116 @@ def cmd_reap(args: argparse.Namespace) -> int:
     if not args.keys:
         for e in result["left"]:
             print(f"  · {e['key']} [{e['state']}] left alone — {e['why']}")
-    if not result["reaped"] and not result["remaining"] and not result["refused"]:
+    # AS-01a. The git plane is a second place residue lives, and until this it was a
+    # second place nothing could clear: `reap` walked the lock directory only, so an
+    # expired ref this run had won stayed on the remote with no command able to reach it.
+    git_bad = 0
+    if s.lease_mode == "git":
+        refs, why = s.git_residue()
+        remote = s.cfg.get("leaseRemote") or "origin"
+        if why is not None:
+            print(f"  ⚠ the git plane could not be read ({why}) — its refs are "
+                  "neither reaped nor reported clean.", file=sys.stderr)
+            print(f"    Enumerate by hand: git ls-remote {remote} "
+                  "'refs/agent-sync/leases/*'", file=sys.stderr)
+            git_bad = 1
+        else:
+            named = set(args.keys or [])
+            want = [e for e in refs if e["state"] == REAPABLE and (not named or e["key"] in named)]
+            for e in s.git_reap(want):
+                if e["gone"]:
+                    print(f"  reaped {e['key']} on {remote} — {e['why']}, confirmed gone by "
+                          "re-reading the remote")
+                else:
+                    print(f"  ✗ {e['key']} is STILL on {remote} after the delete "
+                          f"({e['why_gone']}) — the compare-and-swap refused, which means "
+                          "somebody won it between the read and the delete",
+                          file=sys.stderr)
+                    git_bad = 1
+            for e in refs:
+                if e["state"] != REAPABLE and (not named or e["key"] in named):
+                    print(f"  · {e['key']} [{e['state']}] on {remote} left alone — {e['why']}")
+            if not refs:
+                print(f"  no lease refs on {remote} — swept and empty, not unread")
+    if not result["reaped"] and not result["remaining"] and not result["refused"] \
+            and s.lease_mode != "git":
         print("  nothing this run can prove it owns and has spent — nothing reaped")
-    return 1 if result["remaining"] or result["refused"] else 0
+    return 1 if (result["remaining"] or result["refused"] or git_bad) else 0
+
+
+def _reap_by_operator_decision(s: "Sync", keys: list[str]) -> int:
+    """`--i-own-this` — the one path that clears state no RUN can prove is its own.
+
+    AS-01b. The classifier is right to refuse: a run whose identity is the shared fallback
+    cannot prove a matching run id means anything, so every such lock is `ambiguous` and
+    nothing reaps it. The consequence is that expired locks accumulate with no path out for
+    anybody — 28 of them on this machine by 2026-08-20, the oldest overdue by 21 days
+    against a 2700-second TTL.
+
+    M-50 forbids a RUN from deleting what it cannot prove. A person deciding, per key, is
+    not a run guessing — so the decision is available, and three things make it a decision
+    rather than a sweep:
+
+    * **it takes named keys and refuses to run without them.** A blanket override is the
+      thing the classifier exists to prevent, wearing a flag;
+    * **it refuses a LIVE lease.** Residue is what this clears; a live lease belongs to a
+      run that may still be working, and taking it by hand is the collision the tool exists
+      to prevent;
+    * **it prints the payload it destroyed** — run, timestamp, machine — so the decision is
+      auditable afterwards by somebody who was not there, and journals it where a record
+      plane is configured.
+    """
+    if not keys:
+        print("reap --i-own-this needs the keys, one or more, by name.\n"
+              "  A blanket override is the sweep the classifier exists to refuse, wearing a "
+              "flag.\n"
+              "  `agent_sync.py residue` lists what is there and why each one is unclearable.",
+              file=sys.stderr)
+        return 2
+
+    by_key = {}
+    for e in s.residue():
+        by_key.setdefault(e["key"], e)
+        by_key.setdefault(s._local_lock(e["key"]).stem, e)
+
+    rc = 0
+    for k in keys:
+        e = by_key.get(k) or by_key.get(s._local_lock(k).stem)
+        if e is None:
+            print(f"  · {k} — there is no lock by that name in this checkout", file=sys.stderr)
+            rc = 1
+            continue
+        if e["state"] == LIVE:
+            print(f"  ✗ {e['key']} is LIVE under {e.get('run') or 'a run'}"
+                  f"{' on ' + e['host'] if e.get('host') else ''} — not cleared. An override "
+                  "is for residue;\n    a live lease belongs to a run that may still be "
+                  "working. Ask the holder, or wait for the TTL.", file=sys.stderr)
+            rc = 1
+            continue
+        had = (f"run {e.get('run') or 'unknown'}"
+               f"{' · host ' + e['host'] if e.get('host') else ''}"
+               f"{' · ' + e['ts'] if e.get('ts') else ''}"
+               f" · {spent(e)}")
+        try:
+            e["path"].unlink()
+        except OSError as exc:
+            print(f"  ✗ {e['key']} could not be removed ({exc})", file=sys.stderr)
+            rc = 1
+            continue
+        # Proved gone by looking again, the same rule the ordinary reap follows.
+        if any(x["key"] == e["key"] for x in s.residue()):
+            print(f"  ✗ {e['key']} is STILL PRESENT after the delete — the teardown was not "
+                  "verified, whatever the call returned", file=sys.stderr)
+            rc = 1
+            continue
+        print(f"  cleared {e['key']} by operator decision — it held {had}")
+        print(f"    the classifier called it `{e['state']}`, and that has not changed: this "
+              "was a person's\n    call, not a proof of ownership.")
+        try:
+            s.journal(f"reap --i-own-this {e['key']} — was {had}, classified {e['state']}")
+        except Exception:                                # noqa: BLE001 - the record plane is optional
+            pass
+    return rc
 
 
 def cmd_journal(args: argparse.Namespace) -> int:
@@ -4320,6 +4547,10 @@ def build_parser() -> argparse.ArgumentParser:
     rp = sub.add_parser("reap", help="clear expired locks this run provably owns; foreign "
                                      "and ambiguous ones are reported, never touched")
     rp.add_argument("keys", nargs="*", help="which to clear (default: every reapable one)")
+    rp.add_argument("--i-own-this", action="store_true", dest="own",
+                    help="clear the NAMED expired locks even though this run cannot prove "
+                         "they are its own — an operator's decision, per key, recorded. "
+                         "Refuses a live lease and refuses to run with no key.")
     rp.set_defaults(fn=cmd_reap)
 
     g = sub.add_parser("guard", help="may this run write that path? exit 2 = no")