@ssheleg/agent-sync 1.7.1 → 1.8.0

package/CHANGELOG.md

@@ -1,3 +1,77 @@
+## v1.8.0
+
+**The board, cleared.** Nine rows opened by the two audits of 2026-08-10, closed with a check, a
+measurement or a written decision — because a backlog nobody empties is a list of things everyone
+has agreed to stop seeing.
+
+### The two scenarios that were only ever driven by hand are now gated
+
+Two agents contending for one task, and the guard across every shape a write arrives in, were
+verified by executing them and had no check that fails on its own — the exact state in which the
+first audit found six shipped defects. `check_two_agents_cannot_share_one_task` drives the full
+sequence from two identities: the second run loses, is told who holds it, sees the holding in
+`status`, is denied the guarded registry, cannot release a lease it does not hold, and the holder
+can. `check_guard_covers_every_write_shape` drives nine payloads through the real hook — `Edit`,
+`Write`, `NotebookEdit`, an unguarded file, `git commit`, `git -C <dir> commit`,
+`cd <dir> && git commit`, `git log --grep=commit`, and malformed input — with and without the lease.
+
+Planting the first defect took two mutations, not one, and that is worth recording: breaking only
+`acquire`'s expiry check still refuses the steal, because `_steal_expired` re-reads the expiry
+**inside** the critical section. The exclusion has two independent layers. The single-point fixture
+was MISSED, which is how that was discovered.
+
+### `check_merge_releases_only_its_key`
+
+`merge --key` must release that lease and leave the others held. It was verified by reading the
+code, and every defect the first audit found was in something verified by reading.
+
+### `status` on a large repository: 3.2 s → 0.5 s
+
+`check` resolved guarded and claim-tag patterns by walking the whole tree **once per pattern** —
+five patterns over a 20 000-file repository is five full walks, measured at 3.2 s for a single
+`status`, which is a `SessionStart` hook. It now walks once, and uses git's own index where there is
+one, so `.gitignore` is honoured for free. Same output, six times faster.
+
+### `check_commands_work_without_the_family_installed`
+
+Runs the commands with `HOME` redirected at an empty directory — the state of every CI runner, and
+where the task-pipeline ordering defect was obvious while this development machine could not see it.
+The check proves its own isolation on a healthy project before asserting on a broken one, because a
+probe that cannot fail is not a probe.
+
+### The self-test: 6 min → 2.8 min
+
+Each fixture now runs as its own process, eight at a time. It was a loop that reassigned module
+globals and called `main()` in-band, once per fixture; at 32 fixtures it had already blown a
+ten-minute command budget, and a suite people stop running is a suite that does not exist. The
+subprocess also removes the global-state reset that made parallelism impossible.
+
+### Decisions recorded rather than deferred again
+
+**`settleSeconds` stays.** It is the adapter contract's extension point for a store whose writes are
+not immediately readable; removing it would fail every config that carries one to buy nothing.
+Written into `references/adapter-contract.md`, where the next reader will look.
+
+**Blockers stay gone.** The concept needs a writer, a reader and a place on the board before the
+word earns a document.
+
+**Guard latency is fine:** 130–220 ms per guarded edit with no run id in the environment, against a
+`PreToolUse` budget of 20 s. Measured, recorded, no change.
+
+### Also
+
+`actions/checkout@v5`, `actions/setup-node@v5`, `actions/setup-python@v6` — the v4 pins were being
+forced onto Node 24 by the runner and annotated every release.
+
+`merge` also gained a preflight it was missing. A merge commit is authorship, so it needs a real
+git identity — unlike a lease object, which is plumbing and is written with a synthetic one on
+purpose. Without one the merge started, git refused at the commit, and the abort path ran: it
+recovers, and it is still not what a command whose whole doctrine is *every check before anything
+is touched* promises. Found by CI, because a runner has no global `.gitconfig` and this machine
+does — the same blind spot, twice in one day.
+
+The validator now runs 44 checks and plants and catches 37 distinct defects.
+
 ## v1.7.1
 
 **A second audit, along a different axis: not whether the tool keeps its promises, but whether an

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssheleg/agent-sync",
-  "version": "1.7.1",
+  "version": "1.8.0",
   "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",
   "displayName": "Agent Sync",
-  "version": "1.7.1",
+  "version": "1.8.0",
   "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": "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.7.1"
+  version: "1.8.0"
   author: ssheleg
 ---
 

package/plugins/agent-sync/skills/agent-sync/references/adapter-contract.md

@@ -1,3 +1,11 @@
+> **`settleSeconds` is this contract's extension point, and nothing shipped reads it.**
+> It exists for an adapter whose writes are not immediately visible to a subsequent read —
+> a store with an asynchronous index, where a reader must wait before replaying. Neither
+> `outline` nor `fs` needs it, so `check` says plainly that setting it does nothing here.
+> It is kept rather than removed because deleting it would make every config carrying one
+> fail validation to buy nothing, and because an adapter that needs it has nowhere else to
+> ask. If you add a backend that waits, this is the knob; if you do not, ignore it.
+
 # Adapter contract
 
 **Read this when** adding a knowledge backend, auditing one, or deciding whether a

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.7.1"
+VERSION = "1.8.0"
 
 CONFIG_PATH = Path(".claude/agent-sync.json")
 ENV_FILE = Path(".env.agent-sync")
@@ -231,18 +231,41 @@ def matches_glob(rel: str, pattern: str) -> bool:
     return bool(rx.match(rel.replace(os.sep, "/")))
 
 
-def glob_files(root: Path, pattern: str) -> list[Path]:
-    """Every existing file the pattern covers, by the same rule the guard applies."""
+def _tracked_files(root: Path) -> list[str]:
+    """Every candidate path in the repository, walked ONCE.
+
+    `glob_files` used to walk the whole tree per pattern, and `check` calls it for every
+    guarded pattern and every claim-tag pattern — five patterns over a 20 000-file
+    repository is five full walks. Measured at ~3 s for a single `status`, which since
+    1.7.0 runs `check`, and `status` is a `SessionStart` hook. Git's own index is used
+    where it exists, because it already excludes everything `.gitignore` does; the walk
+    is the fallback for files not yet tracked.
+    """
+    listed = git("ls-files", "--cached", "--others", "--exclude-standard", cwd=root)
+    if listed:
+        return listed.split("\n")
     skip = {".git", "node_modules", STATE_DIR.name}
-    out: list[Path] = []
+    out: list[str] = []
     for path in root.rglob("*"):
-        if skip & set(path.relative_to(root).parts):
+        rel = path.relative_to(root)
+        if skip & set(rel.parts):
             continue
-        if path.is_file() and matches_glob(str(path.relative_to(root)), pattern):
-            out.append(path)
+        if path.is_file():
+            out.append(str(rel))
     return out
 
 
+def glob_files(root: Path, pattern: str) -> list[Path]:
+    """Every existing file the pattern covers, by the same rule the guard applies."""
+    return [root / rel for rel in _tracked_files(root) if matches_glob(rel, pattern)]
+
+
+def glob_files_many(root: Path, patterns: list[str]) -> dict[str, list[Path]]:
+    """The same answer for several patterns, from one walk."""
+    files = _tracked_files(root)
+    return {p: [root / rel for rel in files if matches_glob(rel, p)] for p in patterns}
+
+
 # --------------------------------------------------------------------------- config
 
 def find_env_file(root: Path) -> Path | None:
@@ -3155,9 +3178,11 @@ def check_setup(root: Path) -> tuple[list[str], list[str], list[str]]:
             ok.append(f"register {reg} allocates from {spec['file']} ({reg}-{m.group(1)})")
 
     # A guard glob that matches nothing protects nothing. Resolved by the same function
-    # the guard itself applies, so the two commands cannot disagree about one pattern.
+    # the guard itself applies, so the two commands cannot disagree about one pattern —
+    # and from one walk of the repository, not one per pattern.
+    guard_hits = glob_files_many(root, list(cfg.get("guardedFiles") or []))
     for pattern in (cfg.get("guardedFiles") or []):
-        hits = glob_files(root, pattern)
+        hits = guard_hits.get(pattern) or []
         if not hits:
             problems.append(f"guarded pattern '{pattern}' matches no file — it guards nothing")
     if cfg.get("guardedFiles"):
@@ -3165,8 +3190,9 @@ def check_setup(root: Path) -> tuple[list[str], list[str], list[str]]:
     else:
         warn.append("no guarded files — nothing requires a lease in this repository")
 
+    claim_hits = glob_files_many(root, list(cfg.get("claimTags") or {}))
     for pattern, spec in (cfg.get("claimTags") or {}).items():
-        files = glob_files(root, pattern)
+        files = claim_hits.get(pattern) or []
         if not files:
             problems.append(f"claimTags pattern '{pattern}' matches no file")
             continue
@@ -3397,6 +3423,21 @@ def cmd_merge(args: argparse.Namespace) -> int:
         raise Fail(f"working tree is not clean ({len(dirty)} path(s)) — commit or stash first; "
                    "a merge cannot tell your uncommitted work from the branch's")
 
+    # A merge commit is authorship, so it needs a real identity — unlike a lease object,
+    # which is plumbing and is written with a synthetic one on purpose. Checked HERE
+    # because everything in this command is checked before anything is touched: without
+    # it the merge starts, git refuses at the commit, and the abort path runs. That is
+    # recoverable and it is still not what this command promises. It is also the ordinary
+    # state of a CI runner and a fresh container, which is where it was found.
+    ident = subprocess.run(["git", "var", "GIT_COMMITTER_IDENT"],
+                           capture_output=True, text=True)
+    if ident.returncode != 0:
+        why = (ident.stderr or "").strip().splitlines()
+        raise Fail("git has no committer identity here, so the merge commit cannot be "
+                   "written. Set one and run this again — nothing was touched:\n"
+                   "  git config user.name '<you>' && git config user.email '<you@example>'"
+                   + (f"\n  ({why[-1]})" if why else ""))
+
     git("fetch", "--quiet", "origin", target)
     upstream = f"origin/{target}" if git("rev-parse", "--verify", "--quiet", f"origin/{target}") else target