@ssheleg/agent-sync 1.20.0 → 1.20.2

package/CHANGELOG.md

@@ -1,3 +1,57 @@
+## v1.20.2 — the override that could not reach the plane the state was on
+
+**161 expired lease refs on one remote, from two runs that ended five days earlier, and
+no command in this tool could clear any of them.** Measured on the operator's machine
+2026-09-14: `residue` listed every one, `reap` left them alone (correctly — a ref in a
+dead run's name is `foreign`), and `reap --i-own-this`, the one path a person has for
+exactly this, answered *there is no lock by that name in this checkout*. True, and
+useless: in git mode the authority is `refs/agent-sync/leases/*` on the REMOTE, and the
+override walked the local lock directory only.
+
+This is AS-01b returning on the other plane. That row closed *"expired locks accumulate
+with no path out for anybody"* for the filesystem; the same sentence was true of the git
+plane the whole time, and the tool that reports it could not act on it.
+
+- `_reap_by_operator_decision` now reads **both planes** and collects entries per key as a
+  LIST — a key can be a lock file here AND a ref there, and clearing one while calling the
+  key done is how the ref survived every sweep that ran. A git entry is deleted through
+  `git_reap`'s existing `--force-with-lease` compare-and-swap and proved gone by a second
+  `ls-remote`, never by the push's exit code.
+- **Every refusal the override had, it keeps**, now per plane: a LIVE lease is refused and
+  named, a key nobody holds is reported rather than guessed at, the destroyed payload is
+  printed with its plane so the decision stays auditable, and the journal line carries it.
+- **A remote that cannot be read says so** instead of answering "no such lock" — that
+  answer reads as *there is nothing to clear* over state that may well be there.
+
+Three cases in `test/claim_cell_test.py` (27 total): the override clears a dead run's ref
+and proves it gone, a live ref is still refused, and an unreachable remote does not read
+as a missing key.
+
+## v1.20.1 — the filter that was never read, and the check that would have said so
+
+Claude Code 2.1.270 prints `agent-sync: hooks.json: unknown key "if" in
+hooks.PreToolUse[1] ignored` at every session start. The key was there since 0.1.0.
+
+- **`"if": "Bash(git commit *)"` sat beside `matcher`, and a matcher group is only
+  `matcher` + `hooks`** — read out of the 2.1.270 binary's schema, where `if` exists on a
+  command HANDLER only. So the filter was declared and never evaluated: `guard.sh` has run on
+  every Bash call in a coordinated project for its whole life, narrowing to a commit with its
+  own parser. Nothing in behaviour changes with the key gone; the warning does.
+- **Removed rather than moved.** A handler-level `if` would be real, and a real
+  `Bash(git commit *)` skips `git -C <dir> commit`, `env X=1 git commit` and
+  `cd d && git commit` — the three forms the parser covers and the 2026-08-07 measurement was
+  about. hooks.json's description, `guard.sh`'s header, `references/hooks.md`, the README hook
+  table and the live AS-09 row now say the same thing. `CHANGELOG` v1.18.6 and the 2026-07-29
+  spec keep their wording: dated records.
+- **`check_hooks_manifest` now refuses any key Claude Code does not know** — at group level
+  `{matcher, hooks}`, on a handler `{type, command, args, if, shell, timeout, statusMessage,
+  once, async, asyncRewake}` — with a self-test plant that puts the old `if` back and watches
+  the check fire. `claude plugin validate --strict` passes the defective file, so a repo gate
+  is the only place this fails before a session start.
+- `test/audit_regressions/fix-sy-07.01.py` derived "git commit is covered" from the group's
+  `if` — a declaration that never filtered. It now asserts the matchers, the description and
+  the absence of `if` at both levels.
+
 ## v1.20.0 — the two-sources duty stops carrying its own elaboration
 
 Sherlock external-v3 (14 findings) plus the House audit gap they introduced.

package/README.md

@@ -403,7 +403,7 @@ never grants one that would otherwise be denied.
 | Hook | Runs | Effect |
 |---|---|---|
 | `SessionStart` | startup, resume | `status` — the board summary, other runs, one next action |
-| `PreToolUse` | `Edit`/`Write`/`MultiEdit`/`NotebookEdit`, and `git commit` | Denies the edit (exit 2) when the path is guarded and this run holds no lease; a `git commit` is checked against every staged path |
+| `PreToolUse` | `Edit`/`Write`/`MultiEdit`/`NotebookEdit`, and every `Bash` call — of which only a parsed `git commit` is acted on | Denies the edit (exit 2) when the path is guarded and this run holds no lease; a `git commit` is checked against every staged path |
 | `PostToolUse` | every tool call | Throttled `renew` — touches the network at most once per `renewIntervalSeconds` |
 | `SessionEnd` | session end | Releases every lease this run holds |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssheleg/agent-sync",
-  "version": "1.20.0",
+  "version": "1.20.2",
   "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

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "agent-sync",
   "displayName": "Agent Sync",
-  "version": "1.20.0",
+  "version": "1.20.2",
   "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/hooks/guard.sh

@@ -32,8 +32,10 @@ S="$AGENT_SYNC_PY"
 agent_sync_configured || exit 0
 input=$(cat)
 
-# The parser IS the guard: hooks.json's `if` filter is best-effort and fails open by
-# doctrine, so nothing upstream compensates for a parser that cannot run. A python3
+# The parser IS the guard: hooks.json carries no `if` filter (the one it declared until
+# v1.20.1 sat at the group level, where Claude Code never evaluated it, and a handler-level
+# one would skip `git -C`/env/compound commits), so nothing upstream compensates for a
+# parser that cannot run. A python3
 # missing from PATH used to leave `path` empty, default `is_commit` to 0 and exit 0 —
 # the one machine state that disables the parser silently disabled the guard (ASY-07).
 parser_or_die() {

package/plugins/agent-sync/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "agent-sync — ADVISORY lease guard and run lifecycle. The PreToolUse guard covers exactly the mutation surfaces a Claude Code matcher can name: Edit, Write, MultiEdit, NotebookEdit, and a Bash `git commit` (parsed for compound/`-C`/env forms). It is NOT a sandbox: a language-runtime write (Python write_text), a `sed -i`, or a shell redirect is OUTSIDE the boundary and is not enforced — see the capability matrix in guard.sh. Real enforcement needs a trusted mutation API, an isolated worktree, or OS controls with resource locks, not a regex shell parser. Every hook exits 0 immediately when the project has no .claude/agent-sync.json, so installing the plugin globally changes nothing in projects that do not use it.",
+  "description": "agent-sync — ADVISORY lease guard and run lifecycle. The PreToolUse guard covers exactly the mutation surfaces a Claude Code matcher can name: Edit, Write, MultiEdit, NotebookEdit, and a Bash `git commit` (parsed for compound/`-C`/env forms). It is NOT a sandbox: a language-runtime write (Python write_text), a `sed -i`, or a shell redirect is OUTSIDE the boundary and is not enforced — see the capability matrix in guard.sh. Real enforcement needs a trusted mutation API, an isolated worktree, or OS controls with resource locks, not a regex shell parser. The Bash group carries NO `if` filter on purpose: guard.sh narrows to a git commit itself. A group-level `if` is not a key Claude Code knows (it is ignored and, from 2.1.270, reported as unknown), and a handler-level one would skip the `git -C`, env-prefixed and compound forms the parser covers. Every hook exits 0 immediately when the project has no .claude/agent-sync.json, so installing the plugin globally changes nothing in projects that do not use it.",
   "hooks": {
     "SessionStart": [
       {
@@ -28,7 +28,6 @@
       },
       {
         "matcher": "Bash",
-        "if": "Bash(git commit *)",
         "hooks": [
           {
             "type": "command",

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.20.0"
+  version: "1.20.2"
   author: ssheleg
 ---
 

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

@@ -57,7 +57,7 @@ The hook receives JSON on stdin with `session_id`, `prompt_id`, `transcript_path
     "PreToolUse": [
       { "matcher": "Edit|Write|MultiEdit|NotebookEdit",
         "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/guard.sh" }] },
-      { "matcher": "Bash", "if": "Bash(git commit *)",
+      { "matcher": "Bash",
         "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/guard.sh" }] }
     ],
     "PostToolUse": [
@@ -71,6 +71,15 @@ The hook receives JSON on stdin with `session_id`, `prompt_id`, `transcript_path
 }
 ```
 
+The `Bash` group has no `if` filter, and that is deliberate. Until v1.20.1 it declared
+`"if": "Bash(git commit *)"` beside `matcher` — a key Claude Code does not know at
+the group level, so it was never evaluated (and 2.1.270 started saying so at every
+session start). Moving it into the handler would make it real, and a real one skips
+`git -C <dir> commit`, `env X=1 git commit` and `cd d && git commit` — the forms the
+parser in `guard.sh` was written to cover. So `guard.sh` runs on every Bash call in a
+coordinated project, exits 0 in a few milliseconds when the command is not a commit,
+and the parser is the whole narrowing.
+
 | Hook | Job |
 |---|---|
 | `session-start.sh` | Register the run, print the board summary and the one next action |

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.20.0"
+VERSION = "1.20.2"
 
 CONFIG_PATH = Path(".claude/agent-sync.json")
 ENV_FILE = Path(".env.agent-sync")
@@ -4327,6 +4327,18 @@ def _reap_by_operator_decision(s: "Sync", keys: list[str]) -> int:
     * **it prints the payload it destroyed** — run, timestamp, machine — so the decision is
       auditable afterwards by somebody who was not there, and journals it where a record
       plane is configured.
+
+    **Both planes, because AS-01b came back on the other one.** Until v1.20.2 this walked
+    the lock DIRECTORY only. In git mode the authority is `refs/agent-sync/leases/*` on the
+    remote, a ref outlives the checkout that wrote it, and `reap` clears a git ref only when
+    the classifier calls it `reapable` — this run's own. So an expired ref in a DEAD run's
+    name had no path out from anywhere: `residue` listed it, `reap` left it alone, and
+    `--i-own-this` answered *there is no lock by that name in this checkout*, which is true
+    and useless. Measured on this machine 2026-09-14: **161 refs from two runs that ended on
+    2026-09-09 and 2026-09-10**, every one expired more than four days against a 2700-second
+    TTL, with no command able to reach them. That is the identical shape AS-01b closed for
+    the local plane — "expired locks accumulate with no path out for anybody" — and the
+    remedy is the identical one, applied where the state actually lives.
     """
     if not keys:
         print("reap --i-own-this needs the keys, one or more, by name.\n"
@@ -4336,48 +4348,94 @@ def _reap_by_operator_decision(s: "Sync", keys: list[str]) -> int:
               file=sys.stderr)
         return 2
 
-    by_key = {}
+    # A key can exist on BOTH planes — a lock file here and a ref on the remote — and the
+    # two are separate pieces of state with separate deletes. Collected as a LIST per key
+    # rather than a dict, because clearing one and calling the key done is how the git ref
+    # survived every sweep that ever ran.
+    by_key: dict[str, list[dict[str, Any]]] = {}
+
+    def offer(entry: dict[str, Any]) -> None:
+        by_key.setdefault(entry["key"], []).append(entry)
+        stem = s._local_lock(entry["key"]).stem
+        if stem != entry["key"]:
+            by_key.setdefault(stem, []).append(entry)
+
     for e in s.residue():
-        by_key.setdefault(e["key"], e)
-        by_key.setdefault(s._local_lock(e["key"]).stem, e)
+        e.setdefault("plane", "fs")
+        offer(e)
+    git_unreadable = None
+    if s.lease_mode == "git":
+        refs, git_unreadable = s.git_residue()
+        for e in refs:
+            offer(e)
+        if git_unreadable is not None:
+            print(f"  ⚠ the git plane could not be read ({git_unreadable}) — anything on it "
+                  "is neither cleared nor\n    reported clean. Enumerate by hand: git "
+                  f"ls-remote {s.cfg.get('leaseRemote') or 'origin'} "
+                  "'refs/agent-sync/leases/*'", file=sys.stderr)
 
     rc = 0
     for k in keys:
-        e = by_key.get(k) or by_key.get(s._local_lock(k).stem)
-        if e is None:
-            print(f"  · {k} — there is no lock by that name in this checkout", file=sys.stderr)
-            rc = 1
-            continue
-        if e["state"] == LIVE:
-            print(f"  ✗ {e['key']} is LIVE under {e.get('run') or 'a run'}"
-                  f"{' on ' + e['host'] if e.get('host') else ''} — not cleared. An override "
-                  "is for residue;\n    a live lease belongs to a run that may still be "
-                  "working. Ask the holder, or wait for the TTL.", file=sys.stderr)
-            rc = 1
-            continue
-        had = (f"run {e.get('run') or 'unknown'}"
-               f"{' · host ' + e['host'] if e.get('host') else ''}"
-               f"{' · ' + e['ts'] if e.get('ts') else ''}"
-               f" · {spent(e)}")
-        try:
-            e["path"].unlink()
-        except OSError as exc:
-            print(f"  ✗ {e['key']} could not be removed ({exc})", file=sys.stderr)
-            rc = 1
-            continue
-        # Proved gone by looking again, the same rule the ordinary reap follows.
-        if any(x["key"] == e["key"] for x in s.residue()):
-            print(f"  ✗ {e['key']} is STILL PRESENT after the delete — the teardown was not "
-                  "verified, whatever the call returned", file=sys.stderr)
+        entries = by_key.get(k) or by_key.get(s._local_lock(k).stem) or []
+        # Deduplicate: the stem alias can offer the same object twice.
+        seen_ids, unique = set(), []
+        for e in entries:
+            if id(e) in seen_ids:
+                continue
+            seen_ids.add(id(e))
+            unique.append(e)
+        if not unique:
+            where = "this checkout" if s.lease_mode != "git" else (
+                "this checkout or on the remote" if git_unreadable is None
+                else "this checkout (the remote could not be read)")
+            print(f"  · {k} — there is no lock by that name in {where}", file=sys.stderr)
             rc = 1
             continue
-        print(f"  cleared {e['key']} by operator decision — it held {had}")
-        print(f"    the classifier called it `{e['state']}`, and that has not changed: this "
-              "was a person's\n    call, not a proof of ownership.")
-        try:
-            s.journal(f"reap --i-own-this {e['key']} — was {had}, classified {e['state']}")
-        except Exception:                                # noqa: BLE001 - the record plane is optional
-            pass
+        for e in unique:
+            plane = e.get("plane", "fs")
+            if e["state"] == LIVE:
+                print(f"  ✗ {e['key']} [{plane}] is LIVE under {e.get('run') or 'a run'}"
+                      f"{' on ' + e['host'] if e.get('host') else ''} — not cleared. An override "
+                      "is for residue;\n    a live lease belongs to a run that may still be "
+                      "working. Ask the holder, or wait for the TTL.", file=sys.stderr)
+                rc = 1
+                continue
+            had = (f"run {e.get('run') or 'unknown'}"
+                   f"{' · host ' + e['host'] if e.get('host') else ''}"
+                   f"{' · ' + e['ts'] if e.get('ts') else ''}"
+                   f" · {spent(e)}")
+            if plane == "git":
+                # The same compare-and-swap the ordinary reap uses, and the same proof:
+                # a second read of the remote, never the push's exit code.
+                done = s.git_reap([e])[0]
+                if not done.get("gone"):
+                    print(f"  ✗ {e['key']} is STILL on the remote after the delete "
+                          f"({done.get('why_gone') or 'no reason given'}) — either somebody "
+                          "won it between the read\n    and the delete, or the remote "
+                          "refused. Nothing was reported as cleared.", file=sys.stderr)
+                    rc = 1
+                    continue
+            else:
+                try:
+                    e["path"].unlink()
+                except OSError as exc:
+                    print(f"  ✗ {e['key']} could not be removed ({exc})", file=sys.stderr)
+                    rc = 1
+                    continue
+                # Proved gone by looking again, the same rule the ordinary reap follows.
+                if any(x["key"] == e["key"] for x in s.residue()):
+                    print(f"  ✗ {e['key']} is STILL PRESENT after the delete — the teardown was not "
+                          "verified, whatever the call returned", file=sys.stderr)
+                    rc = 1
+                    continue
+            print(f"  cleared {e['key']} [{plane}] by operator decision — it held {had}")
+            print(f"    the classifier called it `{e['state']}`, and that has not changed: this "
+                  "was a person's\n    call, not a proof of ownership.")
+            try:
+                s.journal(f"reap --i-own-this {e['key']} [{plane}] — was {had}, "
+                          f"classified {e['state']}")
+            except Exception:                            # noqa: BLE001 - the record plane is optional
+                pass
     return rc