@ssheleg/agent-sync 1.20.2 → 1.21.0

package/CHANGELOG.md

@@ -1,3 +1,30 @@
+## v1.21.0 — the SessionEnd budget no host gave, and the watchdog that held the pipe
+
+Codex 0.157 prints `clamping SessionEnd hook timeout to 3s in …/agent-sync/…/hooks.json`
+at every session start. The hook declared 20 s; Codex clamps a SessionEnd handler to 3 s,
+and Claude Code sizes its own SessionEnd wait from the largest handler timeout. So the
+number was never honoured, and the loop behind it did not fit the budget it really had.
+
+- **`hooks.json` declares `timeout: 3`** for SessionEnd, and `check_hooks_manifest` refuses
+  anything larger, with a self-test plant of the exact 20 that shipped 0.1.0 → 1.20.2.
+- **`release --held`** gives back everything this run holds in ONE process. `session-end.sh`
+  used to run `whoami` plus one `release` per key, each with its own 10 s limit, so the host
+  killed it part-way and the tail of the list stayed out until its TTL. It now runs
+  `release --held` under a 2 s limit. The re-read of `held()` after each release is kept,
+  because a run's last task key takes its resource claims with it.
+- **`run_limited`'s fallback watchdog held the caller's pipe.** Stock macOS has neither
+  `timeout` nor `gtimeout`; the bash fallback was `( sleep N; kill ) &` with the caller's
+  stdout inherited, and `kill "$watchdog"` ended the subshell but not its `sleep`. The orphan
+  kept the pipe open, so `$(run_limited 10 …)` and `… | sed` waited the full limit after the
+  command had finished. That covered session-end, and SessionStart's `status` output too.
+  Measured 2026-09-27: session-end took 10.4 s to release three leases. It is a race, so a
+  trap-based stop still lost it now and then. The watchdog now polls `kill -0` in 0.1 s steps
+  with its stdio on `/dev/null`.
+
+Seven cases in `test/hooks_session_test.py` (13 total). The watchdog cases force the
+fallback with a PATH that carries no timeout binary, so a Linux runner exercises it too.
+They repeat the shape forty times, because a single draw of a race proves nothing.
+
 ## 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

package/package.json

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

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.2",
+  "version": "1.21.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/_lib.sh

@@ -24,9 +24,25 @@ run_limited() {
     return $?
   fi
 
+  # The watchdog POLLS in 0.1 s steps with its stdio on /dev/null, and nothing here
+  # depends on a signal reaching it in time. It used to be `( sleep N; kill ) &` with
+  # the caller's stdout inherited: `kill "$watchdog"` ended the subshell and not its
+  # `sleep`, and the orphan held the pipe, so `$(run_limited 10 …)` or `… | sed` waited
+  # the full limit after the command had finished. A trap-based stop still lost the
+  # race now and then (the TERM landing inside the fork), so the stop is now "the
+  # command is gone", seen within one step. session-end.sh spent 10.4 s releasing
+  # three leases the old way, against a SessionEnd budget of 3 s.
   "$@" &
   local pid=$!
-  ( sleep "$secs"; kill -TERM "$pid" 2>/dev/null ) &
+  (
+    n=$((secs * 10))
+    while [ "$n" -gt 0 ]; do
+      kill -0 "$pid" 2>/dev/null || exit 0
+      sleep 0.1
+      n=$((n - 1))
+    done
+    kill -TERM "$pid" 2>/dev/null
+  ) </dev/null >/dev/null 2>&1 &
   local watchdog=$!
   wait "$pid" 2>/dev/null
   local rc=$?

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

@@ -59,7 +59,7 @@
             "type": "command",
             "shell": "bash",
             "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/session-end.sh\"",
-            "timeout": 20
+            "timeout": 3
           }
         ]
       }

package/plugins/agent-sync/hooks/session-end.sh

@@ -1,14 +1,15 @@
 #!/usr/bin/env bash
 # Release every lease this run holds. An abandoned lease looks like active work
 # until its TTL expires.
+#
+# ONE process under a 2 s limit, inside the 3 s hooks.json declares. Codex clamps a
+# SessionEnd handler to 3 s and Claude Code sizes its SessionEnd wait from the largest
+# handler timeout, so 3 s is what either host actually gives. This used to be `whoami`
+# plus one `release` per key, each with its own 10 s limit — a loop the host killed
+# part-way, leaving the tail of the list out until its TTL.
 set -uo pipefail
 . "${CLAUDE_PLUGIN_ROOT}/hooks/_lib.sh"
 S="$AGENT_SYNC_PY"
 agent_sync_configured || exit 0
-held=$(run_limited 10 python3 "$S" whoami 2>/dev/null | sed -n 's/^holds: //p')
-[ -z "$held" ] || [ "$held" = "nothing" ] && exit 0
-IFS=', ' read -r -a keys <<<"$held"
-for k in "${keys[@]}"; do
-  [ -n "$k" ] && run_limited 10 python3 "$S" release "$k" >/dev/null 2>&1 || true
-done
+run_limited 2 python3 "$S" release --held >/dev/null 2>&1 || true
 exit 0

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.2"
+  version: "1.21.0"
   author: ssheleg
 ---
 
@@ -163,6 +163,7 @@ npx sshlg-skills install
 | `acquire <KEY>` | Take the lease on a task id. Prints `won` or `lost <holder>` |
 | `renew <KEY>` | Extend the lease. The `PostToolUse` hook does this for you |
 | `release <KEY>` | Give the lease back. Always do this, including on failure |
+| `release --held` | Give back everything this run holds, in one process — what SessionEnd runs |
 | `reserve <REG> [--key K] [--offline]` | Reserve the next id in a register (`DEC`, `OQ`, `DEP`, …); prints it. `--key` makes a retry idempotent (one key, one number); `--offline` issues a namespaced `REG-o-…` id with no global authority |
 | `map-offline <REG> <ID> <N>` | Bind an offline id to a properly reserved number — append-only, never rebound |
 | `release-id <REG> <ID>` | Return an id you did not end up writing to git |

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.2"
+VERSION = "1.21.0"
 
 CONFIG_PATH = Path(".claude/agent-sync.json")
 ENV_FILE = Path(".env.agent-sync")
@@ -4128,6 +4128,12 @@ def cmd_renew(args: argparse.Namespace) -> int:
 
 
 def cmd_release(args: argparse.Namespace) -> int:
+    if getattr(args, "held", False):
+        if args.key:
+            raise Fail("release takes a key OR --held, not both")
+        return _release_held()
+    if not args.key:
+        raise Fail("release needs a key, or --held for everything this run holds")
     # Exit non-zero when nothing was released. A caller that scripts `release` in a
     # cleanup path has no other way to learn the lease is still out there.
     if not Sync().release(args.key):
@@ -4137,6 +4143,33 @@ def cmd_release(args: argparse.Namespace) -> int:
     return 0
 
 
+def _release_held() -> int:
+    """Everything this run holds, in ONE process — the SessionEnd path.
+
+    The hook used to spend `whoami` plus one `release` process per key, each paying the
+    interpreter start and the config read again; under the 3 s both hosts give a SessionEnd
+    handler, the tail of the list stayed out until its TTL. `held()` is re-read after every
+    release because releasing a run's last task key releases its resource claims with it.
+    """
+    s = Sync()
+    released, refused = [], []
+    for _ in range(len(s.held()) + 1):
+        pending = [k for k in s.held() if k not in refused]
+        if not pending:
+            break
+        key = pending[0]
+        (released if s.release(key) else refused).append(key)
+    if not released and not refused:
+        print("released nothing — this run holds nothing")
+        return 0
+    if released:
+        print(f"released {', '.join(released)}")
+    if refused:
+        print(f"NOT released: {', '.join(refused)}", file=sys.stderr)
+        return 1
+    return 0
+
+
 def cmd_reserve(args: argparse.Namespace) -> int:
     s = Sync()
     if getattr(args, "offline", False):
@@ -5493,10 +5526,14 @@ def build_parser() -> argparse.ArgumentParser:
                     help="also render the configured git documents into the plane")
     bd.set_defaults(fn=cmd_board)
 
-    for name, fn, arg in (("acquire", cmd_acquire, "key"), ("release", cmd_release, "key")):
-        q = sub.add_parser(name)
-        q.add_argument(arg)
-        q.set_defaults(fn=fn)
+    q = sub.add_parser("acquire")
+    q.add_argument("key")
+    q.set_defaults(fn=cmd_acquire)
+    q = sub.add_parser("release", help="release a lease, or --held for all this run holds")
+    q.add_argument("key", nargs="?")
+    q.add_argument("--held", action="store_true",
+                   help="release every lease this run holds, in one process (SessionEnd)")
+    q.set_defaults(fn=cmd_release)
 
     r = sub.add_parser("renew")
     r.add_argument("key", nargs="?")