Files
gstack/bin/gstack-brain-lock.sh
T
Garry Tanandcapy-ai[bot] bcece3fbcd Make gstack's shell locks hold when mkdir reports a race it lost (GST-2247) (#4262)
* Make gstack's shell locks hold when mkdir reports a race it lost (GST-2247)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* Fix lock tests and fixtures for gstack_lock_take; trim setup-gbrain lock prose

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* Ship the lock helper with every copied runtime and fixture that runs a lock

The Claude Code wrapper's copied runtime now includes bin/gstack-lock.sh, and
bin/gstack-render-claude.sh sources it beside itself, so gstack-config set
works in a copied runtime and the render lock is taken by every caller.
Test fixtures that copy single bin scripts now copy the helper too, and the
mkdir lock guard is registered as a repo-wide docs reader.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* Release a lock whose owner file could not be fully written

gstack_lock_take created the owner file with a noclobber redirect and, when
that redirect failed, treated an existing file as a competing holder. If the
file was created but the write then failed (disk full, quota, ulimit -f), the
helper found its own empty file, returned 1 and left a lock nobody held;
freeze's state lock has no stale recovery, so it stayed busy until removed by
hand. The helper now tells "opened but write failed" from "already held",
removes its own file and directory, and returns 3. The inline copy in
gstack-ff-update is updated byte for byte, and a new test under ulimit -f 0
fails on the old helper.

Review-Finding: s11/outside-voice#1 reader=outside-voice
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* Describe the lease lock as gstack_lock_take's O_EXCL owner file

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

---------

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
2026-11-17 09:05:25 +00:00

93 lines
3.8 KiB
Bash

# gstack-brain-lock.sh — the one drain lock for every gstack writer to the
# artifacts repo's git state in $GSTACK_HOME.
#
# This file is NOT executable; source it:
#
# . "$(dirname "$0")/gstack-brain-lock.sh"
#
# Writers that take it: the drain (gstack-brain-sync --once), the skill-start
# merge (gstack-skill-start), gstack-artifacts-init, gstack-brain-restore and
# gstack-gbrain-source-wireup. Holding it is what lets the drain treat an old
# .git/index.lock as abandoned: no other gstack writer can be running git there.
#
# Provides:
# gstack_brain_lock_acquire <gstack_home> <try|wait>
# Returns 0 when this process holds the lock afterwards, 1 otherwise.
# try — give up at once when a live process holds it.
# wait — retry once a second for GSTACK_BRAIN_LOCK_WAIT seconds (default
# 120), then give up.
# A child of the holder (the drain runs the wireup's daily advance; restore
# runs the wireup) inherits GSTACK_BRAIN_LOCK_TOKEN; when it matches the
# lock's owner file the child proceeds without taking or releasing it.
# On failure, _GSTACK_BRAIN_LOCK_HOLDER names the holder's pid (or "").
# gstack_brain_lock_release
# Removes the lock only when this process took it and still owns it.
#
# The lock is a directory holding `pid` and `owner`, taken with
# gstack_lock_take (bin/gstack-lock.sh), which creates `pid` with O_EXCL:
# mkdir's exit status is not a lock on Ubuntu 26.04's uutils mkdir, and
# flock(1) is not on macOS. A lock whose pid is dead is stale and is cleared.
# A lock directory with no pid file is a holder killed between mkdir and the
# pid write once it is older than 10 minutes.
. "$(dirname "${BASH_SOURCE[0]}")/gstack-lock.sh" 2>/dev/null || gstack_lock_take() { echo "gstack: $(dirname "${BASH_SOURCE[0]}")/gstack-lock.sh is missing; reinstall with ./setup" >&2; return 2; }
_GSTACK_BRAIN_LOCK_DIR=""
_GSTACK_BRAIN_LOCK_MINE=0
_GSTACK_BRAIN_LOCK_HOLDER=""
_gstack_brain_lock_try_once() {
local dir="$1" pid
if gstack_lock_take "$dir" pid "$$"; then
GSTACK_BRAIN_LOCK_TOKEN="$$-${RANDOM:-0}-$(date +%s 2>/dev/null || echo 0)"
export GSTACK_BRAIN_LOCK_TOKEN
printf '%s\n' "$GSTACK_BRAIN_LOCK_TOKEN" > "$dir/owner" 2>/dev/null || true
_GSTACK_BRAIN_LOCK_MINE=1
return 0
fi
if [ -f "$dir/pid" ]; then
pid=$(head -1 "$dir/pid" 2>/dev/null || echo "")
_GSTACK_BRAIN_LOCK_HOLDER="$pid"
case "$pid" in ''|*[!0-9]*) return 1 ;; esac
kill -0 "$pid" 2>/dev/null && return 1
elif [ -z "$(find "$dir" -maxdepth 0 -mmin +10 2>/dev/null)" ]; then
_GSTACK_BRAIN_LOCK_HOLDER=""
return 1
fi
rm -rf "$dir" 2>/dev/null || true
return 1
}
gstack_brain_lock_acquire() {
local home="$1" mode="${2:-try}" waited=0 limit
_GSTACK_BRAIN_LOCK_DIR="$home/.brain-sync.lock.d"
_GSTACK_BRAIN_LOCK_MINE=0
_GSTACK_BRAIN_LOCK_HOLDER=""
if [ -n "${GSTACK_BRAIN_LOCK_TOKEN:-}" ] && [ -f "$_GSTACK_BRAIN_LOCK_DIR/owner" ] \
&& [ "$(head -1 "$_GSTACK_BRAIN_LOCK_DIR/owner" 2>/dev/null)" = "$GSTACK_BRAIN_LOCK_TOKEN" ]; then
return 0
fi
mkdir -p "$home" 2>/dev/null || true
limit="${GSTACK_BRAIN_LOCK_WAIT:-120}"
case "$limit" in ''|*[!0-9]*) limit=120 ;; esac
while :; do
_gstack_brain_lock_try_once "$_GSTACK_BRAIN_LOCK_DIR" && return 0
# A stale lock was just cleared: take it now instead of after a sleep.
[ -d "$_GSTACK_BRAIN_LOCK_DIR" ] || { _gstack_brain_lock_try_once "$_GSTACK_BRAIN_LOCK_DIR" && return 0; }
[ "$mode" = "wait" ] || return 1
[ "$waited" -ge "$limit" ] && return 1
sleep 1
waited=$(( waited + 1 ))
done
}
gstack_brain_lock_release() {
[ "$_GSTACK_BRAIN_LOCK_MINE" = "1" ] || return 0
if [ "$(head -1 "$_GSTACK_BRAIN_LOCK_DIR/owner" 2>/dev/null)" = "${GSTACK_BRAIN_LOCK_TOKEN:-}" ]; then
rm -rf "$_GSTACK_BRAIN_LOCK_DIR" 2>/dev/null || true
fi
_GSTACK_BRAIN_LOCK_MINE=0
unset GSTACK_BRAIN_LOCK_TOKEN
return 0
}