@ssheleg/agent-sync 1.3.1 → 1.3.4

package/CHANGELOG.md

@@ -3,6 +3,52 @@
 All notable changes to this project are documented here.
 This project adheres to [Semantic Versioning](https://semver.org/).
 
+## 1.3.4 — 2026-07-29
+
+### Fixed
+- **`release` reported success for a lease it did not release, and cleared the
+  board claim on the way.** The lease plane refused correctly — a lease held by
+  another run stayed held, and `_git_release` printed a note saying so — but the
+  command printed `released <key>` over the top of it and exited 0, and
+  `write_claim` had already blanked the claim cell before the refusal was
+  reached. The result was the board advertising a task as free while the lease
+  still held it: the exact disagreement a lease exists to prevent, manufactured
+  by the tool. Ownership is now checked **first**, in whichever plane arbitrates
+  it; nothing is written when the answer is no; the command exits non-zero and
+  says who holds it. Both lease modes were affected.
+- A regression check covers it in `local` and `git` mode, and was probed against
+  the old code in both before being trusted.
+
+## 1.3.3 — 2026-07-29
+
+### Fixed
+- **The git lease backend could not take a lease on any machine without a git
+  identity.** Acquiring writes a lease object with `git commit-tree`, which
+  refuses when `user.email` is unset and cannot be auto-detected — CI runners,
+  containers, a freshly provisioned box. So the backend that advertises
+  *exclusive across machines* failed on precisely the machines least likely to
+  have a personal git config, with `could not create the lease object` and no
+  further detail. The lease object is plumbing, not authorship: it now carries a
+  fixed `agent-sync <agent-sync@localhost>` identity passed inline, so it never
+  depends on ambient config.
+- The same failure now reports git's own last line instead of swallowing it. The
+  bug survived six red CI runs because the message named a possible cause and
+  showed no evidence.
+
+## 1.3.2 — 2026-07-29
+
+Open-source hygiene — the repo is public and ships in the `sshlg-skills` bundle,
+so the files a first-time contributor looks for now exist.
+
+### Added
+- `CODE_OF_CONDUCT.md`, issue forms and a pull-request template. The forms ask
+  the question that actually matters for this project: **how many agents were
+  running, against what checkout** — a coordination bug reported without the
+  concurrency shape is not reproducible.
+- The PR checklist requires a negative self-test with any new validator guard —
+  plant the defect, watch the check fail, then trust the green.
+- README points at the code of conduct and at the family bundle.
+
 ## 1.3.1 — 2026-07-29
 
 ### The git lease was invisible to everything that reads a lease — fixed
@@ -24,6 +70,22 @@ already removed that note, which is why only one half of the loop was ever writt
 now runs acquire → `whoami` → `guard` → release against **both** modes; against 1.3.0 it fails with
 the two symptoms above, which is the point of adding it.
 
+## 1.3.1 — 2026-07-29
+
+### Ignoring the state directory does nothing once git is tracking it
+
+Found in the project this plugin was built for: `.agent-sync/` was gitignored **and committed**,
+because the files went in before the rule existed. Consequences, all of them silent:
+
+- every tool call rewrites `last-renew`, so all three repositories were permanently dirty and no
+  run could ever report itself finished
+- `run-id` is the checkout's **agent identity**. Committed, it reaches every clone — two machines
+  would then coordinate as one run, which is the failure 1.3.0 fixed at the other end
+
+`init` now untracks the directory when it finds it tracked, and `check` reports it as a problem
+rather than passing a project whose state is versioned. Probed: a repository with a committed
+`.agent-sync/run-id` fails `check` with the exact removal command, and passes once it is untracked.
+
 ## 1.3.0 — 2026-07-29
 
 ### Two agents in one checkout were one identity — fixed

package/README.md

@@ -389,8 +389,13 @@ agent loads on their own trigger rather than by default:
 | [`two-sources.md`](plugins/agent-sync/skills/agent-sync/references/two-sources.md) | before the first reconcile, or when deciding where a document belongs |
 | [`roadmap.md`](plugins/agent-sync/skills/agent-sync/references/roadmap.md) | configuring `claimTags`, taking or closing a task, or re-planning a board |
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) and [CHANGELOG.md](CHANGELOG.md). Security
-reports: [SECURITY.md](SECURITY.md).
+See [CONTRIBUTING.md](CONTRIBUTING.md) and [CHANGELOG.md](CHANGELOG.md). Everyone
+taking part is expected to follow the [Code of Conduct](CODE_OF_CONDUCT.md).
+Security reports: [SECURITY.md](SECURITY.md).
+
+`agent-sync` also ships in the [sshlg-skills](https://github.com/ssheleg/sshlg-skills)
+bundle, which installs the whole family for Claude Code, Cursor, Codex and 70+
+other agents with one command.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssheleg/agent-sync",
-  "version": "1.3.1",
+  "version": "1.3.4",
   "description": "Let concurrent coding agents share one project without colliding \u2014 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",
-  "version": "1.3.1",
-  "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.",
+  "version": "1.3.4",
+  "description": "Coordination layer for multi-agent repositories \u2014 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": "appvillis-com"
   },

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.3.1"
+  version: "1.3.4"
   author: appvillis-com
 ---
 

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

@@ -32,7 +32,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
-VERSION = "1.3.1"
+VERSION = "1.3.4"
 
 CONFIG_PATH = Path(".claude/agent-sync.json")
 ENV_FILE = Path(".env.agent-sync")
@@ -813,10 +813,20 @@ class Sync:
         payload = json.dumps({"run": self.rid, "ts": now_iso(), "ttl": self.ttl,
                               "repo": repo_name(), "host": os.uname().nodename})
         empty_tree = git("hash-object", "-t", "tree", "/dev/null")
-        commit = subprocess.run(["git", "commit-tree", empty_tree], input=payload,
-                                capture_output=True, text=True).stdout.strip()
+        # A lease object is plumbing, not authorship, so it must not depend on the
+        # machine having a git identity. Without these `-c` flags `commit-tree`
+        # refuses wherever user.email is unset and cannot be auto-detected — CI
+        # runners, containers, a freshly provisioned box — and the lease backend
+        # silently becomes unusable on exactly the machines that need it most.
+        made = subprocess.run(
+            ["git", "-c", "user.name=agent-sync", "-c", "user.email=agent-sync@localhost",
+             "commit-tree", empty_tree],
+            input=payload, capture_output=True, text=True)
+        commit = made.stdout.strip()
         if not commit:
-            raise Fail("could not create the lease object — is this a git repository?")
+            detail = (made.stderr or "").strip().splitlines()
+            why = detail[-1] if detail else "no output from git commit-tree"
+            raise Fail(f"could not create the lease object — is this a git repository? ({why})")
 
         args = ["git", "push", remote, f"{commit}:{ref}"]
         if held_sha:                       # stealing an expired lease, and only that
@@ -950,7 +960,36 @@ class Sync:
         marker.parent.mkdir(parents=True, exist_ok=True)
         marker.write_text(now_iso())
 
-    def release(self, key: str) -> None:
+    def _lease_holder(self, key: str) -> str | None:
+        """Who holds this lease right now, in whichever plane arbitrates it."""
+        if self.lease_mode == "git":
+            sha, held = self._git_read_lease(key)
+            return held.get("run") if sha else None
+        lock = self._local_lock(key)
+        if not lock.exists():
+            return None
+        try:
+            return json.loads(lock.read_text()).get("run")
+        except (json.JSONDecodeError, OSError):
+            return None
+
+    def release(self, key: str) -> bool:
+        """Release only what this run holds, and say so plainly when it does not.
+
+        This used to clear the board claim and report success unconditionally. The lease
+        plane refused correctly — `_git_release` prints a note and returns — but the
+        caller printed "released" over the top of it and exited 0, and `write_claim` had
+        already blanked the claim cell on the way in. The board then said the task was
+        free while the lease said it was taken: the exact disagreement a lease exists to
+        prevent, manufactured by the tool. Ownership is therefore checked FIRST, and
+        nothing is written when the answer is no.
+        """
+        holder = self._lease_holder(key)
+        if holder is not None and holder != self.rid:
+            print(f"note: {key} is held by {holder}, not this run — nothing released",
+                  file=sys.stderr)
+            return False
+
         for n in self.write_claim(key, None):
             print(f"  {n}")
         if self.lease_mode == "git":
@@ -968,6 +1007,7 @@ class Sync:
                                         fmt_line("release", key, self.rid))
             except Fail as exc:
                 print(f"note: released locally, not published ({exc})", file=sys.stderr)
+        return True
 
     def held(self) -> list[str]:
         d = self.root / STATE_DIR / "leases"
@@ -1778,6 +1818,7 @@ def cmd_init(args: argparse.Namespace) -> int:
 
     ensure_gitignored(root, str(ENV_FILE))
     ensure_gitignored(root, f"{STATE_DIR}/")
+    ensure_untracked(root, f"{STATE_DIR}/")
 
     print()
     if backend == "outline":
@@ -1833,6 +1874,25 @@ def ensure_gitignored(root: Path, entry: str) -> None:
     print(f"✓ added {entry} to .gitignore")
 
 
+def ensure_untracked(root: Path, entry: str) -> None:
+    """Ignoring a path does nothing once git is already tracking it.
+
+    Found in a real project: the state directory had been committed before the ignore rule
+    existed, so `git status` reported it modified after **every** tool call — the repository was
+    permanently dirty and no run could report itself finished. `run-id` is the worse half: it is
+    this checkout's agent identity, and committed it reaches every clone, so two machines
+    coordinate as one run.
+    """
+    tracked = git("ls-files", "--", entry.rstrip("/"), cwd=root)
+    if not tracked:
+        return
+    if git("rm", "-r", "--cached", "-q", "--", entry.rstrip("/"), cwd=root) is None:
+        return
+    n = len(tracked.split("\n"))
+    print(f"✓ untracked {n} committed file(s) under {entry} — commit that removal; "
+          "ignoring a tracked path has no effect")
+
+
 # --------------------------------------------------------------------------- status
 
 def cmd_status(_args: argparse.Namespace) -> int:
@@ -1978,7 +2038,11 @@ def cmd_renew(args: argparse.Namespace) -> int:
 
 
 def cmd_release(args: argparse.Namespace) -> int:
-    Sync().release(args.key)
+    # Exit non-zero when nothing was released. A caller that scripts `release` in a
+    # cleanup path has no other way to learn the lease is still out there.
+    if not Sync().release(args.key):
+        print(f"NOT released: {args.key} is held by another run", file=sys.stderr)
+        return 1
     print(f"released {args.key}")
     return 0
 
@@ -2714,6 +2778,16 @@ def cmd_check(_args: argparse.Namespace) -> int:
         except Fail:
             pass
 
+    tracked_state = git("ls-files", "--", STATE_DIR)
+    if tracked_state:
+        problems.append(
+            f"{STATE_DIR}/ is tracked by git ({len(tracked_state.split(chr(10)))} file(s)) — it is "
+            "generated state, the repository is dirty after every tool call, and a committed "
+            "run-id hands this checkout's identity to every clone. "
+            f"Run: git rm -r --cached {STATE_DIR} && commit")
+    else:
+        ok.append(f"{STATE_DIR}/ is not tracked")
+
     for line in ok:
         print(f"  ✓ {line}")
     for line in warn: