@zerwiz/ymir 0.1.4 → 0.1.7

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,130 @@
+#!/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}"
+# The registry lives in the hoard (RULES/04-hoard.md; correction 2026-09-17).
+# Resolve through hoard-lib so the path can never drift again.
+if [ -r "$SCRIPT_DIR/hoard-lib.sh" ]; then
+  # shellcheck source=bin/hoard-lib.sh
+  . "$SCRIPT_DIR/hoard-lib.sh"; hoard_root _hoard
+else
+  _hoard="${YMIR_HOARD:-$YMIR_HOME/hodd}"
+fi
+REG="${BROKK_EINDRI_HOMES:-$_hoard/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

package/bin/hall-snapshot.sh

@@ -0,0 +1,111 @@
+#!/usr/bin/env bash
+# hall-snapshot.sh — the planning feed for the Óðrerir Live Hall.
+#
+# Reads the REAL system state and emits a public-safe livehall.json the Hall
+# fetches (same origin) and renders: the tally of the hall, the deal-stack of
+# planned errands (the armed when-sources and their smiths), and the carved
+# ledger (underway / landed / charted). The Hall becomes the full planning
+# glass: every errand Brokk arms appears there; every smith's state is live.
+#
+# PUBLIC-SAFE BY LAW: only Norse worker names, counts, and job ids — never a
+# private name, path, secret, or command (the PLAN §12 gate).
+#
+# Usage:
+#   bin/hall-snapshot.sh [<output.json>]
+#   default output: apps/odrerir/public/livehall.json
+#   (the Live Hall's own deck; the merged public site takes it from its build).
+set -u
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="${BROKK_ROOT_OVERRIDE:-$(cd "$SCRIPT_DIR/.." && pwd)}"
+
+# The operator's settings and secrets live in the home they chose, never in the
+# code tree — a packaged install replaces its tree on upgrade, and a credential
+# must never sit in a tree that ships (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_settings_dir YMIR_SETTINGS_DIR
+hoard_local_env YMIR_ENV_FILE
+hoard_state_dir YMIR_STATE_DIR
+hoard_data_dir YMIR_DATA_DIR
+
+# 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).
+STATE="${BROKK_STATE_OVERRIDE:-$YMIR_STATE_DIR}"
+OUT="${1:-$ROOT/apps/odrerir/public/livehall.json}"
+
+runes_file="${BROKK_RUNES_FILE:-${YMIR_HOME:-$HOME/Documents/Ymir}/hodd/memory/runes_audit.md}"
+PROJECTS_FILE="${YMIR_HOME:-$HOME/Documents/Ymir}/hodd/identity/projects.yaml"
+projects_file="$PROJECTS_FILE"
+cron_file="$YMIR_SETTINGS_DIR/cron.yaml"
+
+# --- tally the pieces ---
+runes=$(grep -c '^{' "$runes_file" 2>/dev/null || echo 0)
+projects=$(grep -E '^  - id:' "$projects_file" 2>/dev/null | sed -E 's/^  - id: *([^ ]+).*/\1/' | tr '\n' ' ')
+loom=$(grep -cE '^[0-9]{2}:[0-9]{2} ' "$cron_file" 2>/dev/null || echo 0)
+wake=$(wc -l <"$STATE/.wake-queue" 2>/dev/null | tr -d '[:space:]'); [ -n "$wake" ] || wake=0
+
+# --- the smiths and their errands (herdr x when-sources) ---
+SMITHS_JSON="$(herdr agent list 2>/dev/null | python3 -c "
+import json,sys
+try:
+    d=json.load(sys.stdin)
+    out=[]
+    for a in d['result']['agents']:
+        n=a.get('name')
+        if n in ('odrerir','sessrumnir-cloth','hall-button'):
+            out.append({'smith':n,'state':a.get('agent_status','unknown'),'pane':a.get('pane_id','')})
+    print(json.dumps(out))
+except Exception:
+    print('[]')
+" 2>/dev/null)"
+[ -n "$SMITHS_JSON" ] || SMITHS_JSON='[]'
+
+errands=""
+if [ -x "$ROOT/.agents/backend/fm-procevent.sh" ]; then
+  errands=$("$ROOT/.agents/backend/fm-procevent.sh" list 2>/dev/null | awk '{print $1}' | grep '^when-' | sed 's/^when-//' | sort -u | tr '\n' ' ')
+fi
+
+err=$(printf '%s\n' "$errands" | python3 -c "import json,sys; print(json.dumps(sys.stdin.read().split()))" 2>/dev/null)
+[ -n "$err" ] || err='[]'
+proj=$(printf '%s\n' "$projects" | python3 -c "import json,sys; print(json.dumps(sys.stdin.read().split()))" 2>/dev/null)
+[ -n "$proj" ] || proj='[]'
+underway=$(printf '%s' "$SMITHS_JSON" | python3 -c "
+import json,sys
+d=json.load(sys.stdin)
+print(json.dumps([x['smith'] for x in d if x['state']=='working']))")
+landed=$(ls "$STATE/eindri-reports/archive/" 2>/dev/null | sed 's/-.*//' | sort -u | tr '\n' ' ')
+landed_json=$(printf '%s\n' "$landed" | python3 -c "import json,sys; print(json.dumps(sys.stdin.read().split()))" 2>/dev/null || echo '[]')
+
+OUT_JSON="$(RUNE_C="$runes" PROJ_N="$(printf '%s' "$projects" | wc -w | tr -d ' ')" LOOM="$loom" WAKE="$wake" \
+ SMITHS="$SMITHS_JSON" ERRANDS="$err" PROJ="$proj" UNDERWAY="$underway" LANDED="$landed_json" python3 -c "
+import json, os
+payload = {
+  'generated_at': os.popen('date -u +%Y-%m-%dT%H:%M:%SZ').read().strip(),
+  'realm': 'wayof',
+  'tally': {
+    'runes': int(os.environ['RUNE_C'] or 0),
+    'projects': int(os.environ['PROJ_N'] or 0),
+    'loom': int(os.environ['LOOM'] or 0),
+    'wake': int(os.environ['WAKE'] or 0),
+    'smiths': len(json.loads(os.environ['SMITHS'])),
+  },
+  'errands_armed': json.loads(os.environ['ERRANDS']),
+  'smiths': json.loads(os.environ['SMITHS']),
+  'ledger': {
+    'underway': json.loads(os.environ['UNDERWAY']),
+    'landed': json.loads(os.environ['LANDED']),
+    'charted': json.loads(os.environ['PROJ']),
+  },
+}
+print(json.dumps(payload, ensure_ascii=False, indent=2))
+")"
+
+mkdir -p "$(dirname "$OUT")"
+printf '%s\n' "$OUT_JSON" > "$OUT"
+printf 'hall-snapshot[1]{generated_at,output}:\n  "%s","%s"\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$OUT"