@ssheleg/agent-sync 1.16.0 → 1.17.0

package/CHANGELOG.md

@@ -1,3 +1,31 @@
+## v1.17.0 — the identity that had never once been established
+
+`_session_key()` falls back to one `shared` entry per checkout when it cannot tell which
+session is asking, and everything downstream hedges about it: `classify_lock` answers
+`ambiguous` rather than `reapable`, so an expired lease can never be cleared by the run that
+took it. The fallback was documented as the rare case.
+
+It was the only case. Measured 2026-08-25 in a checkout that had been running the tool all
+day: `.agent-sync/sessions` did not exist, and `.agent-sync/run-id` held exactly one key —
+`shared`. The stamping block in `session-start.sh` required `CLAUDE_SESSION_ID` in the hook's
+**environment**, and Claude Code delivers the id to a hook on **stdin as JSON**, which is how
+`guard.sh` next to it has always read its own payload. So the block had never run, in any
+session, since it was written. A fallback that is always taken is not a fallback.
+
+The hook reads its payload now, with the environment variable still winning where it exists.
+`test/hooks_session_test.py` runs the real hook as a process — the only way this was ever
+going to be caught, because every unit around it was correct — and covers the four ways it
+must behave: an id from stdin is stamped, an id from the environment still wins, a payload
+carrying no id stamps nothing rather than keying every session alike, and a payload that is
+not JSON leaves the hook exit 0, because a SessionStart hook that throws takes the session
+with it. A fifth case walks the whole chain: stamp, then the descendant's key, then the
+run-id map, then `classify_lock` returning `reapable` where it used to return `ambiguous`.
+
+Watched failing against the previous hook: 2 of the 5 cases red, and green after.
+
+Also: the README no longer tells a reader to run `python3 test/validate.py` and `npm test`
+from a package that ships no `test/` directory. It names where they run.
+
 ## Unreleased — both `AS-01` halves exercised outside their fixtures
 
 The two rows sat at priority `unverified`: shipped, and confirmed by nothing but their own

package/README.md

@@ -444,6 +444,10 @@ and `.agent-sync/` if you want the project clean too.
 
 ## Develop and verify
 
+<!-- commands-run-in: a clone -->
+These run **in a clone of this repository**. The published npm package ships no
+`test/` directory, so from an install they are names, not commands.
+
 ```bash
 python3 test/validate.py             # manifests, version sync, no host/credential leaks
 python3 test/validate.py --self-test # the validator must still be able to fail

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssheleg/agent-sync",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "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"
@@ -17,7 +17,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "python3 test/validate.py && python3 test/validate.py --self-test && python3 test/claim_cell_test.py",
+    "test": "python3 test/validate.py && python3 test/validate.py --self-test && python3 test/claim_cell_test.py && python3 test/hooks_session_test.py",
     "prepublishOnly": "python3 test/validate.py"
   },
   "publishConfig": {

package/plugins/agent-sync/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-sync",
   "displayName": "Agent Sync",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "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/session-start.sh

@@ -6,14 +6,36 @@ S="$AGENT_SYNC_PY"
 agent_sync_configured || exit 0
 
 # Stamp who this session is, keyed by the process every command in it descends from.
-# A hook has CLAUDE_SESSION_ID in its environment and a plain shell command does not, so without
-# this a second session in the same checkout adopts the first one's identity: both acquire and
-# release as one run, and the lease stops separating the exact case it exists for. $PPID here is
-# the CLI process, which is the one ancestor every later command shares.
-if [ -n "${CLAUDE_SESSION_ID:-}" ]; then
+# Without this a second session in the same checkout adopts the first one's identity: both
+# acquire and release as one run, and the lease stops separating the exact case it exists for.
+# $PPID here is the CLI process, which is the one ancestor every later command shares.
+#
+# The id arrives on STDIN as JSON, the way every other hook here reads its payload -- see
+# guard.sh. This block used to require CLAUDE_SESSION_ID in the ENVIRONMENT and nothing else,
+# so on this machine it never ran once: measured 2026-08-25, `.agent-sync/sessions` had never
+# been created and the run-id map held a single `shared` key, which is the weak identity that
+# makes an expired lease unattributable and `reap` refuse it forever. A fallback that is always
+# taken is not a fallback.
+if [ -t 0 ]; then
+  payload=""                       # no stdin (invoked by hand) -- do not block on `cat`
+else
+  payload=$(cat 2>/dev/null || true)
+fi
+sid="${CLAUDE_SESSION_ID:-}"
+if [ -z "$sid" ] && [ -n "$payload" ]; then
+  sid=$(printf '%s' "$payload" | python3 -c '
+import json,sys
+try:
+    d = json.load(sys.stdin)
+except Exception:
+    sys.exit(0)
+print(d.get("session_id") or "")
+' 2>/dev/null)
+fi
+if [ -n "$sid" ]; then
   d="$(git rev-parse --show-toplevel 2>/dev/null)/.agent-sync/sessions"
   if mkdir -p "$d" 2>/dev/null; then
-    printf '%s' "$CLAUDE_SESSION_ID" > "$d/$PPID" 2>/dev/null || true
+    printf '%s' "$sid" > "$d/$PPID" 2>/dev/null || true
     # forget the stamps of processes that are gone, so the directory cannot grow without bound
     for f in "$d"/*; do
       b="$(basename "$f")"

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