feat(sentry): add agent-lock mkdir-atomic advisory lock helper

Phase 1 of the sentry supervisor workflow. sentry needs two locks: a single-runner lock so overlapping /loop fires don't stack, and a roam-write lock so agent edits to the shared roam tree serialize. flock can't serve either, because every Bash call an agent makes is its own short-lived shell, so an flock dies with the call that took it.

agent-lock persists the lock on disk between calls. An atomic mkdir is the acquire. A metadata file inside records pid, host, ISO timestamp, and TTL. Staleness is age-based on the meta mtime, so a crashed holder's lock expires instead of wedging every later acquire, and every reclaim surfaces a note rather than clearing silently. refresh re-touches the mtime as a heartbeat, release is idempotent, status reports free/held/stale, path prints the resolved dir. Locks live under XDG_RUNTIME_DIR/agent-locks (tmpfs: host-local, out of every repo, cleared on reboot), with a ~/.cache fallback where no runtime dir exists.

Reclaim claims the stale dir with an atomic rename before removing it, so two acquirers that both see a lock stale can't both win. A plain remove-then-mkdir would let the loser delete the winner's fresh lock and double-acquire, defeating the roam-write lock's purpose.

Nothing calls it yet. 18 bats tests cover fresh win, contention, release, stale reclaim, heartbeat, path resolution, and usage errors.

1 files changed, 214 insertions, 0 deletions

diff --git a/.ai/scripts/tests/agent-lock.bats b/.ai/scripts/tests/agent-lock.bats
new file mode 100644
index 0000000..dbcffe1
--- /dev/null
+++ b/.ai/scripts/tests/agent-lock.bats
@@ -0,0 +1,214 @@
+#!/usr/bin/env bats
+#
+# Tests for claude-templates/.ai/scripts/agent-lock — a mkdir-atomic advisory
+# lock helper for agent workflows (sentry's single-runner and roam-write
+# locks). flock can't span an agent's tool calls: every Bash call is its own
+# short-lived shell, so a flock dies with the call that took it. This helper
+# persists the lock on disk between calls and self-clears after a crash via
+# age-based staleness reclaim.
+#
+# Contract under test:
+#   agent-lock acquire <name> [--ttl=SECONDS] [--wait[=SECONDS]]
+#     exit 0  → acquired (fresh, or reclaimed from a stale prior holder).
+#     exit 1  → busy: a live lock holds <name>; deferred (note on stderr).
+#     exit 2  → usage error (bad/absent name, unknown subcommand).
+#   agent-lock refresh <name>   → re-touch a held lock (heartbeat); exit 1 if absent.
+#   agent-lock release <name>   → remove the lock; idempotent (exit 0 if already free).
+#   agent-lock status  <name>   → print free|held|stale + metadata; exit 0 (query).
+#   agent-lock path    <name>   → print the resolved lock dir path; does not create it.
+#
+# Staleness is age-based on the metadata file's mtime versus the lock's own
+# recorded TTL, so a crashed holder's lock expires instead of wedging every
+# later acquire. Heartbeat (refresh) re-touches the mtime, keeping a live
+# holder's lock young. Every reclaim surfaces a note (never silent).
+#
+# Lock home: /run/user/<uid>/agent-locks/<name>/ (tmpfs: host-local, out of
+# every repo, cleared on reboot), with ~/.cache/agent-locks/ as the fallback
+# where no runtime dir exists. AGENT_LOCK_DIR overrides the base for tests and
+# advanced callers; the helper otherwise owns the path scheme and callers pass
+# only names.
+#
+# Strategy: AGENT_LOCK_DIR points every lock at a temp base, so tests never
+# touch a real runtime dir. Staleness is exercised by aging the metadata
+# file's mtime with `touch` rather than sleeping.
+
+SCRIPT="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)/agent-lock"
+BASH_BIN="$(command -v bash)"
+
+setup() {
+  TEST_DIR="$(mktemp -d -t agent-lock-bats.XXXXXX)"
+  LOCK_BASE="$TEST_DIR/locks"
+}
+
+teardown() {
+  rm -rf "$TEST_DIR"
+}
+
+lock() {
+  run env AGENT_LOCK_DIR="$LOCK_BASE" "$BASH_BIN" "$SCRIPT" "$@"
+}
+
+# meta-file path for a lock name, for direct inspection / aging.
+meta_of() {
+  printf '%s/%s/meta\n' "$LOCK_BASE" "$1"
+}
+
+# ---- acquire: fresh win + metadata --------------------------------------
+
+@test "acquire: fresh name wins (exit 0) and writes pid/host/timestamp/ttl" {
+  lock acquire job
+  [ "$status" -eq 0 ]
+  local meta; meta="$(meta_of job)"
+  [ -f "$meta" ]
+  grep -q "^pid=$$\|^pid=[0-9][0-9]*$" "$meta"
+  grep -q "^host=$(uname -n)$" "$meta"
+  grep -qE "^acquired=[0-9]{4}-[0-9]{2}-[0-9]{2}T" "$meta"
+  grep -qE "^ttl=[0-9]+$" "$meta"
+}
+
+@test "acquire: honors an explicit --ttl in the metadata" {
+  lock acquire job --ttl=45
+  [ "$status" -eq 0 ]
+  grep -q "^ttl=45$" "$(meta_of job)"
+}
+
+# ---- acquire: contention (one winner) -----------------------------------
+
+@test "acquire: a second acquire of a live lock defers (exit 1, note)" {
+  lock acquire job
+  [ "$status" -eq 0 ]
+  lock acquire job
+  [ "$status" -eq 1 ]
+  [[ "$output" == *job* ]]
+}
+
+@test "acquire: two racing acquires yield exactly one winner" {
+  # Fire both without releasing; exactly one mkdir wins.
+  env AGENT_LOCK_DIR="$LOCK_BASE" "$BASH_BIN" "$SCRIPT" acquire race & p1=$!
+  env AGENT_LOCK_DIR="$LOCK_BASE" "$BASH_BIN" "$SCRIPT" acquire race & p2=$!
+  local r1=0 r2=0
+  wait $p1 || r1=$?
+  wait $p2 || r2=$?
+  # One exits 0 (won), one exits 1 (deferred).
+  [ "$((r1 + r2))" -eq 1 ]
+}
+
+# ---- release: frees the lock --------------------------------------------
+
+@test "release: frees a held lock so the next acquire wins" {
+  lock acquire job
+  [ "$status" -eq 0 ]
+  lock release job
+  [ "$status" -eq 0 ]
+  [ ! -d "$LOCK_BASE/job" ]
+  lock acquire job
+  [ "$status" -eq 0 ]
+}
+
+@test "release: is idempotent on an already-free lock (exit 0)" {
+  lock release never-held
+  [ "$status" -eq 0 ]
+}
+
+# ---- staleness reclaim (surfaced, never silent) -------------------------
+
+@test "acquire: reclaims a stale lock and surfaces the reclaim note" {
+  lock acquire job --ttl=1
+  [ "$status" -eq 0 ]
+  # Age the metadata mtime well past the 1s TTL.
+  touch -d '1 hour ago' "$(meta_of job)"
+  lock acquire job --ttl=1
+  [ "$status" -eq 0 ]
+  [[ "$output" == *reclaim* ]]
+  [[ "$output" == *job* ]]
+  # The reclaim installed fresh metadata (young again), not the aged holder's.
+  lock status job
+  [[ "$output" == *held* ]]
+  [[ "$output" != *stale* ]]
+}
+
+@test "acquire: a lock inside its TTL is not stale (stays deferred)" {
+  lock acquire job --ttl=3600
+  [ "$status" -eq 0 ]
+  lock acquire job --ttl=3600
+  [ "$status" -eq 1 ]
+}
+
+# ---- heartbeat (refresh keeps a live lock young) ------------------------
+
+@test "refresh: re-touches a held lock so it is no longer stale" {
+  lock acquire job --ttl=1
+  [ "$status" -eq 0 ]
+  touch -d '1 hour ago' "$(meta_of job)"
+  lock status job
+  [[ "$output" == *stale* ]]
+  lock refresh job
+  [ "$status" -eq 0 ]
+  lock status job
+  [[ "$output" == *held* ]]
+  [[ "$output" != *stale* ]]
+}
+
+@test "refresh: an absent lock cannot be refreshed (exit 1)" {
+  lock refresh nothing
+  [ "$status" -eq 1 ]
+}
+
+# ---- status query -------------------------------------------------------
+
+@test "status: reports free for an unheld lock (exit 0)" {
+  lock status job
+  [ "$status" -eq 0 ]
+  [[ "$output" == *free* ]]
+}
+
+@test "status: reports held with metadata for a live lock" {
+  lock acquire job --ttl=3600
+  lock status job
+  [ "$status" -eq 0 ]
+  [[ "$output" == *held* ]]
+  [[ "$output" == *"host=$(uname -n)"* ]]
+}
+
+# ---- path resolution: runtime dir home with cache fallback --------------
+
+@test "path: resolves under AGENT_LOCK_DIR when set" {
+  lock path job
+  [ "$status" -eq 0 ]
+  [ "$output" = "$LOCK_BASE/job" ]
+  [ ! -d "$LOCK_BASE/job" ]  # path does not create the lock
+}
+
+@test "path: prefers the runtime dir home when no override is set" {
+  local rt="$TEST_DIR/run"
+  mkdir -p "$rt"
+  run env -u AGENT_LOCK_DIR XDG_RUNTIME_DIR="$rt" "$BASH_BIN" "$SCRIPT" path job
+  [ "$status" -eq 0 ]
+  [ "$output" = "$rt/agent-locks/job" ]
+}
+
+@test "path: falls back to the cache home when no runtime dir exists" {
+  local home="$TEST_DIR/home"
+  mkdir -p "$home"
+  run env -u AGENT_LOCK_DIR -u XDG_RUNTIME_DIR -u XDG_CACHE_HOME \
+    HOME="$home" "$BASH_BIN" "$SCRIPT" path job
+  [ "$status" -eq 0 ]
+  [ "$output" = "$home/.cache/agent-locks/job" ]
+}
+
+# ---- usage errors -------------------------------------------------------
+
+@test "usage: a missing name is a usage error (exit 2)" {
+  lock acquire
+  [ "$status" -eq 2 ]
+}
+
+@test "usage: a name with a slash is rejected (exit 2)" {
+  lock acquire bad/name
+  [ "$status" -eq 2 ]
+}
+
+@test "usage: an unknown subcommand is a usage error (exit 2)" {
+  lock frobnicate job
+  [ "$status" -eq 2 ]
+}