@ssheleg/agent-sync 1.18.5 → 1.18.6

package/CHANGELOG.md

@@ -1,3 +1,40 @@
+## v1.18.6 — the guard keeps its own header's promise, and /clear gets its own identity
+
+Wave-2 hardening from the 2026-08-29 family audit (ASY-07, ASY-08, ASY-06, ASY-01).
+Same shape as v1.18.5: text that claimed more than the code did.
+
+- **ASY-07 — a machine without python3 had no guard, and said nothing.** `guard.sh`'s
+  header promises that every internal failure exits 2, because any other outcome is
+  non-blocking in Claude Code — and the python3-absent path broke it: both parser
+  substitutions failed under `2>/dev/null`, `path` came back empty, `is_commit`
+  defaulted to 0 and the hook exited 0. Fail OPEN, exactly where the header says it
+  must not, and nothing upstream compensates — hooks.json's `if` filter is best-effort
+  by doctrine, so the parser IS the guard. Both substitutions now report through
+  `parser_or_die`, which exits 2 and names the remedy (install python3 / fix PATH, or
+  remove `.claude/agent-sync.json` to switch coordination off).
+  `check_guard_fails_closed_without_python3` drives the real hook through a shim PATH
+  holding bash and cat but no interpreter — watched failing against the shipped guard
+  (`the guard exited 0`) — and the self-test plants the fail-open back
+  (`an absent interpreter fails open`).
+- **ASY-08 — a post-/clear session inherited the ended run's identity.** The
+  SessionStart matcher read `startup|resume`, and `/clear` ends the run while keeping
+  the CLI process — so the stamp keyed by that process survived into the next session:
+  "two sessions, one identity", the case SKILL.md itself names, and `release` then
+  takes a lease the caller never had. The matcher now carries `clear`; `compact` stays
+  excluded deliberately, because a compaction continues the SAME session.
+  `hooks_session_test.py` gained the case (matcher parts asserted both directions, and
+  the hook re-stamps on a clear payload) — watched failing against the shipped matcher.
+- **ASY-06 — the guard's internal-failure refusal named no next step.** A refusal with
+  no remedy is how an operator learns to switch a hook off. The message now says:
+  diagnose with `python3 <script> check`, or acquire a lease first.
+- **ASY-01 — `scripts/__pycache__` regenerated forever.** Hooks now export
+  `PYTHONDONTWRITEBYTECODE=1` in `_lib.sh` (sourced by all four), and the test files
+  that import `agent_sync.py` set `sys.dont_write_bytecode` — the shipped `scripts/`
+  directory stays source, not build products.
+- ASY-04 (this test class missing from CI) was already closed in v1.18.5:
+  `validate.yml` runs `hooks_session_test.py` since commit `5446990`. Verified, not
+  re-done. ASY-02 (command rename) closed by operator decision 2026-08-30: names stay.
+
 ## v1.18.5 — a pipe reaches the guard, and the installers stop deleting blind
 
 Two enforcement holes, each of the same shape: a mechanism whose own text claimed more

package/package.json

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

@@ -1,7 +1,7 @@
 {
   "name": "agent-sync",
   "displayName": "Agent Sync",
-  "version": "1.18.5",
+  "version": "1.18.6",
   "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/_lib.sh

@@ -1,6 +1,11 @@
 #!/usr/bin/env bash
 # Shared helpers for the agent-sync hooks. Sourced, never executed.
 
+# Every hook runs python3 against the shipped scripts/ directory, which people read
+# as source, not as a build product. Bytecode caching buys nothing at this call rate
+# and left scripts/__pycache__ regenerating forever (ASY-01).
+export PYTHONDONTWRITEBYTECODE=1
+
 # Run a command under a time limit, portably.
 #
 # `timeout` is GNU coreutils and is NOT on a stock macOS. Calling it directly made

package/plugins/agent-sync/hooks/guard.sh

@@ -8,6 +8,17 @@ 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
+# 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() {
+  local rc="$1"
+  [ "$rc" -eq 0 ] && return 0
+  echo "agent-sync: the guard could not run its parser (python3 exit $rc — likely missing from PATH). Failing closed. Install python3 or fix PATH and retry, or remove .claude/agent-sync.json to switch coordination off here." >&2
+  exit 2
+}
+
 path=$(python3 -c '
 import json,sys
 try:
@@ -17,6 +28,7 @@ except Exception:
 ti=d.get("tool_input") or {}
 print(ti.get("file_path") or ti.get("path") or ti.get("notebook_path") or "")
 ' <<<"$input" 2>/dev/null)
+parser_or_die $?
 
 # git commit: check every staged path instead of a single file argument.
 if [ -z "$path" ]; then
@@ -30,7 +42,7 @@ if [ -z "$path" ]; then
   #
   # Tokenised in python rather than globbed in shell: `git log --grep=commit` must not match, and
   # `git -c user.name=x -C dir commit` must.
-  read -r is_commit repo <<<"$(python3 -c '
+  parsed=$(python3 -c '
 import json, shlex, sys
 try:
     d = json.load(sys.stdin)
@@ -71,7 +83,9 @@ for seg in cmd.replace("&&", "\n").replace("||", "\n").replace("|&", "\n").repla
             repo = r
         break
 print(is_commit, repo)
-' <<<"$input" 2>/dev/null)"
+' <<<"$input" 2>/dev/null)
+  parser_or_die $?
+  read -r is_commit repo <<<"$parsed"
   [ -n "${is_commit:-}" ] || is_commit=0
   [ -n "${repo:-}" ] || repo="."
   [ -d "$repo" ] || repo="${CLAUDE_PROJECT_DIR:-$PWD}"
@@ -100,6 +114,6 @@ else
     echo "$out" >&2
     exit 2
   fi
-  echo "agent-sync guard failed to run ($code): $out" >&2
+  echo "agent-sync guard failed to run ($code): $out — diagnose with \`python3 $S check\`, or acquire a lease first: \`python3 $S acquire <TASK-ID>\`" >&2
   exit 2
 fi

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

@@ -3,7 +3,7 @@
   "hooks": {
     "SessionStart": [
       {
-        "matcher": "startup|resume",
+        "matcher": "startup|resume|clear",
         "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.18.5"
+  version: "1.18.6"
   author: ssheleg
 ---
 

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.18.5"
+VERSION = "1.18.6"
 
 CONFIG_PATH = Path(".claude/agent-sync.json")
 ENV_FILE = Path(".env.agent-sync")