@ssheleg/agent-sync 1.11.1 → 1.13.0

package/CHANGELOG.md

@@ -1,3 +1,88 @@
+## 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.**
+`@ssheleg/agent-sync@1.11.1` ships
+`plugins/agent-sync/skills/agent-sync/scripts/__pycache__/agent_sync.cpython-312.pyc` —
+**245.8 kB against 175.7 kB of source beside it**, 40% of the tarball, compiled by
+whatever interpreter the publisher happened to be running. Verified by unpacking the
+published artefact, not by reading the manifest.
+
+`.gitignore:3-4` and `.npmignore:1-2` both exclude `__pycache__/` and `*.pyc`. **Neither
+is consulted once `files` names a directory** — the whitelist wins, so the intent was
+recorded twice and enforced nowhere. `files` now carries `!plugins/**/__pycache__` and
+`!plugins/**/*.pyc`, and the packed result drops from **231.5 kB / 28 files to
+125.8 kB / 27**.
+
+**A filesystem walk would not have caught this**, which is why the new check asks npm.
+`check_the_tarball_carries_no_bytecode()` reads `npm pack --dry-run --json` — the
+packer's own answer to *what would ship* — and fails on any `.pyc` or `__pycache__` in
+it. Where npm is absent it discloses rather than passing: a check that cannot look must
+never read as one that looked. Watched failing against the exact state that shipped, and
+added to `--self-test`, now **38 fixtures**.
+
+### Fixed — three documents that told the reader something untrue
+
+- **`references/hooks.md` said the hooks are removed by editing `.claude/settings.json`.**
+  Nothing here ever writes a `hooks` block there, and Claude Code has no per-hook disable
+  for a hook a plugin ships. A user who wanted them gone edited a file with no such block
+  and concluded it had worked, while the SessionStart hook kept speaking in every session.
+  The two real levers are named now — `enabledPlugins[…] = false` or `plugin uninstall` —
+  plus the fact that every hook already self-disables in a project with no
+  `.claude/agent-sync.json`.
+- **`CONTRIBUTING.md` said five version surfaces move together; the validator enforces
+  six.** The missing one is `VERSION` in `scripts/agent_sync.py`, and it is exactly what
+  forced the 1.11.1 patch: a bump driver written from that page moved four of six and CI
+  refused the tag. It is the constant `status` prints into every session, so its drift is
+  invisible in the manifests and loud in the banner.
+- **`CONTRIBUTING.md` said the self-test injects five defects; it injected thirty-seven.**
+  The count is read off the run's own last line now. The number is the whole claim — a
+  contributor who reads *five* will not think to add a fixture for the sixth thing they
+  change.
+
+Found by the nine-repository audit of 2026-08-16 (umbrella `B-72`; the three documents
+are `F-agent-sync-05`, `-08` and `-11`).
+
 ## v1.11.1 — the gate can see an invariant it breaks elsewhere
 
 **This gate can now see an invariant it breaks one repository away.** The family umbrella
@@ -378,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
@@ -451,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,13 +1,15 @@
 {
   "name": "@ssheleg/agent-sync",
-  "version": "1.11.1",
-  "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.",
+  "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"
   },
   "files": [
     "bin/",
     "plugins/",
+    "!plugins/**/__pycache__",
+    "!plugins/**/*.pyc",
     "agent-sync.schema.json",
     "agent-sync.example.json",
     "README.md",

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

@@ -1,7 +1,7 @@
 {
   "name": "agent-sync",
   "displayName": "Agent Sync",
-  "version": "1.11.1",
+  "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.11.1"
+  version: "1.13.0"
   author: ssheleg
 ---
 

package/plugins/agent-sync/skills/agent-sync/references/hooks.md

@@ -103,6 +103,18 @@ echo '{"tool_name":"Edit","tool_input":{"file_path":"docs/DECISIONS.md"},"cwd":"
 
 ## Removing them
 
-Delete the `hooks` block from the project's `.claude/settings.json`. The skill keeps
-working — every guard is also available as a command, and the board simply records
-runs as `ungated` from then on.
+**Not** by editing `.claude/settings.json` — nothing here ever writes a `hooks`
+block there, and Claude Code has no per-hook disable for a hook a plugin ships. A
+reader who follows that instruction edits a file with no such block and concludes
+the removal worked while every hook keeps firing.
+
+Two levers actually work:
+
+- `enabledPlugins["agent-sync@agent-sync"] = false` in `~/.claude/settings.json` —
+  enablement is the only switch a plugin hook has; or
+- `claude plugin uninstall agent-sync@agent-sync`.
+
+And one you usually do not need: every hook already self-disables in a project with
+no `.claude/agent-sync.json` (`hooks/_lib.sh`), so a repository that never opted in
+is not paying for them. The skill keeps working either way — every guard is also
+available as a command, and the board simply records runs as `ungated` from then on.

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.11.1"
+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"),