@ssheleg/agent-sync 1.3.3 → 1.3.5

package/CHANGELOG.md

@@ -3,6 +3,39 @@
 All notable changes to this project are documented here.
 This project adheres to [Semantic Versioning](https://semver.org/).
 
+## 1.3.5 — 2026-07-29
+
+### The two rules this plugin enforces are now stated, with the failures that taught them
+
+Both are already code. Neither was written down, and a mechanism nobody can explain is a mechanism
+the next person removes.
+
+- **Identity comes before coordination.** Both ways of getting it wrong have happened here: one
+  session with two identities (acquired as one, denied by its own guard as the other) and two
+  sessions with one identity, which is worse because it is silent — `whoami` reported a lease that
+  belonged to somebody else and `release` would have taken it.
+- **Work in a submodule is not finished until its parent points at it.** Neither repository looks
+  wrong alone; the disagreement lives between them, which is why it survives every check that runs
+  inside one. That is what `finish` is for.
+- **The rule under both:** before trusting a tool's report about the world, make it report something
+  you can already verify.
+
+## 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

package/README.md

@@ -137,6 +137,20 @@ claude plugin marketplace add appvillis-com/agent-sync && claude plugin install
 
 ## Update
 
+**Update the whole family — one package, every agent.** A bundle with one member current and the
+rest stale is a combination nobody tested:
+
+```bash
+npx sshlg-skills update               # installed but behind — updates everything
+npx sshlg-skills install              # nothing installed yet
+npx --yes sshlg-skills@latest list    # what the current release of each member is
+```
+
+Restart your agent afterwards: skills and hooks load at session start, so the session that updates
+is not the session that gets the new ones.
+
+<details><summary>Updating this one member only</summary>
+
 **agent-sync itself** — update every channel you installed, then restart Claude Code:
 
 ```bash
@@ -167,6 +181,8 @@ npx sshlg-skills install
 Nothing else to update: the coordinator is stdlib-only python, and the npm package has
 zero runtime dependencies.
 
+</details>
+
 ## Set up a project
 
 **Initialisation is the first command, and it asks a question rather than guessing.**
@@ -387,6 +403,7 @@ agent loads on their own trigger rather than by default:
 | [`pipeline-binding.md`](plugins/agent-sync/skills/agent-sync/references/pipeline-binding.md) | wiring `pipeline.json`, or adding a stage hook |
 | [`hooks.md`](plugins/agent-sync/skills/agent-sync/references/hooks.md) | installing, debugging or removing the Claude Code hooks |
 | [`two-sources.md`](plugins/agent-sync/skills/agent-sync/references/two-sources.md) | before the first reconcile, or when deciding where a document belongs |
+| [`earned-rules.md`](plugins/agent-sync/skills/agent-sync/references/earned-rules.md) | why identity is resolved the way it is, and why `finish` exists — the two failures that produced both |
 | [`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). Everyone

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ssheleg/agent-sync",
-  "version": "1.3.3",
-  "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.",
+  "version": "1.3.5",
+  "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.3",
-  "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.5",
+  "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.3"
+  version: "1.3.5"
   author: appvillis-com
 ---
 
@@ -371,12 +371,20 @@ The mirror is a **rendering** of git, stamped with the source commit. It has no
 authority. When its stamp and `HEAD` disagree, the board gate fails — that is
 drift, not a formatting problem.
 
+## Two rules, and the failures that taught them
+
+Identity comes before coordination: a lease is only a lease if two agents get two identities. A
+submodule commit is unfinished until its parent points at it. Both:
+[`references/earned-rules.md`](references/earned-rules.md).
+
 ## Non-negotiables
 
 - Append, read back, then act. Never rewrite a coordination document.
 - `release` what you `acquire`, on every path including failure.
 - Credentials never reach `argv`, a log line, or the repository.
 - Degrade out loud. `ungated` is an acceptable state; a false claim of enforcement is not.
+- Two agents in one checkout are two identities, or the lease is decoration.
+- A submodule commit is unfinished until the parent points at it — `finish` before you call it done.
 - Everything the cloud holds about a durable fact is a link to git, never a substitute.
 
 ## References

package/plugins/agent-sync/skills/agent-sync/references/earned-rules.md

@@ -0,0 +1,27 @@
+# Two rules this plugin exists to enforce, and the failures that taught them
+
+Both were found by running this plugin on a four-repository project with several agents working at
+once. Each is now code, not advice — and each is stated here because a mechanism nobody can explain
+is a mechanism the next person removes.
+
+**Identity comes before coordination.** A lease is only a lease if two agents get two identities.
+Both ends of getting this wrong have happened: deriving the id from `CLAUDE_SESSION_ID` alone gave
+**one session two identities** — it acquired as one and was denied by its own guard as the other —
+and keeping one id per checkout gave **two sessions one identity**, which is worse because it is
+silent. Both acquired as one run, both were guarded as one run, `whoami` reported a lease that
+belonged to somebody else, and `release` would have taken it. The resolution order is
+`AGENT_SYNC_RUN_ID` · `CLAUDE_SESSION_ID` · the session that started this shell · shared, and where
+none can be established the run says so instead of presenting a shared entry as separation.
+
+**Work in a submodule is not finished until its parent says so.** A parent records each submodule as
+a pointer to one commit, and moving the submodule does not move the pointer. The work is committed,
+pushed, green in CI and marked done in its own roadmap — and a clone of the parent gets the commit
+**before** it. Neither repository looks wrong on its own; the disagreement exists only between them,
+which is why it survives every check that runs inside one. `finish` is that check, and it is the
+reason this plugin's pipeline binding no longer describes gate expressions it never ran.
+
+**The rule under both:** before trusting a tool's report about the world, make it report something
+you can already verify. A test suite reporting green having skipped every assertion, a gate printing
+`FAIL` and exiting `0`, containers reporting healthy while the tools talked to the host's services,
+and a lease held by the wrong identity are the same failure — a tool describing a world it is not
+looking at.

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.3"
+VERSION = "1.3.5"
 
 CONFIG_PATH = Path(".claude/agent-sync.json")
 ENV_FILE = Path(".env.agent-sync")
@@ -960,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":
@@ -978,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"
@@ -2008,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