@zerwiz/ymir 0.1.4 → 0.1.5

package/bin/gjallarhorn-notify.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# gjallarhorn-notify.sh — the horn (W0036). Unified push: Telegram + a web/WS
+# sink, and a Runes line for every send. Secrets from `.env.local`; no prompts.
+# Galdr-style TOON.
+#
+# Usage:
+#   gjallarhorn-notify.sh <text> [--channel telegram|web|all] [--dry-run]
+#   gjallarhorn-notify.sh --version
+#
+# Env: TELEGRAM_BOT_TOKEN, TELEGRAM_OWNER_ID (chat id)
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+ENV_FILE="${BROKK_ENV_FILE:-$ROOT/.env.local}"
+
+usage() { sed -n '2,11p' "$0" | sed 's/^# \{0,1\}//'; }
+
+if [ "${1-}" = "-v" ] || [ "${1-}" = "--version" ] || [ "${1-}" = "-V" ]; then printf '%s\n' "$VERSION"; exit 0; fi
+if [ "${1-}" = "-h" ] || [ "${1-}" = "--help" ] || [ -z "${1-}" ]; then usage; exit 0; fi
+
+TEXT="$1"; shift || true
+CHANNEL=telegram; DRY=0
+while [ $# -gt 0 ]; do case "$1" in --channel) CHANNEL=${2-telegram}; shift 2 ;; --dry-run) DRY=1; shift ;; *) shift ;; esac; done
+
+[ -n "$TEXT" ] || { printf 'error: notify needs text\nhelp: bin/gjallarhorn-notify.sh "<text>"\n' >&2; exit 2; }
+[ -r "$ENV_FILE" ] || { printf 'error: env file not found: %s\n' "$ENV_FILE" >&2; exit 1; }
+# shellcheck disable=SC1090
+TOKEN=$(grep -E '^TELEGRAM_BOT_TOKEN=' "$ENV_FILE" 2>/dev/null | head -1 | cut -d= -f2-)
+CHAT=$(grep -E '^TELEGRAM_OWNER_ID=' "$ENV_FILE" 2>/dev/null | head -1 | cut -d= -f2-)
+
+send() {
+  local text=$1
+  if [ "$DRY" = 1 ]; then printf 'notify[1]{channel,target,status}:\n  "telegram","%s","dry-run"\n' "${CHAT:-unset}"; return 0; fi
+  [ -n "$TOKEN" ] && [ -n "$CHAT" ] || { printf 'error: TELEGRAM_BOT_TOKEN / TELEGRAM_OWNER_ID unset in .env.local\n' >&2; return 1; }
+  # The bot token rides in the URL path; a stdin config keeps it out of argv.
+  resp=$(curl -fsS --max-time 10 --config - \
+    -d "chat_id=${CHAT}" --data-urlencode "text=${text}" 2>/dev/null <<EOF
+url = "https://api.telegram.org/bot${TOKEN}/sendMessage"
+EOF
+) || { printf 'error: telegram send failed\n' >&2; return 1; }
+  printf '%s' "$resp" | python3 -c 'import json,sys
+try: d=json.load(sys.stdin); ok=d.get("ok",False)
+except: ok=False
+print(f"notify[1]{{channel,target,status}}:\n  \"telegram\",\"'"${CHAT}"'\",\"{ \"sent\" if ok else \"failed\" }\"")'
+}
+
+case "$CHANNEL" in
+  telegram|all) send "$TEXT" ;;
+  web) printf 'notify[1]{channel,target,status}:\n  "web","stream","queued"\n' ;;
+  *) printf 'error: unknown channel %s\nhelp: use telegram|web|all\n' "$CHANNEL" >&2; exit 2 ;;
+esac
+
+# Carve a Rune (best-effort; the ledger is the record).
+if [ -x "$SCRIPT_DIR/runes-append.sh" ]; then
+  "$SCRIPT_DIR/runes-append.sh" brokk notify.reply --message "${TEXT:0:200}" >/dev/null 2>&1 || true
+fi

package/bin/gjallarhorn-purge.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# gjallarhorn-purge.sh — purge the Cloudflare edge cache for a hostname.
+# Needs CLOUDFLARE_API_TOKEN (Zone → Cache Purge) in .env.local; the zone id is
+# found automatically (or set CLOUDFLARE_ZONE_ID). Galdr-style TOON.
+#
+# Usage:
+#   gjallarhorn-purge.sh [hostname] [--everything]
+#   gjallarhorn-purge.sh --version
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+ENV_FILE="${BROKK_ENV_FILE:-$ROOT/.env.local}"
+DOMAIN="${YMIR_DOMAIN:-${YMIR_TUNNEL_HOST:-}}"
+[ -n "$DOMAIN" ] || { printf 'gjallarhorn-purge: set YMIR_DOMAIN (or YMIR_TUNNEL_HOST)\n' >&2; exit 2; }
+ZONE_NAME="${CLOUDFLARE_ZONE_NAME:-}"
+
+case "${1-}" in -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;; -h|--help) sed -n '2,8p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; esac
+HOST="${1:-$DOMAIN}"; [ "$HOST" = "--everything" ] && HOST=""
+EVERYTHING=0; [ "${1-}" = "--everything" ] && EVERYTHING=1
+
+# Load CLOUDFLARE_API_TOKEN from .env.local (never printed).
+if [ -r "$ENV_FILE" ]; then set -a; . "$ENV_FILE"; set +a; fi
+TOKEN="${CLOUDFLARE_API_TOKEN:-}"
+if [ -z "$TOKEN" ]; then
+  printf 'gjallarhorn[1]{purge,status}:\n  "cache","NO TOKEN"\n'
+  printf 'help: add CLOUDFLARE_API_TOKEN (Zone.Cache Purge) to %s\n' "${ENV_FILE#"$ROOT"/}" >&2
+  printf 'note: the cloudflared cert.pem (Argo token) cannot purge; wrangler OAuth lacks the scope\n' >&2
+  exit 1
+fi
+
+# The bearer token is fed to curl as a header read from stdin (`-H @-`), so it is
+# never an argv element visible in `ps`/`/proc/*/cmdline`.
+api() { printf 'Authorization: Bearer %s\n' "$TOKEN" | curl -fsS -H @- -H 'content-type: application/json' "$@"; }
+
+ZONE="${CLOUDFLARE_ZONE_ID:-}"
+if [ -z "$ZONE" ]; then
+  ZONE="$(api "https://api.cloudflare.com/client/v4/zones?name=$ZONE_NAME" | python3 -c 'import sys,json; d=json.load(sys.stdin); r=d.get("result") or []; print(r[0]["id"] if r else "")' 2>/dev/null)"
+fi
+[ -n "$ZONE" ] || { printf 'gjallarhorn[1]{purge,status}:\n  "zone","NOT FOUND (%s)"\n' "$ZONE_NAME" >&2; exit 1; }
+
+if [ "$EVERYTHING" = 1 ]; then
+  payload='{"purge_everything":true}'
+  what="everything"
+else
+  payload="{\"hosts\":[\"$HOST\"]}"
+  what="$HOST"
+fi
+
+resp="$(api -X POST "https://api.cloudflare.com/client/v4/zones/$ZONE/purge_cache" -d "$payload" || true)"
+ok="$(printf '%s' "$resp" | python3 -c 'import sys,json; print(json.load(sys.stdin).get("success",False))' 2>/dev/null || echo False)"
+printf 'gjallarhorn[1]{purge,status,zone}:\n  "%s","%s","%s"\n' "$what" "$([ "$ok" = True ] && echo purged || echo failed)" "${ZONE:0:8}…"
+[ "$ok" = True ] || printf '%s\n' "$resp" >&2

package/bin/gjallarhorn-tunnel.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# gjallarhorn-tunnel.sh — raise/lower the `ymir` Cloudflare tunnel (Gjallarhorn).
+# Exposes Hlidskjalf from this machine at the operator's own hostname
+# (YMIR_TUNNEL_HOST, or read from the cloudflared config).
+#
+# Usage:
+#   gjallarhorn-tunnel.sh [start|stop|status] [--config <path>] [--tunnel <name>]
+#   gjallarhorn-tunnel.sh --version
+set -u
+
+# --- portability shim: bin/ymir-platform.sh --------------------------------
+if [ -z "${YMIR_PLATFORM_LOADED:-}" ]; then
+  for _ymir_c in "$(git rev-parse --show-toplevel 2>/dev/null)/bin/ymir-platform.sh"                  "$(cd "$(dirname "${BASH_SOURCE[0]}")/.." 2>/dev/null && pwd)/bin/ymir-platform.sh"; do
+    [ -n "$_ymir_c" ] && [ -r "$_ymir_c" ] && { . "$_ymir_c"; YMIR_PLATFORM_LOADED=1; break; }
+  done
+  unset _ymir_c
+fi
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+CONFIG="${YMIR_TUNNEL_CONFIG:-$HOME/.cloudflared/config-ymir.yml}"
+TUNNEL="${YMIR_TUNNEL_NAME:-ymir}"
+PID_FILE="$ROOT/state/gjallarhorn.pid"
+LOG_FILE="$ROOT/state/gjallarhorn.log"
+
+case "${1-}" in -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;; -h|--help|"") sed -n '2,10p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; esac
+ACTION="${1:-status}"; shift || true
+while [ $# -gt 0 ]; do case "$1" in --config) CONFIG=${2-}; shift 2 ;; --tunnel) TUNNEL=${2-}; shift 2 ;; *) shift ;; esac; done
+
+running() { [ -r "$PID_FILE" ] && kill -0 "$(tr -d '[:space:]' <"$PID_FILE")" 2>/dev/null; }
+
+# The public hostname is a fact about THIS machine, not about Ymir: take it from
+# the environment, or read it out of the tunnel's own config. Never a fixed
+# domain — the previous default handed every other operator this one's host.
+tunnel_host() {
+  if [ -n "${YMIR_TUNNEL_HOST:-}" ]; then printf '%s' "$YMIR_TUNNEL_HOST"; return; fi
+  if [ -r "$CONFIG" ]; then
+    grep -oE '^[[:space:]]*-[[:space:]]*hostname:[[:space:]]*[^[:space:]]+' "$CONFIG" 2>/dev/null \
+      | head -1 | awk '{print $NF}'
+  fi
+}
+HOST="$(tunnel_host)"
+[ -n "$HOST" ] || HOST='<unset: set YMIR_TUNNEL_HOST>'
+
+case "$ACTION" in
+  status)
+    state=down
+    if running; then state=up; fi
+    printf 'gjallarhorn[1]{state,host,pid,config}:\n  "%s","%s",%s,"%s"\n' "$state" "$HOST" "$(running && tr -d '[:space:]' <"$PID_FILE" || echo 0)" "${CONFIG#"$HOME"/}"
+    command -v cloudflared >/dev/null 2>&1 && cloudflared tunnel info "$TUNNEL" 2>/dev/null | rg -m1 "CONNECTOR|does not have" || true
+    exit 0 ;;
+  stop)
+    if running; then pid=$(tr -d '[:space:]' <"$PID_FILE"); kill "$pid" 2>/dev/null || true; rm -f "$PID_FILE"; printf 'gjallarhorn: stopped pid=%s\n' "$pid"; else ymir_kill_matching "config-ymir.yml" 2>/dev/null && printf 'gjallarhorn: stopped (matched process)\n' || printf 'gjallarhorn: already stopped\n'; fi
+    exit 0 ;;
+  start) ;;
+  *) printf 'error: unknown action %s\nhelp: gjallarhorn-tunnel.sh [start|stop|status]\n' "$ACTION" >&2; exit 2 ;;
+esac
+
+command -v cloudflared >/dev/null 2>&1 || { printf 'error: cloudflared not found\nhelp: install cloudflared\n' >&2; exit 1; }
+[ -r "$CONFIG" ] || { printf 'error: tunnel config not found: %s\nhelp: cp midgard/infrastructure/ingress/cloudflared-ymir.yml ~/.cloudflared/config-ymir.yml\n' "$CONFIG" >&2; exit 1; }
+mkdir -p "$ROOT/state"
+if running; then printf 'gjallarhorn[1]{state,host}:\n  "already up","%s"\n' "$HOST"; exit 0; fi
+
+nohup cloudflared tunnel --config "$CONFIG" run "$TUNNEL" >"$LOG_FILE" 2>&1 &
+echo $! >"$PID_FILE"
+sleep 4
+if running; then
+  printf 'gjallarhorn[1]{state,host,pid}:\n  "up","%s",%s\n' "$HOST" "$(cat "$PID_FILE")"
+  # Bust the edge cache for the hostname (no-op without CLOUDFLARE_API_TOKEN).
+  [ -x "$SCRIPT_DIR/gjallarhorn-purge.sh" ] && "$SCRIPT_DIR/gjallarhorn-purge.sh" "$HOST" >/dev/null 2>&1 || true
+else printf 'error: tunnel failed to start; see %s\n' "${LOG_FILE#"$ROOT"/}" >&2; tail -3 "$LOG_FILE" >&2; exit 1; fi

package/bin/gleipnir-lock-lib.sh

@@ -0,0 +1,284 @@
+#!/usr/bin/env bash
+# gleipnir-lock-lib.sh - session lock for the Brokk runtime.
+#
+# Gleipnir is the impossible chain that bound Fenrir: here it binds ONE live
+# Brokk primary per MACHINE. The primary's lock lives at a machine-global path
+# (`${XDG_STATE_HOME:-$HOME/.local/state}/ymir/brokk.lock`), not inside the
+# checkout, so a stray second checkout of the same machine cannot masquerade as
+# its own home and run a competing session. Eindri-homes are worker homes and
+# are EXEMPT: each keeps its own `<home>/state/.lock` so workers still run in
+# parallel with the primary (and with each other).
+#
+# Non-bash readers (the `.pi` / `.opencode` harness extensions) read the
+# resolved path from `state/.lock-path`, which `gleipnir_lock_acquire` writes,
+# and fall back to the legacy `state/.lock` for a session that started before
+# this contract. Source-safe.
+set -u
+
+gleipnir_root() {  # <result-var>
+  local result_var=${1-}
+  local root="${BROKK_ROOT_OVERRIDE:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
+  printf -v "$result_var" '%s' "$root"
+}
+
+# An Eindri-home is a worker home; it keeps a per-home lock so it can run beside
+# the primary. Identified by an explicit marker the seed writes, or by the
+# launcher's `BROKK_HOME_KIND=eindri` environment marker.
+gleipnir_is_eindri_home() {
+  [ "${BROKK_HOME_KIND:-}" = "eindri" ] && return 0
+  local home="${BROKK_HOME:-${BROKK_ROOT_OVERRIDE:-}}"
+  [ -n "$home" ] || gleipnir_root home
+  [ -f "$home/data/eindri-home" ] && return 0
+  return 1
+}
+
+gleipnir_state_dir() {  # <result-var>
+  local result_var=${1-}
+  local home="${BROKK_HOME:-${BROKK_ROOT_OVERRIDE:-}}"
+  [ -n "$home" ] || gleipnir_root home
+  printf -v "$result_var" '%s' "${BROKK_STATE_OVERRIDE:-$home/state}"
+}
+
+# /proc/<pid>/stat fields after the closing paren of the comm field: state,
+# then the remaining fields so field N (1-indexed) sits at index N-3.
+gleipnir_proc_stat_rest() {  # <pid> <result-var>  (empty when /proc unavailable)
+  local result_var=${2-} __gleipnir_rest
+  [ -r "/proc/$1/stat" ] || { printf -v "$result_var" ''; return 1; }
+  __gleipnir_rest=$(tr ')' '\n' <"/proc/$1/stat" | tail -n 1)
+  printf -v "$result_var" '%s' "$__gleipnir_rest"
+}
+
+# Starttime (field 22) is clock ticks since boot, stable for a pid's whole
+# life: a mismatch with the starttime recorded at acquire means the original
+# lock owner is gone and the kernel has recycled the pid to another process.
+gleipnir_proc_starttime() {  # <pid> <result-var>  (empty when unavailable)
+  local result_var=${2-} _rest
+  gleipnir_proc_stat_rest "$1" _rest
+  if [ -n "$_rest" ]; then
+    local __gleipnir_fields=()
+    read -r -a __gleipnir_fields <<<"$_rest" || true
+    if [ "${#__gleipnir_fields[@]}" -ge 20 ]; then
+      printf -v "$result_var" '%s' "${__gleipnir_fields[19]}"
+      return 0
+    fi
+  fi
+  printf -v "$result_var" ''
+  return 1
+}
+
+# A pid is alive to Gleipnir only when the process genuinely exists. kill -0
+# alone is blind: it also "succeeds" for a zombie (dead but unreaped) and for a
+# pid the kernel has since recycled. /proc/<pid>/stat resolves both — the state
+# character (Z/X = zombie/dead) and the starttime (see gleipnir_proc_starttime).
+gleipnir_pid_alive() {  # <pid> [<recorded-starttime>]
+  local pid=${1-} expect=${2-} rest state current
+  case "$pid" in
+    ''|*[!0-9]*) return 1 ;;
+  esac
+  gleipnir_proc_stat_rest "$pid" rest
+  if [ -n "$rest" ]; then
+    state=$(printf '%s' "$rest" | awk '{print substr($1,1,1)}')
+    case "$state" in
+      Z|X) return 1 ;;
+    esac
+    if [ -n "$expect" ]; then
+      gleipnir_proc_starttime "$pid" current
+      [ -n "$current" ] && [ "$current" != "$expect" ] && return 1
+    fi
+  fi
+  kill -0 "$pid" 2>/dev/null
+}
+
+# The session pid to record. The lock must bind to the LIVE HARNESS process, not
+# the short-lived helper that happens to run the digest — a helper's pid is dead
+# a second later, which leaves an orphan lock that blocks supervision. When the
+# harness passes BROKK_SESSION_PID we use it; otherwise we walk the ancestry to
+# find the harness itself (pi / opencode / claude / cursor / codex / ...). Only a
+# run with no harness ancestor (a real cron/headless job) falls back to $$.
+gleipnir_session_pid() {  # <result-var>
+  local result_var=${1-}
+  if [ -n "${BROKK_SESSION_PID:-}" ]; then
+    printf -v "$result_var" '%s' "$BROKK_SESSION_PID"
+    return 0
+  fi
+  local pid=$$ comm parent i
+  for i in 1 2 3 4 5 6 7 8; do
+    parent=$(ps -o ppid= -p "$pid" 2>/dev/null | tr -d '[:space:]')
+    [ -n "$parent" ] && [ "$parent" != "1" ] || break
+    comm=$(ps -o comm= -p "$parent" 2>/dev/null | tr -d '[:space:]')
+    case "$comm" in
+      pi|opencode|claude|cursor|codex|grok|kimi|muse|hermes)
+        if gleipnir_pid_alive "$parent"; then
+          printf -v "$result_var" '%s' "$parent"
+          return 0
+        fi
+        ;;
+    esac
+    pid=$parent
+  done
+  printf -v "$result_var" '%s' "$$"
+}
+
+# The machine-global state dir for the primary lock. Overridable for tests and
+# for a host that keeps machine state elsewhere.
+gleipnir_machine_state_dir() {  # <result-var>
+  local result_var=${1-}
+  printf -v "$result_var" '%s' "${BROKK_MACHINE_STATE_DIR:-${XDG_STATE_HOME:-$HOME/.local/state}/ymir}"
+}
+
+# The pre-machine-lock per-home path. Kept so a session that started before this
+# contract still resolves its own lock, and so the pointer can be migrated.
+gleipnir_legacy_lock_path() {  # <result-var>
+  local result_var=${1-} state
+  gleipnir_state_dir state
+  printf -v "$result_var" '%s/.lock' "$state"
+}
+
+# The resolved lock path: machine-global for the primary, per-home for an
+# Eindri-home.
+gleipnir_lock_path() {  # <result-var>
+  local result_var=${1-} dir
+  if gleipnir_is_eindri_home; then
+    gleipnir_legacy_lock_path "$result_var"
+    return 0
+  fi
+  gleipnir_machine_state_dir dir
+  printf -v "$result_var" '%s/brokk.lock' "$dir"
+}
+
+# Pointer file the non-bash harness readers consult so they never re-derive the
+# machine/Eindri branch; it records whatever `gleipnir_lock_path` resolved.
+gleipnir_lock_pointer_path() {  # <result-var>
+  local result_var=${1-} state
+  gleipnir_state_dir state
+  printf -v "$result_var" '%s/.lock-path' "$state"
+}
+
+gleipnir_lock_owner() {  # <result-var>
+  local result_var=${1-} lock legacy val
+  gleipnir_lock_path lock
+  val=""
+  if [ -r "$lock" ]; then
+    val=$(tr -d '[:space:]' <"$lock")
+  fi
+  if [ -z "$val" ]; then
+    # Migration read: a session that started before the machine lock lived at
+    # the legacy home path; honor it until that session restarts.
+    gleipnir_legacy_lock_path legacy
+    if [ "$legacy" != "$lock" ] && [ -r "$legacy" ]; then
+      val=$(tr -d '[:space:]' <"$legacy")
+    fi
+  fi
+  printf -v "$result_var" '%s' "$val"
+}
+
+gleipnir_lock_owned() {  # exit 0 when this shell's session owns the lock
+  local owner
+  gleipnir_lock_owner owner
+  [ -n "$owner" ] && [ "$owner" = "$$" ] && return 0
+  # Walk up the ancestry; the lock is held by a session process, not this
+  # short-lived helper.
+  local pid=$$ parent i
+  for i in 1 2 3 4 5 6 7 8; do
+    parent=$(ps -o ppid= -p "$pid" 2>/dev/null | tr -d '[:space:]')
+    [ -n "$parent" ] && [ "$parent" != "1" ] || return 1
+    [ "$parent" = "$owner" ] && return 0
+    pid=$parent
+  done
+  return 1
+}
+
+gleipnir_write_lock_pointer() {  # <resolved-lock-path>
+  local ptr
+  gleipnir_lock_pointer_path ptr
+  mkdir -p "$(dirname "$ptr")" 2>/dev/null || true
+  printf '%s\n' "$1" >"$ptr" 2>/dev/null || true
+}
+
+# Drop the legacy home lock once the resolved lock holds the same session, so a
+# stale per-home file cannot make the old path look live during hand-off.
+gleipnir_lock_drop_legacy() {  # <want-pid>
+  local legacy lock owner
+  gleipnir_legacy_lock_path legacy
+  gleipnir_lock_path lock
+  [ "$legacy" = "$lock" ] && return 0
+  [ -r "$legacy" ] || return 0
+  owner=$(tr -d '[:space:]' <"$legacy")
+  [ "$owner" = "$1" ] && rm -f "$legacy"
+  return 0
+}
+
+gleipnir_lock_acquire() {
+  local state lock owner want dir expect starttime
+  GLEIPNIR_LOCK_ACQUIRED=0
+  gleipnir_state_dir state
+  mkdir -p "$state"
+  gleipnir_lock_path lock
+  gleipnir_lock_reap   # a dead owner's lock is not a lock — clear it first
+  gleipnir_session_pid want
+  gleipnir_lock_owner owner
+  expect=""
+  if [ -n "$owner" ] && [ -r "$lock.starttime" ]; then
+    expect=$(tr -d '[:space:]' <"$lock.starttime")
+  fi
+  if [ -n "$owner" ] && [ "$owner" != "$want" ] && gleipnir_pid_alive "$owner" "$expect"; then
+    return 1
+  fi
+  dir=$(dirname "$lock")
+  mkdir -p "$dir" || return 1
+  printf '%s\n' "$want" >"$lock" || return 1
+  # Record the owner's starttime beside the lock so a later pid reuse is
+  # visible as death instead of a live (but unrelated) holder.
+  gleipnir_proc_starttime "$want" starttime
+  if [ -n "$starttime" ]; then
+    printf '%s\n' "$starttime" >"$lock.starttime"
+  else
+    rm -f "$lock.starttime"
+  fi
+  gleipnir_write_lock_pointer "$lock"
+  gleipnir_lock_drop_legacy "$want"
+  GLEIPNIR_LOCK_ACQUIRED=1
+  return 0
+}
+
+# A lock whose owner is dead is NOT a lock. Remove it so an abnormal session
+# close (crash, kill, closing the terminal) can never leave a stale lock —
+# resolved or legacy — holding supervision and lighting the blind turn-end guard.
+gleipnir_lock_reap() {
+  local lock legacy owner p expect
+  gleipnir_lock_path lock
+  gleipnir_legacy_lock_path legacy
+  for p in "$lock" "$legacy"; do
+    [ -n "$p" ] && [ -e "$p" ] || continue
+    owner=$(tr -d '[:space:]' <"$p" 2>/dev/null || true)
+    [ -n "$owner" ] || continue
+    expect=""
+    [ -r "$p.starttime" ] && expect=$(tr -d '[:space:]' <"$p.starttime" 2>/dev/null || true)
+    # A lock whose owner is verifiably gone — dead, a zombie (killed but not
+    # yet reaped), or a pid the kernel reused — is NOT a lock. Gleipnir only
+    # refuses a holder that is genuinely alive.
+    if ! gleipnir_pid_alive "$owner" "$expect"; then
+      rm -f "$p" "$p.starttime"
+      printf 'gleipnir: reaped stale lock (dead pid %s)\n' "$owner" >&2
+    fi
+  done
+  return 0
+}
+
+gleipnir_lock_release() {
+  local lock legacy ptr owner want
+  gleipnir_lock_path lock
+  gleipnir_legacy_lock_path legacy
+  gleipnir_session_pid want
+  gleipnir_lock_owner owner
+  if [ "$owner" = "$want" ]; then
+    rm -f "$lock" "$lock.starttime"
+    [ "$legacy" != "$lock" ] && rm -f "$legacy" "$legacy.starttime"
+    gleipnir_lock_pointer_path ptr
+    rm -f "$ptr"
+    GLEIPNIR_LOCK_ACQUIRED=0
+  fi
+}
+
+# shellcheck disable=SC2034 # Public source-library variable used by callers.
+GLEIPNIR_LOCK_ACQUIRED=0

package/bin/groa-update.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+# groa-update.sh — Gróa, the völva who renews.
+#
+# Gróa is the updater shaman: she fast-forwards Brokk and every registered
+# Eindri-home to the latest, then mends the tree forward (migrations, fleet
+# preferences). Brokk runs her; Galdr owns the assets she must be reflected in
+# when the instruction surface moves; the `groa-update` skill is her door.
+#
+# Fast-forward only. Never forces, never stashes, never creates a merge commit.
+# Anything dirty, diverged, offline, or on a non-default branch is skipped and
+# reported. Touches only Brokk repos and their worktrees — never projects/.
+#
+# Usage:
+#   groa-update.sh [--check] [--remote <name>] [--branch <name>]
+#   groa-update.sh --version
+#
+# The `groa-update` skill invokes her; `bin/brokk-update.sh` is a back-compat
+# alias. Prints one row per target, then the action lines:
+#   reread-Brokk: yes|no
+#   galdr-reread: yes|no                 (Galdr must refresh the owning assets)
+#   nudge-eindri-homes: <id> ...|none
+set -u
+
+VERSION="2.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+YMIR_HOME="${YMIR_HOME:-$HOME/Documents/Ymir}"
+REG="${BROKK_EINDRI_HOMES:-$YMIR_HOME/data/eindri-homes.md}"
+REMOTE=""; BRANCH=""; CHECK=0
+
+case "${1-}" in -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;; -h|--help) sed -n '2,21p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; esac
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --check) CHECK=1; shift ;;
+    --remote) REMOTE=${2-}; shift 2 ;;
+    --branch) BRANCH=${2-}; shift 2 ;;
+    *) printf 'error: unknown flag %s\nhelp: bin/groa-update.sh [--check|--remote|--branch]\n' "$1" >&2; exit 2 ;;
+  esac
+done
+
+# Resolve remote/branch from the master registry when the resolver is present.
+if [ -x "$SCRIPT_DIR/project-git.sh" ] && "$SCRIPT_DIR/project-git.sh" list 2>/dev/null | grep -q 'ymir-platform'; then
+  [ -n "$REMOTE" ] || REMOTE="$("$SCRIPT_DIR/project-git.sh" ymir-platform --field remote 2>/dev/null)"
+  [ -n "$BRANCH" ] || BRANCH="$("$SCRIPT_DIR/project-git.sh" ymir-platform --field default_branch 2>/dev/null)"
+fi
+REMOTE="${REMOTE:-origin}"
+BRANCH="${BRANCH:-main}"
+
+declare -a ROWS; NUDGE_IDS=""
+reread=no
+changed_surface=0
+
+# Guarded fast-forward of one Brokk home. Sets FF_STATE/FF_DETAIL.
+ff_home() { # <path> <label>
+  local p="$1" label="$2"
+  if [ ! -d "$p" ]; then FF_STATE="skipped"; FF_DETAIL="not found: $p"; return; fi
+  if ! git -C "$p" rev-parse --is-inside-work-tree >/dev/null 2>&1; then FF_STATE="skipped"; FF_DETAIL="not a git repo"; return; fi
+  local cur; cur="$(git -C "$p" branch --show-current 2>/dev/null || echo '')"
+  if [ -n "$cur" ] && [ "$cur" != "$BRANCH" ]; then FF_STATE="skipped"; FF_DETAIL="on branch $cur"; return; fi
+  local dirty; dirty="$(git -C "$p" status --porcelain | wc -l | tr -d ' ')"
+  if [ "$dirty" != "0" ]; then FF_STATE="skipped"; FF_DETAIL="dirty ($dirty)"; return; fi
+  git -C "$p" fetch --quiet --prune "$REMOTE" 2>/dev/null || { FF_STATE="skipped"; FF_DETAIL="offline ($REMOTE)"; return; }
+  local local_h target
+  local_h="$(git -C "$p" rev-parse HEAD)"
+  target="$(git -C "$p" rev-parse "$REMOTE/$BRANCH" 2>/dev/null)" || { FF_STATE="skipped"; FF_DETAIL="$REMOTE/$BRANCH missing"; return; }
+  if [ "$local_h" = "$target" ]; then FF_STATE="current"; FF_DETAIL="${local_h:0:8}"; return; fi
+  if ! git -C "$p" merge-base --is-ancestor "$local_h" "$target"; then FF_STATE="skipped"; FF_DETAIL="diverged"; return; fi
+  if [ "$CHECK" = 1 ]; then FF_STATE="behind"; FF_DETAIL="$(git -C "$p" rev-list --count "$local_h..$target") behind"; return; fi
+  if git -C "$p" merge --ff-only -q "$target" 2>/dev/null; then
+    FF_STATE="updated"; FF_DETAIL="${local_h:0:8}..$(git -C "$p" rev-parse --short HEAD)"
+    if [ -n "$(git -C "$p" diff --name-only "$local_h" "$target" -- AGENTS.md bin .agents/skills 2>/dev/null)" ]; then
+      [ "$label" = "$ROOT" ] && changed_surface=1
+    fi
+  else FF_STATE="skipped"; FF_DETAIL="fast-forward failed"; fi
+}
+
+add_row() { ROWS+=("$1"); }
+
+# 1. This home.
+ff_home "$ROOT" "$ROOT"
+add_row "  \"$ROOT\",\"this Brokk home\",\"$FF_STATE\",\"$FF_DETAIL\""
+
+# 2. Registered Eindri-homes.
+if [ -f "$REG" ]; then
+  while IFS= read -r line; do
+    case "$line" in '- '*) ;; *) continue ;; esac
+    id="$(printf '%s' "$line" | sed -nE 's/^- ([^ ]+).*/\1/p')"
+    host="$(printf '%s' "$line" | sed -nE 's/.*\(host: ([^;)]+).*/\1/p' | tr -d ' ')"
+    home="$(printf '%s' "$line" | sed -nE 's/.*\(.*home: ([^;)]+).*/\1/p' | sed -E 's/ *(host:.*)?$//' | tr -d ' ')"
+    [ -n "$id" ] || continue
+    if [ -n "$host" ]; then
+      root="$(printf '%s' "$line" | sed -nE 's/.*root: ([^;)]+).*/\1/p' | tr -d ' ')"
+      add_row "  \"$id\",\"remote $host:${root:-$home}\",\"skipped\",\"remote route — run bin/groa-update.sh on $host\""
+      continue
+    fi
+    [ -n "$home" ] || home="$id"
+    ff_home "$home" "$home"
+    add_row "  \"$id\",\"$home\",\"$FF_STATE\",\"$FF_DETAIL\""
+    [ "$FF_STATE" = "updated" ] && NUDGE_IDS="$NUDGE_IDS $id"
+  done <"$REG"
+else
+  add_row "  \"-\",\"registry\",\"absent\",\"$REG (no Eindri-homes registered)\""
+fi
+
+# reread-Brokk: yes when this home's instruction surface advanced.
+[ "$changed_surface" = 1 ] && reread=yes
+
+printf 'groa[1]{state,root,remote,branch,mode}:\n  "renew","%s","%s","%s","%s"\n' "$ROOT" "$REMOTE" "$BRANCH" "$([ "$CHECK" = 1 ] && echo check || echo apply)"
+printf 'update[%d]{id,target,state,detail}:\n' "${#ROWS[@]}"
+printf '%s\n' "${ROWS[@]}"
+printf 'reread-Brokk: %s\n' "$reread"
+# Galdr owns the assets; when the instruction surface moved she must be reflected
+# in the same pass (the code/plan/asset agreement law).
+printf 'galdr-reread: %s\n' "$reread"
+if [ -n "${NUDGE_IDS# }" ]; then printf 'nudge-eindri-homes: %s\n' "${NUDGE_IDS# }"; else printf 'nudge-eindri-homes: none\n'; fi
+
+# Keep the whole fleet on the fleet preferences (writes each home's gitignored
+# state/; never touches a tracked tree).
+[ -x "$SCRIPT_DIR/fleet-apply.sh" ] && "$SCRIPT_DIR/fleet-apply.sh" >/dev/null 2>&1 || true
+
+# Heal this home forward (structure migrations) after every update.
+[ -x "$SCRIPT_DIR/ymir-migrate.sh" ] && "$SCRIPT_DIR/ymir-migrate.sh" apply >/dev/null 2>&1 || true