@ssheleg/agent-sync 1.2.3 → 1.2.4

package/CHANGELOG.md

@@ -3,6 +3,35 @@
 All notable changes to this project are documented here.
 This project adheres to [Semantic Versioning](https://semver.org/).
 
+## 1.2.4 — 2026-07-29
+
+### Fixed — the tool misreported its own version, and disagreed with itself about the lease
+- **`VERSION` drifted a release behind.** The constant said `1.2.2` while every manifest
+  said `1.2.3`, so each `status` and `adopt` header named the wrong version — the exact
+  number the README tells an operator to compare when hunting a stale install channel.
+  `check_version_sync()` read five manifests and not the script; `check_scripts_run()` ran
+  `--version` only to prove the process starts, and threw the answer away. The constant is
+  now part of the sync check, so this cannot drift silently again.
+- **`gated` was decided by the record backend, which has not decided a lease since 1.0.0.**
+  It read the adapter's `atomicAppend`/`totalOrderRead` capabilities, and both directions
+  lied: `outline` with a local lock reported `gated` while exclusion was machine-local —
+  the pretended lease the skill's own trap 2 warns about — and `fs` with git refs reported
+  `ungated` while every lease was a genuine cross-machine compare-and-swap. It now derives
+  from `leaseBackend`.
+- **Six surfaces phrased the guarantee independently, and two called the knowledge base
+  the "lease authority".** `status` said `lease authority: NO — degraded` for the same
+  project where `check` said `exclusive on this machine` and `acquire` said something else
+  again. One guarantee described three ways reads as three guarantees, and an operator acts
+  on the weakest. The wording now lives in one table (`lease_guarantee()`), used by
+  `status`, `acquire`, `check`, the board, the setup snapshot and `init`. `status` reports
+  the record plane and the lease as the separate facts they are.
+
+### Added
+- **`test/validate.py` exercises the agreement**: for `leaseBackend` `local` and `git` it
+  runs `status`, `acquire` and `check` against a throwaway repository (a real bare remote
+  for `git`) and fails if any of them omits the guarantee, or if `status` still calls the
+  record backend the lease authority. Verified red against 1.2.3, green after.
+
 ## 1.2.3 — 2026-07-29
 
 ### Fixed — the guard blocked commits in projects that never installed agent-sync

package/README.md

@@ -282,19 +282,24 @@ configuration defect.
 
 ## Backends
 
-The knowledge store is a **pluggable adapter** — six primitives, three declared
-capabilities. Nothing about a specific vendor is baked in, and no instance address ships
-in this repository.
+**Two settings, two jobs.** `backend` chooses the record plane — where the log, the
+signals and the board live. `leaseBackend` chooses what actually decides a lease. The
+knowledge base is never the second one: measured against a real instance, twelve
+concurrent appends to one document returned twelve successes and left three lines.
 
-| Backend | Lease authority | Notes |
-|---|---|---|
-| `outline` | yes | [Outline](https://www.getoutline.com), hosted or self-hosted. Server-side append gives a total order without compare-and-swap |
-| `fs` | no — **degraded** | Local files. Real mutual exclusion between agents on one machine, none across machines. Every run is recorded `ungated` |
+| `backend` — the record plane | What it gives |
+|---|---|
+| `outline` | [Outline](https://www.getoutline.com), hosted or self-hosted. Every repository and machine reads one plane: shared awareness, cross-repo signals, the board |
+| `fs` | Local files. No credentials, and no visibility to an agent on another machine |
+
+| `leaseBackend` — the lease | Guarantee |
+|---|---|
+| `git` | **Exclusive across machines.** The remote's non-fast-forward rejection is a real compare-and-swap |
+| `local` *(default)* | **Exclusive on this machine, advisory across machines.** An atomic file create |
 
-**A backend that cannot arbitrate says so.** When the adapter is not the lease authority,
-`agent-sync` announces it, falls back to git-file leases, and marks runs `ungated` —
-because a lease that is not actually exclusive is worse than none, and the other agent
-has stopped checking.
+`status`, `acquire` and `check` all state which of the two you have, in the same words,
+because a lease that is not actually exclusive is worse than none: the other agent has
+stopped checking. `runs recorded: gated` follows the lease mode — never the record plane.
 
 Adding one: read
 [`references/adapter-contract.md`](plugins/agent-sync/skills/agent-sync/references/adapter-contract.md).
@@ -331,15 +336,18 @@ board at docs, release everything at acceptance. Wiring:
   expire one. Agents' clocks differ and the protocol does not depend on them.
 - **A reserved id that never reaches git is reported, not reclaimed.** A half-written
   decision on a branch is not an unused number.
-- **`fs` is not cross-machine.** It is a real mutex between agents on one host and
-  nothing more, which is why it never claims lease authority.
+- **`fs` is not cross-machine.** As a record plane it is invisible to agents on another
+  host, and the default `local` lease is a mutex on this one. Set `leaseBackend: "git"`
+  when a fleet spans machines; the tool says which guarantee you have rather than
+  implying the stronger one.
 
 ## Troubleshooting
 
 | Symptom | Cause and fix |
 |---|---|
 | `task-pipeline is not installed` and `status` stops | Intentional — there are no stages to bind to. `npx sshlg-skills install` |
-| `⚠ ungated backend — this lease is advisory` | The `fs` backend, or missing credentials. Expected; configure `outline` for enforced leases |
+| `⚠ this lease is advisory, not enforced` | `gated: false` in the config, or a `leaseBackend` that is neither `local` nor `git`. Fix the mode — an unknown one claims nothing on purpose |
+| `lease: local — advisory across machines` | Expected on the default. Set `leaseBackend: "git"` (and a reachable `leaseRemote`) when agents run on more than one machine |
 | Every `acquire` reports `lost` | Check the holder in `status`. If the log itself is unreadable, `acquire` raises instead — that is a parse failure, not a race |
 | Guarded edit blocked in Claude Code | Working as designed: `acquire` the key first, or unstage the file |
 | Guarded edit *not* blocked | You are not on Claude Code. Run `guard <path>` yourself; the run is `ungated` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssheleg/agent-sync",
-  "version": "1.2.3",
+  "version": "1.2.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,6 +1,6 @@
 {
   "name": "agent-sync",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "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": "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.2.3"
+  version: "1.2.4"
   author: appvillis-com
 ---
 
@@ -107,10 +107,13 @@ storage question gets asked and answered, once, and written down.
 1. **Where should coordination state live?**
    - a knowledge cloud (`outline`) — the shared record, awareness and board across
      machines. **It does not decide leases**; nothing in it can (trap 1);
-   - or local files (`fs`) — no credentials, no shared awareness, every run `ungated`.
+   - or local files (`fs`) — no credentials, and no visibility to an agent on another
+     machine: no shared awareness, no cross-repo signals, no shared board.
 
    The lease is decided separately by `leaseBackend` — `git` for cross-machine exclusion,
-   `local` otherwise.
+   `local` otherwise — and **`gated` follows that choice, never the record plane**. `fs`
+   with a local lock is still real exclusion between the agents on this machine; `outline`
+   with a local lock is *not* exclusion across them. Report the one you actually have.
 2. **If cloud: the instance URL.** The URL is configuration, not a secret, so you
    may write it. The **token is not** — you never ask for it in chat, never read it
    back, and never place it yourself.

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

@@ -32,13 +32,33 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
-VERSION = "1.2.2"
+VERSION = "1.2.4"
 
 CONFIG_PATH = Path(".claude/agent-sync.json")
 ENV_FILE = Path(".env.agent-sync")
 STATE_DIR = Path(".agent-sync")
 GENERATED_MARKER = "<!-- agent-sync:generated"
 
+# What a won lease is actually worth, in one place. Six surfaces used to phrase this
+# independently and two of them named the knowledge base as the authority — a role it
+# has not held since 1.0.0, when exclusion moved to a primitive the store cannot lose.
+# One guarantee described two ways reads as two guarantees, and an operator acts on the
+# weaker one.
+LEASE_GUARANTEE = {
+    "git": ("exclusive across machines",
+            "the remote's non-fast-forward rejection is a real compare-and-swap"),
+    "local": ("exclusive on this machine, advisory across machines",
+              'set `leaseBackend: "git"` if agents run on more than one'),
+}
+
+
+def lease_guarantee(mode: str) -> tuple[str, str]:
+    """The headline and the detail for a lease mode. Unknown modes claim nothing."""
+    return LEASE_GUARANTEE.get(
+        mode, ("NOT a lease — unknown mode, treat this project as unprotected",
+               f"'{mode}' is not a known leaseBackend; only {' or '.join(LEASE_GUARANTEE)}"))
+
+
 LOGS = {
     "claims": "30 Claims",
     "reservations": "40 Reservations",
@@ -615,7 +635,15 @@ class Sync:
 
     @property
     def gated(self) -> bool:
-        return bool(self.cfg.get("gated", True)) and self.adapter.is_lease_authority
+        """Whether exclusion is real — decided by the lease mode, never by the record.
+
+        Until 1.2.4 this read the record adapter's capabilities, which stopped deciding
+        leases in 1.0.0. Both directions were wrong: `outline` with a local lock reported
+        `gated` while exclusion was machine-local, and `fs` with git refs reported
+        `ungated` while every lease was a genuine cross-machine compare-and-swap. The
+        plane carries the record; `leaseBackend` decides the lease.
+        """
+        return bool(self.cfg.get("gated", True)) and self.lease_mode in LEASE_GUARANTEE
 
     def log_id(self, which: str) -> str:
         """This run's OWN shard. One writer per document, always.
@@ -1377,8 +1405,8 @@ class Sync:
             "Every repository on this plane writes and reads this page. It carries only "
             "facts that are true from any of them.",
             "",
-            f"- backend: `{self.adapter.name}` · lease authority: "
-            f"**{'yes' if self.adapter.is_lease_authority else 'no'}**",
+            f"- record plane: `{self.adapter.name}` · lease: `{self.lease_mode}` — "
+            f"**{lease_guarantee(self.lease_mode)[0]}**",
             f"- runs are recorded as **{'gated' if self.gated else 'ungated'}**",
             f"- unparseable log lines: {bad}/{total}"
             f"{'  ⚠ over 2% — the log cannot be replayed reliably' if bad / total > 0.02 else ''}",
@@ -1446,8 +1474,8 @@ class Sync:
             "",
             "## This project's wiring",
             "",
-            f"- backend: **{self.adapter.name}** · lease authority: "
-            f"**{'yes' if self.adapter.is_lease_authority else 'NO — degraded'}** · runs recorded "
+            f"- record plane: **{self.adapter.name}** · lease: **{self.lease_mode}** — "
+            f"{lease_guarantee(self.lease_mode)[0]} · runs recorded "
             f"**{'gated' if self.gated else 'ungated'}**",
             f"- lease TTL {cfg.get('leaseTtlSeconds', DEFAULT_TTL)}s, renewed every "
             f"{cfg.get('renewIntervalSeconds', DEFAULT_RENEW)}s",
@@ -1687,8 +1715,11 @@ def cmd_init(args: argparse.Namespace) -> int:
         print("  The token is yours alone: do not paste it into a chat, a commit, "
               "or a command line.")
     else:
-        print("Backend 'fs' needs no credentials. It is DEGRADED: it is not the lease")
-        print("authority, and every run is recorded as `ungated`. See references/backend-fs.md.")
+        print("Backend 'fs' needs no credentials. It is the record plane only, and a")
+        print("local one: agents on another machine see none of this project's leases,")
+        print("signals or board. The lease itself is decided by `leaseBackend` —")
+        print(f"default `local`, which is {lease_guarantee('local')[0]}.")
+        print("See references/backend-fs.md.")
     return 0
 
 
@@ -1739,14 +1770,18 @@ def cmd_status(_args: argparse.Namespace) -> int:
 
     s = Sync()
     ad = s.adapter
-    print(f"  backend        : {ad.name}")
-    print(f"  lease authority: {'yes' if ad.is_lease_authority else 'NO — degraded'}")
+    headline, detail = lease_guarantee(s.lease_mode)
+    print(f"  record plane   : {ad.name}"
+          f"{'' if ad.is_lease_authority else ' — local only, not shared between machines'}")
+    print(f"  lease          : {s.lease_mode} — {headline}")
     print(f"  runs recorded  : {'gated' if s.gated else 'UNGATED'}")
     print(f"  run id         : {s.rid}")
 
-    if not ad.is_lease_authority:
-        print("\n⚠ This backend cannot hold leases exclusively, so nothing here is")
-        print("  enforced. Do not describe this project as protected.")
+    if not s.gated:
+        print("\n⚠ Nothing here is enforced. Do not describe this project as protected.")
+        print(f"  {detail}")
+    elif not s.lease_is_cross_machine:
+        print(f"  ({detail})")
 
     if ad.name == "outline" and isinstance(ad, OutlineAdapter) and not ad.collection:
         print("\n✗ AGENT_SYNC_OUTLINE_COLLECTION is empty.")
@@ -1846,15 +1881,11 @@ def cmd_acquire(args: argparse.Namespace) -> int:
     s = Sync()
     won, holder = s.acquire(args.key)
     if won:
+        headline, detail = lease_guarantee(s.lease_mode)
         print(f"won {args.key} (run {s.rid}, ttl {s.ttl}s)")
-        if s.lease_is_cross_machine:
-            print("  exclusive across machines — the remote's non-fast-forward rule is a "
-                  "real compare-and-swap")
-        else:
-            print("  exclusive between agents on THIS machine; advisory across machines. "
-                  "Set `leaseBackend: \"git\"` for cross-machine exclusion.")
+        print(f"  {headline} — {detail}")
         if not s.gated:
-            print("⚠ ungated backend — this lease is advisory, not enforced")
+            print("⚠ this lease is advisory, not enforced")
         print("Remember: release it on every path, including failure.")
         return 0
     print(f"lost {args.key} — held by {holder or 'another run'}")
@@ -2225,18 +2256,19 @@ def cmd_check(_args: argparse.Namespace) -> int:
         ok.append(f"{len(cfg['claimTags'])} claim-tag mapping(s) declared")
 
     mode = cfg.get("leaseBackend") or "local"
-    if mode not in ("local", "git"):
-        problems.append(f"leaseBackend '{mode}' is not a known mode")
+    headline, detail = lease_guarantee(mode)
+    if mode not in LEASE_GUARANTEE:
+        problems.append(f"leaseBackend '{mode}': {headline} — {detail}")
     elif mode == "git":
         remote = cfg.get("leaseRemote") or "origin"
         if not git("remote", "get-url", remote):
             problems.append(f"leaseBackend is 'git' but remote '{remote}' does not exist — "
-                            "the lease cannot be decided at all")
+                            f"the lease cannot be decided at all ({headline} claimed, "
+                            "none delivered)")
         else:
-            ok.append(f"lease decided by git refs on '{remote}' — exclusive across machines")
+            ok.append(f"lease decided by git refs on '{remote}' — {headline}")
     else:
-        warn.append("lease is a local file lock: exclusive on this machine, advisory "
-                    "across machines. Set leaseBackend to 'git' if agents run on more than one")
+        warn.append(f"lease is a local file lock: {headline}. {detail[0].upper()}{detail[1:]}")
 
     for cmd in (cfg.get("gates") or []):
         exe = cmd.split()[0]