@ssheleg/agent-sync 1.7.1 → 1.8.1

package/CHANGELOG.md

@@ -1,3 +1,87 @@
+## v1.8.1
+
+### Changed
+
+- **Six references over 100 lines now open with a `## Contents` list.** The
+  canon asks for it because a partial read is what an agent actually does with
+  a long reference; without the list, a partial read returns an arbitrary
+  slice. Generated from each file's own `##` headings, so the list cannot
+  disagree with the document.
+
+## 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.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.",
   "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.1",
   "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.1"
   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/references/backend-outline.md

@@ -2,6 +2,17 @@
 
 **Read this when** making any Outline API call or debugging one.
 
+## Contents
+
+- [Shape of the API](#shape-of-the-api)
+- [Capabilities](#capabilities)
+- [Primitive mapping](#primitive-mapping)
+- [Calling it without leaking the token](#calling-it-without-leaking-the-token)
+- [Rate limits](#rate-limits)
+- [Getting a token](#getting-a-token)
+- [Verifying an instance](#verifying-an-instance)
+
+
 [Outline](https://www.getoutline.com) is a collaborative knowledge base, available
 hosted or self-hosted. Both work; the instance URL is configuration, never code.
 

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

@@ -3,6 +3,15 @@
 **Read this when** starting work that will produce commits, merging a branch, or deciding
 where a claim should be written.
 
+## Contents
+
+- [The rule](#the-rule)
+- [Where a claim lives](#where-a-claim-lives)
+- [Landing the work](#landing-the-work)
+- [The merge log](#the-merge-log)
+- [What this does not do](#what-this-does-not-do)
+
+
 ## The rule
 
 > **Work happens on a branch. The integration branch is somebody else's stable base.**

package/plugins/agent-sync/skills/agent-sync/references/lease-protocol.md

@@ -3,6 +3,16 @@
 **Read this when** changing acquisition, expiry, stealing, or id allocation — or
 when two agents disagree about who holds something.
 
+## Contents
+
+- [Line grammar](#line-grammar)
+- [Acquiring — the third design, and the first that is true](#acquiring--the-third-design-and-the-first-that-is-true)
+- [Expiry and stealing](#expiry-and-stealing)
+- [Releasing](#releasing)
+- [Id reservation](#id-reservation)
+- [The lease is not the claim](#the-lease-is-not-the-claim)
+
+
 Two different mechanisms, and confusing them is how this went wrong twice:
 
 > **A lease is decided by an atomic operation** — `O_EXCL` on one filesystem, or a pushed

package/plugins/agent-sync/skills/agent-sync/references/pipeline-binding.md

@@ -2,6 +2,16 @@
 
 **Read this when** wiring `pipeline.json`, or adding a stage hook.
 
+## Contents
+
+- [The numbers, once](#the-numbers-once)
+- [Where it plugs in](#where-it-plugs-in)
+- [pipeline.json](#pipelinejson)
+- [What must be guarded](#what-must-be-guarded)
+- [Preflight](#preflight)
+- [Gate expressions](#gate-expressions)
+
+
 `agent-sync` supplies stages; it does not define them. The stage names below are
 `task-pipeline`'s own — do not rename, renumber or fork them.
 

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

@@ -3,6 +3,16 @@
 **Read this when** configuring `claimTags`, taking or releasing a task, closing one, or
 re-planning work that is already on a board.
 
+## Contents
+
+- [The two records, and why both exist](#the-two-records-and-why-both-exist)
+- [How the write is made safe](#how-the-write-is-made-safe)
+- [Configuring it](#configuring-it)
+- [Closing a task](#closing-a-task)
+- [Re-planning](#re-planning)
+- [When the claim cannot be written](#when-the-claim-cannot-be-written)
+
+
 The roadmap is where a project says *what is being done and by whom*. With several
 agents it is also the file most likely to be written by two of them at once, which is why
 it is guarded — and why the tool touches it as narrowly as it possibly can.

package/plugins/agent-sync/skills/agent-sync/references/two-sources.md

@@ -3,6 +3,16 @@
 **Read this when** starting a task, finishing one, or deciding where a piece of
 documentation belongs.
 
+## Contents
+
+- [They answer different questions](#they-answer-different-questions)
+- [The duty, both ends of a task](#the-duty-both-ends-of-a-task)
+- [What `reconcile` decides, and what it refuses to](#what-reconcile-decides-and-what-it-refuses-to)
+- [The baseline — why the check is a ratchet](#the-baseline--why-the-check-is-a-ratchet)
+- [Where a piece of documentation belongs](#where-a-piece-of-documentation-belongs)
+- [Lifetime, and why nothing is deleted](#lifetime-and-why-nothing-is-deleted)
+
+
 ## They answer different questions
 
 | Source | Answers | Written | Authority over |

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.1"
 
 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