@ssheleg/agent-sync 1.12.0 → 1.13.0

package/CHANGELOG.md

@@ -1,3 +1,44 @@
+## v1.13.0 — the file carried two notions of *held* and they disagreed where it mattered
+
+**A lease from a run that died could not be cleared by any command.** Measured in the field:
+three locks past their TTL, one of them by **604x**, and the only way out was deleting the file
+by hand — which is the single thing a coordination tool exists to stop anybody doing. The
+refusal itself was correct; there was simply no path.
+
+The cause is one function. `acquire` has always known a TTL runs out — `_steal_expired` exists
+for exactly that. `_lease_holder`, which `release` consults, read **any** lock file as held and
+never looked at the timestamp. So an expired lease was *gone* for `acquire` and *eternal* for
+`release`, and the file never noticed it was answering one question two ways.
+
+`_lease_alive()` is now the one definition, used by both. `release` reaps an expired foreign
+lease and **says whose it was**, because the operator asked to release their own lease and is
+getting somebody else's corpse cleared alongside it.
+
+**What did not change is the half that matters.** A lease inside its TTL is still refused, and
+that is fixtured beside the reap so the two cannot drift. An unparseable timestamp is treated
+as expired rather than as a licence to hold forever — a corrupt lock was the other way to reach
+the same unclearable state.
+
+Fixtures 6 → **9**, each driving the shipped script as a process against a real project.
+Closes #4.
+
+### Also closed by measurement: #1
+
+`claimTags` whole-row id matching made the claim unwritable on boards with a `Depends` column —
+filed against **1.3.5**, and fixed by **B-42** on 2026-08-14 without anyone connecting the two.
+Re-run against this version on the exact board shape the issue names (`| id | what | acceptance
+| depends | decisions | status |`, with `T-02` and `T-03` both citing `T-01`):
+
+```
+$ agent_sync.py acquire T-01
+docs/ROADMAP.md: `T-01` claim written through
+| T-01 | … | open (claimed: r-cca8b75db) |
+| T-02 | … | open |          ← untouched
+| T-03 | … | open |          ← untouched
+```
+
+Closes #1.
+
 ## v1.12.0 — 246 kB of someone else's bytecode, in every install
 
 **The published tarball carried a `.pyc` both ignore files were written to exclude.**
@@ -422,6 +463,11 @@ plants and catches 27 distinct defects.
 
 ## v1.6.0
 
+> **Never released on its own.** There is no `v1.6.0` tag and no `1.6.0` on npm,
+> so `npm install @ssheleg/agent-sync@1.6.0` and `git checkout v1.6.0` both fail. This section
+> describes work that shipped inside a later version. The note is here because
+> the section reads as a release (2026-08-17, umbrella `B-71`).
+
 **Four guarantees that were described but not delivered, and the one number now stated once.**
 1.5.3 stopped the tool reporting things that were untrue; this release makes the properties it
 claims actually hold, each with a check that has been watched fail against the defect it exists to
@@ -495,6 +541,11 @@ planting each defect back.
 
 ## v1.5.3
 
+> **Never released on its own.** There is no `v1.5.3` tag and no `1.5.3` on npm,
+> so `npm install @ssheleg/agent-sync@1.5.3` and `git checkout v1.5.3` both fail. This section
+> describes work that shipped inside a later version. The note is here because
+> the section reads as a release (2026-08-17, umbrella `B-71`).
+
 **Five surfaces told the caller something that was not true.** An audit on 2026-08-10 ran the
 commands instead of reading them, and every finding below was reproduced before it was fixed. The
 validator was green throughout — which is the finding behind the findings, and the reason this

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssheleg/agent-sync",
-  "version": "1.12.0",
+  "version": "1.13.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.12.0",
+  "version": "1.13.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.12.0"
+  version: "1.13.0"
   author: ssheleg
 ---
 

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.12.0"
+VERSION = "1.13.0"
 
 CONFIG_PATH = Path(".claude/agent-sync.json")
 ENV_FILE = Path(".env.agent-sync")
@@ -1271,18 +1271,44 @@ class Sync:
         marker.parent.mkdir(parents=True, exist_ok=True)
         marker.write_text(now_iso())
 
+    @staticmethod
+    def _lease_alive(held: dict, default_ttl: int) -> bool:
+        """Is this lease still within its TTL? The ONE definition of held.
+
+        `acquire` has always answered this question — `_steal_expired` exists
+        precisely to take a lease whose TTL has run out. `release` did not ask it,
+        and read any lock file as held. So the file carried two notions of *held*
+        and they disagreed exactly where it mattered: a lease from a run that died
+        was expired for `acquire` and eternal for `release`, and no command could
+        clear it. Measured in the field at **604x** its 2700-second TTL, released
+        only by deleting the file by hand — which is the one thing a coordination
+        tool exists to stop anybody doing.
+        """
+        try:
+            return time.time() <= parse_iso(held.get("ts", "")) + int(held.get("ttl", default_ttl))
+        except (ValueError, TypeError):
+            # An unparseable timestamp is not a licence to hold forever.
+            return False
+
     def _lease_holder(self, key: str) -> str | None:
-        """Who holds this lease right now, in whichever plane arbitrates it."""
+        """Who holds this lease right now, in whichever plane arbitrates it.
+
+        `None` for an expired lease as well as an absent one: the TTL is the
+        contract, and a lease past it is not held by anybody.
+        """
         if self.lease_mode == "git":
             sha, held = self._git_read_lease(key)
-            return held.get("run") if sha else None
+            if not sha or not self._lease_alive(held, self.ttl):
+                return None
+            return held.get("run")
         lock = self._local_lock(key)
         if not lock.exists():
             return None
         try:
-            return json.loads(lock.read_text()).get("run")
+            held = json.loads(lock.read_text())
         except (json.JSONDecodeError, OSError):
             return None
+        return held.get("run") if self._lease_alive(held, self.ttl) else None
 
     def release(self, key: str) -> bool:
         """Release only what this run holds, and say so plainly when it does not.
@@ -1308,10 +1334,20 @@ class Sync:
         lock = self._local_lock(key)
         if lock.exists():
             try:
-                if json.loads(lock.read_text()).get("run") in (self.rid, None):
-                    lock.unlink(missing_ok=True)
+                held = json.loads(lock.read_text())
             except (json.JSONDecodeError, OSError):
                 lock.unlink(missing_ok=True)
+            else:
+                owner = held.get("run")
+                if owner in (self.rid, None):
+                    lock.unlink(missing_ok=True)
+                elif not self._lease_alive(held, self.ttl):
+                    # Reaped, not stolen — and said out loud, because the operator
+                    # asked to release THEIR lease and is getting somebody else's
+                    # corpse cleared as well.
+                    print(f"  reaped {key}: expired lease from {owner}, "
+                          f"whose run left it past its TTL")
+                    lock.unlink(missing_ok=True)
         if self.adapter.is_lease_authority:
             try:
                 self.adapter.log_append(self.log_id("claims"),