@zerwiz/ymir 0.1.4 → 0.1.7

package/bin/brokk-lease-lib.sh

@@ -0,0 +1,222 @@
+#!/usr/bin/env bash
+# brokk-lease-lib.sh - the per-task supervision lease contract (one owner).
+#
+# WHY. On the Pi supervision branch (docs/pi-supervision-branch.md), two LLM
+# actors share one brokk home inside one pi process: MAIN (the Allfather's
+# chat) and BRANCH (the persistent supervision conversation). Most records have
+# exactly one natural owner, but the overlap set - steering or stopping a
+# worker, post-landing cleanup, backlog status for a task, stuck-worker
+# recovery - could otherwise be mutated by both actors at once. The lease is
+# the merge-conflict analog: a small per-task file saying which actor is
+# changing that task right now, and the mutating entrypoints refuse the other
+# actor while it exists.
+#
+# CONTRACT.
+#   - Lease file: $STATE/.lease-<task>, one line "<actor>\t<pid>\t<epoch>".
+#     Written atomically (temp + ln for claim, temp + mv for a same-actor
+#     refresh), with inspection and mutation serialized by the home-local
+#     lease-command lock; leases never coordinate across brokk homes.
+#   - Actors: exactly "main" and "branch". The current actor is
+#     $BROKK_SUPERVISION_ACTOR when set, else "main". The branch's shell gets
+#     BROKK_SUPERVISION_ACTOR=branch injected deterministically by the Pi branch
+#     extension's bash tool, not by agent memory. Any other value is refused
+#     loudly - an unknown actor is a wiring bug, not a third role.
+#   - Staleness: the recorded pid is the long-lived supervising process (the
+#     session-lock holder, or BROKK_LEASE_HOLDER_PID - see bin/brokk-lease.sh), and
+#     both actors live inside that one pi process, so a dead recorded pid
+#     means the process died; the lease is cleared at the next claim, guard,
+#     or sweep. Liveness requires a Pi calling context plus state/.lock, and
+#     the recorded pid must BE its current holder, so a lease left by an exited
+#     Pi session goes stale even if its pid was recycled by an unrelated
+#     process, and a non-Pi home never honors a leftover Pi lease. A lease held by the
+#     live current session but an abandoned branch conversation is recovered
+#     by the branch extension's generation-activation cleanup.
+#
+# THREAT MODEL (deliberate, Allfather-decided): these guards are
+# CONFUSED-AGENT-GRADE, the same grade bin/brokk-gate-refuse-lib.sh documents
+# for the gate refusal. They stop non-deliberate misuse - the injected actor
+# identity, the loud refusals, and the session-bound staleness make every
+# accidental cross-actor mutation fail loudly. A deliberately forging shell
+# running as the same uid inside the same pi process can evade any in-process
+# discriminator (it can rewrite env, spawn fresh shells, and edit state
+# files), so adversarial-grade separation is explicitly out of scope here and
+# tracked as separate follow-up design work. The branch's shell prelude makes
+# the actor variables readonly (see the Pi branch extension), so an
+# ACCIDENTAL override fails loudly inside the branch's own shell as well.
+#   - Guard semantics (fm_lease_guard): no lease, a same-actor lease, or a
+#     provably stale lease passes; a live lease held by the OTHER actor
+#     refuses with exit BROKK_LEASE_REFUSE_EXIT. In a Pi supervision context the
+#     guard retains the lease-command lock until fm_lease_guard_release, so the
+#     other actor cannot claim between the check and the guarded mutation. A
+#     home without the current Pi session lock cannot have a live lease, so
+#     the guard is a no-op there - non-Pi behavior is unchanged by construction.
+#   - Role partition (fm_lease_forbid_branch): actions MAIN alone owns -
+#     merging a PR, landing local-only work, spawning workers - refuse the
+#     branch actor outright, lease or no lease.
+#   - "backlog" is a reserved claimable resource name used by the branch
+#     prompt around its own data/backlog.md writes. This is deliberately
+#     branch-side containment only; main's tasks-axi path has no executable
+#     backlog lease guard in this scope.
+#
+# Sourced by bin/brokk-send.sh, bin/brokk-control.sh, bin/brokk-teardown.sh,
+# bin/brokk-pr-merge.sh, bin/brokk-merge-local.sh, bin/einherjar-spawn.sh, and
+# bin/brokk-lease.sh. Callers must have $STATE resolved before calling. No side
+# effects on source. set -u / set -e safe.
+
+# Distinct from usage errors (2), the gate refusal (3), and brokk-send's
+# unconfirmed submit (3): recognizable as "the other supervision actor holds
+# this task right now - retry after the lease clears".
+BROKK_LEASE_REFUSE_EXIT=6
+BROKK_LEASE_LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+BROKK_LEASE_GUARD_LOCK=
+
+fm_lease_lock_helpers() {
+  command -v fm_lock_acquire_wait >/dev/null 2>&1 && return 0
+  # brokk-wake-lib.sh is a canonical lint root in its own right and is already
+  # sourced directly by every caller of this lazy fallback; keep this an
+  # analysis boundary so ShellCheck's external-source traversal does not
+  # recursively duplicate that large graph for every lease-lib consumer.
+  # shellcheck source=/dev/null
+  . "$BROKK_LEASE_LIB_DIR/brokk-wake-lib.sh"
+}
+
+# fm_lease_actor: print the current actor after validating it. Returns 1 (with
+# stderr) for an unknown BROKK_SUPERVISION_ACTOR value.
+fm_lease_actor() {
+  local actor=${BROKK_SUPERVISION_ACTOR:-main}
+  case "$actor" in
+    main|branch) printf '%s\n' "$actor" ;;
+    *)
+      echo "error: unknown BROKK_SUPERVISION_ACTOR '$actor' (expected main or branch)" >&2
+      return 1
+      ;;
+  esac
+}
+
+# fm_lease_valid_id <id>: 0 iff the task/resource id is safe to embed in a
+# state filename.
+fm_lease_valid_id() {
+  case "${1:-}" in
+    '' | *[!A-Za-z0-9._-]*) return 1 ;;
+    *) return 0 ;;
+  esac
+}
+
+fm_lease_path() {
+  printf '%s/.lease-%s\n' "$STATE" "$1"
+}
+
+# fm_lease_read <task>: read the lease into BROKK_LEASE_ACTOR/BROKK_LEASE_PID/
+# BROKK_LEASE_EPOCH. Returns 1 when no lease file exists. A malformed lease
+# (unreadable actor or pid) reads as actor "" so callers treat it as stale
+# rather than blocking forever on a torn record.
+fm_lease_read() {
+  local file line
+  file=$(fm_lease_path "$1")
+  BROKK_LEASE_ACTOR=
+  BROKK_LEASE_PID=
+  BROKK_LEASE_EPOCH=
+  [ -e "$file" ] || return 1
+  IFS= read -r line < "$file" 2>/dev/null || line=
+  BROKK_LEASE_ACTOR=$(printf '%s' "$line" | cut -f1)
+  BROKK_LEASE_PID=$(printf '%s' "$line" | cut -f2)
+  # shellcheck disable=SC2034 # Consumed by sourcing callers (bin/brokk-lease.sh check).
+  BROKK_LEASE_EPOCH=$(printf '%s' "$line" | cut -f3)
+  case "$BROKK_LEASE_ACTOR" in
+    main|branch) ;;
+    *) BROKK_LEASE_ACTOR= ;;
+  esac
+  case "$BROKK_LEASE_PID" in
+    '' | *[!0-9]*) BROKK_LEASE_PID= ;;
+  esac
+  return 0
+}
+
+# fm_lease_live <task>: 0 iff a well-formed lease exists in a Pi context, its
+# recorded pid is alive, and that pid IS the current session-lock holder (see
+# the staleness contract above).
+fm_lease_live() {
+  local lock_pid
+  case "${PI_CODING_AGENT:-}:${BROKK_SUPERVISION_ACTOR:-}" in
+    true:*|*:main|*:branch) ;;
+    *) return 1 ;;
+  esac
+  fm_lease_read "$1" || return 1
+  [ -n "$BROKK_LEASE_ACTOR" ] || return 1
+  [ -n "$BROKK_LEASE_PID" ] || return 1
+  kill -0 "$BROKK_LEASE_PID" 2>/dev/null || return 1
+  # The session lock is machine-global for the primary; state/.lock-path records
+  # the resolved path (per-home for an Eindri-home, legacy state/.lock otherwise).
+  local lock_file="$STATE/.lock"
+  [ -r "$STATE/.lock-path" ] && lock_file=$(tr -d '[:space:]' <"$STATE/.lock-path")
+  lock_pid=$(head -n 1 "$lock_file" 2>/dev/null || true)
+  case "$lock_pid" in ''|0|1|*[!0-9]*) return 1 ;; esac
+  [ "$BROKK_LEASE_PID" = "$lock_pid" ]
+}
+
+# fm_lease_clear_stale <task>: remove the lease file when it exists but is not
+# live. Silent; never touches a live lease.
+fm_lease_clear_stale() {
+  local file
+  file=$(fm_lease_path "$1")
+  [ -e "$file" ] || return 0
+  fm_lease_live "$1" && return 0
+  rm -f -- "$file"
+}
+
+# fm_lease_guard <task> <action-label>: refuse (exit BROKK_LEASE_REFUSE_EXIT) when
+# a live lease held by the OTHER actor exists for <task>. In a Pi supervision
+# context, a successful guard retains the command lock across the caller's
+# mutation; the caller must invoke fm_lease_guard_release from its EXIT cleanup.
+# This closes the check/use race with a concurrent claim. Outside Pi, stale
+# records are still cleaned but the lock is released before returning.
+fm_lease_guard() {
+  local task=$1 action=$2 actor lock lease_actor active=0
+  fm_lease_valid_id "$task" || return 0
+  actor=$(fm_lease_actor) || exit "$BROKK_LEASE_REFUSE_EXIT"
+  case "${PI_CODING_AGENT:-}:${BROKK_SUPERVISION_ACTOR:-}" in
+    true:*|*:main|*:branch) active=1 ;;
+  esac
+  [ "$active" = 1 ] || [ -e "$(fm_lease_path "$task")" ] || return 0
+  fm_lease_lock_helpers
+  lock="$STATE/.brokk-lease-command.lock"
+  # A caller with more than one guarded phase already excludes claims until
+  # its shared cleanup; do not recursively acquire the non-reentrant lock.
+  if [ "$BROKK_LEASE_GUARD_LOCK" != "$lock" ]; then
+    fm_lock_acquire_wait "$lock"
+    BROKK_LEASE_GUARD_LOCK=$lock
+  fi
+  if ! fm_lease_live "$task"; then
+    fm_lease_clear_stale "$task" || { fm_lease_guard_release; return 1; }
+    if [ "$active" != 1 ]; then
+      fm_lease_guard_release
+    fi
+    return 0
+  fi
+  lease_actor=$BROKK_LEASE_ACTOR
+  if [ "$lease_actor" != "$actor" ]; then
+    fm_lease_guard_release
+    echo "error: $action refused - task '$task' is leased to the $lease_actor supervision actor (state/.lease-$task); retry after that actor releases it" >&2
+    exit "$BROKK_LEASE_REFUSE_EXIT"
+  fi
+}
+
+# Release the claim/guard serialization lock retained by fm_lease_guard.
+# Idempotent so callers can use it unconditionally from existing EXIT cleanup.
+fm_lease_guard_release() {
+  local lock=$BROKK_LEASE_GUARD_LOCK
+  [ -n "$lock" ] || return 0
+  BROKK_LEASE_GUARD_LOCK=
+  fm_lock_release "$lock"
+}
+
+# fm_lease_forbid_branch <action-label>: refuse (exit BROKK_LEASE_REFUSE_EXIT)
+# when the current actor is the supervision branch. Guards the main-owned role
+# partition; a home with no branch never sets the actor and always passes.
+fm_lease_forbid_branch() {
+  local action=$1 actor
+  actor=$(fm_lease_actor) || exit "$BROKK_LEASE_REFUSE_EXIT"
+  [ "$actor" = branch ] || return 0
+  echo "error: $action refused - the supervision branch never performs this action; report the outcome and leave it to main (role partition: docs/pi-supervision-branch.md)" >&2
+  exit "$BROKK_LEASE_REFUSE_EXIT"
+}

package/bin/brokk-lease.sh

@@ -0,0 +1,193 @@
+#!/usr/bin/env bash
+# brokk-lease.sh - claim, release, inspect, and sweep per-task supervision leases.
+#
+# The lease contract itself (file format, actors, staleness, guard semantics)
+# is owned by bin/brokk-lease-lib.sh; this is the command surface the two
+# supervision actors use around the overlap set (steering, stopping, cleanup,
+# backlog status, stuck-worker recovery). "backlog" is the reserved resource
+# the branch prompt claims around its own backlog writes; main's tasks-axi path
+# is deliberately unguarded in this scope.
+#
+# Usage:
+#   brokk-lease.sh claim <task> [--actor main|branch]
+#       Take the lease for the calling actor. Idempotent for the holder (the
+#       claim refreshes its own lease). Refuses with exit 6 while the other
+#       actor holds a live lease. A stale lease (dead pid, or a torn record)
+#       is cleared and re-claimed.
+#   brokk-lease.sh release <task> [--actor main|branch]
+#       Drop the calling actor's lease. Releasing a lease the actor does not
+#       hold is a silent no-op, so a retry after a partial failure is safe.
+#       Naming the other actor is refused loudly.
+#   brokk-lease.sh check <task>
+#       Print "<actor> <pid> <epoch> <live|stale>" for a held lease, or
+#       nothing (exit 1) when the task is unleased.
+#   brokk-lease.sh release-actor --actor main|branch
+#       Drop every lease the named actor holds; the Pi branch extension runs
+#       this at generation activation so a replaced branch conversation's
+#       leases never outlive it.
+#   brokk-lease.sh sweep
+#       Remove every provably stale lease in this home. Run at session start
+#       (a lease held by a dead actor is cleared at session start); safe to
+#       run any time - a live lease is never touched.
+#
+# The default actor is $BROKK_SUPERVISION_ACTOR (else main); when --actor is
+# supplied for a mutation, it must name that calling actor. Exit codes: 0 ok,
+# 1 check-miss, 2 usage, 6 refused (other actor holds or actor mismatch).
+set -eu
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+BROKK_ROOT="${BROKK_ROOT_OVERRIDE:-${BROKK_ROOT:-$(cd "$SCRIPT_DIR/.." && pwd)}}"
+BROKK_HOME="${BROKK_HOME:-${BROKK_ROOT_OVERRIDE:-$BROKK_ROOT}}"
+STATE="${BROKK_STATE_OVERRIDE:-$BROKK_HOME/state}"
+# shellcheck source=bin/brokk-lease-lib.sh
+. "$SCRIPT_DIR/brokk-lease-lib.sh"
+# shellcheck source=bin/brokk-wake-lib.sh
+. "$SCRIPT_DIR/brokk-wake-lib.sh"
+
+mkdir -p "$STATE"
+LEASE_COMMAND_LOCK="$STATE/.brokk-lease-command.lock"
+fm_lock_acquire_wait "$LEASE_COMMAND_LOCK"
+trap 'fm_lock_release "$LEASE_COMMAND_LOCK"' EXIT
+
+usage() {
+  echo "usage: brokk-lease.sh claim|release <task> [--actor main|branch] | release-actor --actor main|branch | check <task> | sweep" >&2
+  exit 2
+}
+
+CMD=${1:-}
+shift 2>/dev/null || true
+
+case "$CMD" in
+  claim|release)
+    TASK=${1:-}
+    shift 2>/dev/null || true
+    fm_lease_valid_id "$TASK" || usage
+    ACTOR=
+    while [ "$#" -gt 0 ]; do
+      case "$1" in
+        --actor)
+          ACTOR=${2:-}
+          shift 2 || usage
+          ;;
+        *) usage ;;
+      esac
+    done
+    if [ -z "$ACTOR" ]; then
+      ACTOR=$(fm_lease_actor) || exit 2
+    fi
+    case "$ACTOR" in main|branch) ;; *) usage ;; esac
+    ;;
+  check)
+    TASK=${1:-}
+    [ "$#" -le 1 ] || usage
+    fm_lease_valid_id "$TASK" || usage
+    ;;
+  release-actor)
+    ACTOR=
+    while [ "$#" -gt 0 ]; do
+      case "$1" in
+        --actor)
+          ACTOR=${2:-}
+          shift 2 || usage
+          ;;
+        *) usage ;;
+      esac
+    done
+    case "$ACTOR" in main|branch) ;; *) usage ;; esac
+    ;;
+  sweep)
+    [ "$#" -eq 0 ] || usage
+    ;;
+  *) usage ;;
+esac
+
+case "$CMD" in
+  claim)
+    # Loud accidental-override guard: a claim naming the OTHER actor than the
+    # caller's own injected identity is a wiring mistake, never a role change.
+    # Release and bulk release enforce the same caller authorization below.
+    CALLER=$(fm_lease_actor) || exit "$BROKK_LEASE_REFUSE_EXIT"
+    if [ "$ACTOR" != "$CALLER" ]; then
+      echo "error: claim refused - the $CALLER supervision actor cannot claim a lease as $ACTOR on '$TASK'" >&2
+      exit "$BROKK_LEASE_REFUSE_EXIT"
+    fi
+    LEASE=$(fm_lease_path "$TASK")
+    if fm_lease_live "$TASK" && [ "$BROKK_LEASE_ACTOR" != "$ACTOR" ]; then
+      echo "error: claim refused - task '$TASK' is leased to the $BROKK_LEASE_ACTOR supervision actor (state/.lease-$TASK)" >&2
+      exit "$BROKK_LEASE_REFUSE_EXIT"
+    fi
+    # The lease outlives this CLI call, so its liveness pid must be the
+    # long-lived supervising process: BROKK_LEASE_HOLDER_PID when the caller
+    # provides one (the Pi branch extension passes the session-lock holder),
+    # else the session-lock holder (state/.lock is the harness pid), else this
+    # shell; without a matching session lock the resulting lease is stale.
+    HOLDER_PID=${BROKK_LEASE_HOLDER_PID:-}
+    case "$HOLDER_PID" in *[!0-9]*) HOLDER_PID= ;; esac
+    if [ -z "$HOLDER_PID" ]; then
+      # state/.lock-path records the resolved session lock (machine-global for
+      # the primary, per-home for an Eindri-home); fall back to the legacy path.
+      lock_file="$STATE/.lock"
+      [ -r "$STATE/.lock-path" ] && lock_file=$(tr -d '[:space:]' <"$STATE/.lock-path")
+      HOLDER_PID=$(head -n 1 "$lock_file" 2>/dev/null | tr -cd '0-9' || true)
+    fi
+    [ -n "$HOLDER_PID" ] || HOLDER_PID=$$
+    TMP=$(mktemp "$STATE/.brokk-lease-tmp.XXXXXX")
+    printf '%s\t%s\t%s\n' "$ACTOR" "$HOLDER_PID" "$(date +%s)" > "$TMP"
+    if [ -e "$LEASE" ]; then
+      # Same-actor refresh, or a stale/torn record: replace atomically.
+      mv -f -- "$TMP" "$LEASE"
+    elif ! ln -- "$TMP" "$LEASE" 2>/dev/null; then
+      # Lost the create race to the sibling actor; re-check who won.
+      rm -f -- "$TMP"
+      if fm_lease_live "$TASK" && [ "$BROKK_LEASE_ACTOR" != "$ACTOR" ]; then
+        echo "error: claim refused - task '$TASK' was just leased to the $BROKK_LEASE_ACTOR supervision actor" >&2
+        exit "$BROKK_LEASE_REFUSE_EXIT"
+      fi
+      TMP=$(mktemp "$STATE/.brokk-lease-tmp.XXXXXX")
+      printf '%s\t%s\t%s\n' "$ACTOR" "$HOLDER_PID" "$(date +%s)" > "$TMP"
+      mv -f -- "$TMP" "$LEASE"
+    else
+      rm -f -- "$TMP"
+    fi
+    ;;
+  release)
+    CALLER=$(fm_lease_actor) || exit "$BROKK_LEASE_REFUSE_EXIT"
+    if [ "$ACTOR" != "$CALLER" ]; then
+      echo "error: release refused - the $CALLER supervision actor cannot release a lease as $ACTOR on '$TASK'" >&2
+      exit "$BROKK_LEASE_REFUSE_EXIT"
+    fi
+    if fm_lease_read "$TASK" && { [ "$BROKK_LEASE_ACTOR" = "$ACTOR" ] || [ -z "$BROKK_LEASE_ACTOR" ]; }; then
+      rm -f -- "$(fm_lease_path "$TASK")"
+    fi
+    ;;
+  check)
+    fm_lease_read "$TASK" || exit 1
+    if fm_lease_live "$TASK"; then LIVENESS=live; else LIVENESS=stale; fi
+    printf '%s %s %s %s\n' "${BROKK_LEASE_ACTOR:-unreadable}" "${BROKK_LEASE_PID:-0}" "${BROKK_LEASE_EPOCH:-0}" "$LIVENESS"
+    ;;
+  release-actor)
+    CALLER=$(fm_lease_actor) || exit "$BROKK_LEASE_REFUSE_EXIT"
+    if [ "$ACTOR" != "$CALLER" ]; then
+      echo "error: release-actor refused - the $CALLER supervision actor cannot release leases as $ACTOR" >&2
+      exit "$BROKK_LEASE_REFUSE_EXIT"
+    fi
+    for LEASE in "$STATE"/.lease-*; do
+      [ -e "$LEASE" ] || continue
+      case "$LEASE" in *.lock) continue ;; esac
+      TASK=${LEASE##*/.lease-}
+      fm_lease_valid_id "$TASK" || continue
+      if fm_lease_read "$TASK" && [ "$BROKK_LEASE_ACTOR" = "$ACTOR" ]; then
+        rm -f -- "$LEASE"
+      fi
+    done
+    ;;
+  sweep)
+    for LEASE in "$STATE"/.lease-*; do
+      [ -e "$LEASE" ] || continue
+      case "$LEASE" in *.lock) continue ;; esac
+      TASK=${LEASE##*/.lease-}
+      fm_lease_valid_id "$TASK" || continue
+      fm_lease_clear_stale "$TASK"
+    done
+    ;;
+esac

package/bin/brokk-lint.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# brokk-lint.sh — the Brokk lint gate. Single owner of lint for CI and
+# no-mistakes; run by .github/workflows and `commands.lint` in .no-mistakes.yaml.
+# Galdr-style: TOON output, structured errors, no prompts, idempotent.
+#
+# Usage: bin/brokk-lint.sh [--quiet] ; bin/brokk-lint.sh --version
+# Exit: 0 clean, 1 findings, 2 usage.
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+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
+QUIET=0
+[ "${1-}" = "--quiet" ] && QUIET=1
+
+declare -a N S; fails=0
+add() { N+=("$1"); S+=("$2"); [ "$2" = FAIL ] && fails=$((fails + 1)); }
+
+# 1. shell syntax
+shell=OK
+for f in "$ROOT"/bin/*.sh; do
+  [ -e "$f" ] || continue
+  bash -n "$f" 2>/dev/null || shell=FAIL
+done
+add "shell syntax" "$shell"
+
+# 2. plugin JS
+js=OK
+if command -v node >/dev/null 2>&1; then
+  while IFS= read -r f; do
+    node --check "$f" 2>/dev/null || js=FAIL
+  done < <(find "$ROOT/.opencode/plugins" -name '*.js' 2>/dev/null)
+fi
+add "plugin syntax" "$js"
+
+# 3. JSON parse
+json=OK
+for f in "$ROOT/opencode.json" "$ROOT"/.agents/config/*.json "$ROOT"/.claude/settings.json "$ROOT"/.codex/hooks.json "$ROOT"/.cursor/hooks.json "$ROOT"/.opencode/plugins/package.json; do
+  [ -e "$f" ] || continue
+  python3 -m json.tool "$f" >/dev/null 2>&1 || json=FAIL
+done
+add "json parse" "$json"
+
+# 4. Galdr/Tyr compliance gates
+if bash "$ROOT/.agents/skills/galdr-ymirsystem/scripts/compliance-check.sh" >/dev/null 2>&1; then
+  add "galdr compliance" OK
+else
+  add "galdr compliance" FAIL
+fi
+
+if [ "$QUIET" = 0 ]; then
+  printf 'lint[%s]{check,status}:\n' "${#N[@]}"
+  for i in "${!N[@]}"; do printf '  "%s","%s"\n' "${N[$i]}" "${S[$i]}"; done
+fi
+if [ "$fails" -gt 0 ]; then
+  printf 'error: %s lint check(s) failed\n' "$fails" >&2
+  printf 'help: run bin/brokk-lint.sh to see the failing check\n' >&2
+  exit 1
+fi
+exit 0

package/bin/brokk-send.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# brokk-send.sh — send a one-line steer to a running Brokk/Eindri-home.
+# Resolves the target's home from data/eindri-homes.md and appends a wake line to
+# its state/.wake-queue (the drain prints it as `WAKE <line>`). Local routes only;
+# a remote route must be nudged on its own host. Galdr-style TOON.
+#
+# Usage: brokk-send.sh <id> <message>
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# The roots that live OUTSIDE the code tree: this machine's records and the
+# runtime state belong to the home the operator chose at installation, never in
+# the tree — a packaged install replaces its tree on upgrade (Rule 04).
+if [ -z "${YMIR_HOARD_LIB_LOADED:-}" ]; then
+  _yr="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  for _yc in "$_yr/hoard-lib.sh" "$(dirname "$_yr")/bin/hoard-lib.sh"; do
+    [ -r "$_yc" ] && { . "$_yc"; YMIR_HOARD_LIB_LOADED=1; break; }
+  done
+  unset _yr _yc
+fi
+hoard_state_dir YMIR_STATE_DIR
+hoard_data_dir YMIR_DATA_DIR
+REG="${BROKK_EINDRI_HOMES:-$YMIR_DATA_DIR/eindri-homes.md}"
+
+case "${1-}" in -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;; -h|--help|"") sed -n '2,9p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; esac
+ID="${1-}"; shift || true
+MSG="${*:-}"
+[ -n "$ID" ] && [ -n "$MSG" ] || { printf 'error: usage: brokk-send.sh <id> <message>\n' >&2; exit 2; }
+
+if [ "$ID" = "this" ] || [ "$ID" = "brokk" ]; then HOME_DIR="$ROOT"; HOST=""; else
+  HOME_DIR=""; HOST=""
+  if [ -f "$REG" ]; then
+    line="$(grep -E "^- ${ID} " "$REG" | head -1)"
+    HOST="$(printf '%s' "$line" | sed -nE 's/.*\(host: ([^;)]+).*/\1/p' | tr -d ' ')"
+    HOME_DIR="$(printf '%s' "$line" | sed -nE 's/.*\(.*home: ([^;)]+).*/\1/p' | tr -d ' ')"
+  fi
+fi
+
+if [ -n "$HOST" ]; then
+  printf 'send[1]{id,state,detail}:\n  "%s","remote","run bin/brokk-send.sh %s on host %s"\n' "$ID" "$ID" "$HOST"
+  exit 1
+fi
+[ -n "$HOME_DIR" ] && [ -d "$HOME_DIR" ] || { printf 'send[1]{id,state,detail}:\n  "%s","unknown","no home for id (see %s)"\n' "$ID" "${REG#"$ROOT"/}"; exit 1; }
+
+mkdir -p "$HOME_DIR/state"
+ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+printf 'from=brokk to=%s at=%s msg=%s\n' "$ID" "$ts" "$MSG" >>"$HOME_DIR/state/.wake-queue"
+printf 'send[1]{id,state,detail}:\n  "%s","queued","%s/state/.wake-queue"\n' "$ID" "${HOME_DIR#"$ROOT"/}"

package/bin/brokk-update.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# brokk-update.sh — back-compat alias.
+#
+# The updater shaman is Gróa; see bin/groa-update.sh. This thin alias keeps old
+# callers working (and the `groa-update` skill now names her).
+set -u
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+printf 'note: brokk-update.sh is an alias; the updater is Gróa (bin/groa-update.sh)\n' >&2
+exec "$SCRIPT_DIR/groa-update.sh" "$@"

package/bin/brokk-wake-grant.sh

@@ -0,0 +1,127 @@
+#!/usr/bin/env bash
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=bin/brokk-wake-lib.sh
+. "$SCRIPT_DIR/brokk-wake-lib.sh"
+
+BRANCH_ROWS="$STATE/.branch-eligible-rows"
+BRANCH_OWNER="$STATE/.branch-eligible-owner"
+MAIN_ROWS="$STATE/.main-eligible-rows"
+TMP=
+LOCK_HELD=false
+
+# shellcheck disable=SC2329 # Registered by the EXIT trap below.
+cleanup() {
+  local status=$?
+  [ -z "$TMP" ] || rm -f -- "$TMP" 2>/dev/null || true
+  [ "$LOCK_HELD" = false ] || fm_lock_release "$BROKK_WAKE_QUEUE_LOCK"
+  exit "$status"
+}
+trap cleanup EXIT
+trap 'exit 130' INT
+trap 'exit 143' TERM
+
+rows_valid() {
+  [ -s "$1" ] && awk 'BEGIN { ok=1 } !/^[0-9]+$/ || seen[$0]++ { ok=0 } END { exit !ok }' "$1"
+}
+
+owner_matches() {
+  local expected_pid=${1:-} expected_generation=${2:-} version pid identity generation current
+  [ -f "$BRANCH_OWNER" ] && [ ! -L "$BRANCH_OWNER" ] || return 1
+  exec 8< "$BRANCH_OWNER" || return 1
+  IFS= read -r version <&8 || { exec 8<&-; return 1; }
+  IFS= read -r pid <&8 || { exec 8<&-; return 1; }
+  IFS= read -r identity <&8 || { exec 8<&-; return 1; }
+  IFS= read -r generation <&8 || { exec 8<&-; return 1; }
+  if IFS= read -r _extra <&8; then exec 8<&-; return 1; fi
+  exec 8<&-
+  [ "$version" = brokk-branch-eligible-owner-v1 ] || return 1
+  case "$pid" in ''|*[!0-9]*|1) return 1 ;; esac
+  case "$generation" in ''|*[!A-Za-z0-9._-]*) return 1 ;; esac
+  [ -z "$expected_pid" ] || [ "$pid" = "$expected_pid" ] || return 1
+  [ -z "$expected_generation" ] || [ "$generation" = "$expected_generation" ] || return 1
+  current=$(fm_pid_identity "$pid" 2>/dev/null) || return 1
+  [ -n "$current" ] && [ "$current" = "$identity" ]
+}
+
+case "${1:-}" in
+  activate)
+    pid=${2:-}
+    generation=${3:-}
+    [ "$#" -eq 3 ] || exit 2
+    case "$pid" in ''|*[!0-9]*|1) exit 2 ;; esac
+    case "$generation" in ''|*[!A-Za-z0-9._-]*) exit 2 ;; esac
+    identity=$(fm_pid_identity "$pid" 2>/dev/null) || exit 1
+    [ -n "$identity" ] || exit 1
+    TMP=$(mktemp "$STATE/.branch-eligible-owner.tmp.XXXXXX") || exit 1
+    printf '%s\n%s\n%s\n%s\n' brokk-branch-eligible-owner-v1 "$pid" "$identity" "$generation" > "$TMP" || exit 1
+    chmod 0600 "$TMP" || exit 1
+    fm_lock_acquire_wait "$BROKK_WAKE_QUEUE_LOCK"
+    LOCK_HELD=true
+    [ "$(fm_pid_identity "$pid" 2>/dev/null || true)" = "$identity" ] || exit 1
+    rm -f -- "$BRANCH_ROWS" || exit 1
+    _fm_atomic_replace "$TMP" "$BRANCH_OWNER" || exit 1
+    TMP=
+    ;;
+  publish)
+    generation=${2:-}
+    [ "$#" -gt 2 ] || exit 2
+    case "$generation" in ''|*[!A-Za-z0-9._-]*) exit 2 ;; esac
+    shift 2
+    TMP=$(mktemp "$STATE/.branch-eligible-rows.tmp.XXXXXX") || exit 1
+    printf '%s\n' "$@" > "$TMP" || exit 1
+    chmod 0600 "$TMP" || exit 1
+    rows_valid "$TMP" || exit 2
+    fm_lock_acquire_wait "$BROKK_WAKE_QUEUE_LOCK"
+    LOCK_HELD=true
+    owner_matches '' "$generation" || exit 1
+    replace=1
+    if [ -e "$BRANCH_ROWS" ] || [ -L "$BRANCH_ROWS" ]; then
+      rows_valid "$BRANCH_ROWS" && cmp -s "$TMP" "$BRANCH_ROWS" || exit 1
+      replace=0
+    fi
+    awk -F '\t' -v requested="$TMP" -v main="$MAIN_ROWS" '
+      BEGIN {
+        while ((getline line < requested) > 0) wanted[line]=1
+        while ((getline line < main) > 0) owned[line]=1
+      }
+      NF >= 5 && $2 ~ /^[0-9]+$/ && $2 in wanted { present[$2]=1 }
+      END {
+        for (seq in wanted) if (seq in owned) exit 3
+        for (seq in wanted) if (!(seq in present)) exit 1
+      }
+    ' "$BROKK_WAKE_QUEUE"
+    rc=$?
+    [ "$rc" -eq 0 ] || exit "$rc"
+    if [ "$replace" -eq 1 ]; then
+      _fm_atomic_replace "$TMP" "$BRANCH_ROWS" || exit 1
+      TMP=
+    fi
+    ;;
+  release)
+    generation=${2:-}
+    [ "$#" -eq 2 ] || exit 2
+    fm_lock_acquire_wait "$BROKK_WAKE_QUEUE_LOCK"
+    LOCK_HELD=true
+    owner_matches '' "$generation" || exit 1
+    rm -f -- "$BRANCH_ROWS" || exit 1
+    ;;
+  deactivate)
+    pid=${2:-}
+    generation=${3:-}
+    [ "$#" -eq 3 ] || exit 2
+    fm_lock_acquire_wait "$BROKK_WAKE_QUEUE_LOCK"
+    LOCK_HELD=true
+    owner_matches "$pid" "$generation" || exit 1
+    rm -f -- "$BRANCH_ROWS" "$BRANCH_OWNER" || exit 1
+    ;;
+  *)
+    echo "usage: brokk-wake-grant.sh activate PID GENERATION | publish GENERATION SEQUENCE... | release GENERATION | deactivate PID GENERATION" >&2
+    exit 2
+    ;;
+esac
+
+fm_lock_release "$BROKK_WAKE_QUEUE_LOCK"
+LOCK_HELD=false
+exit 0