@zerwiz/ymir 0.1.4 → 0.1.5

package/bin/utgard.sh

@@ -0,0 +1,111 @@
+#!/usr/bin/env bash
+# utgard.sh — the sealed execution barrier (Utgard, the realm outside the wall).
+#
+# Runs an untrusted task inside an ephemeral container: no host root, no network,
+# CPU/RAM/timeout caps, a read-only rootfs, and only the task worktree mounted.
+# A failed run leaves no trace on main. Galdr-style TOON output.
+#
+# Usage:
+#   utgard.sh build [--tag <name>]
+#   utgard.sh status
+#   utgard.sh run <worktree> -- <command...> [--network none|on] [--cpus N] [--memory M] [--timeout S]
+#   utgard.sh sandcastle <args…>   # the sandcastle engine (Docker/Podman/Vercel)
+#   utgard.sh --version
+#
+# Engine: the isolated agent sandbox engine is **sandcastle**
+# (github.com/mattpocock/sandcastle, `@ai-hero/sandcastle`); this script is the
+# sealed Norse shell. `sandcastle` delegates to it; `run` uses utgard-runner.
+#
+# Exit: 0 ok, 1 error, 2 usage, 124 timeout.
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+SANDBOX="$ROOT/.agents/sandbox"
+TAG="${UTGARD_TAG:-utgard-runner:latest}"
+
+usage() { sed -n '2,18p' "$0" | sed 's/^# \{0,1\}//'; }
+
+CMD="${1-}"; shift || true
+case "$CMD" in
+  -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h|--help|"") usage; exit 0 ;;
+esac
+
+# `sandcastle` delegates to the sandbox engine (no docker-daemon requirement —
+# it may use podman or vercel).
+if [ "$CMD" = "sandcastle" ]; then
+  command -v npx >/dev/null 2>&1 || { printf 'error: npx not found\nhelp: install node/npm to use sandcastle\n' >&2; exit 1; }
+  exec npx --yes @ai-hero/sandcastle "$@"
+fi
+
+# shellcheck source=bin/ymir-platform.sh
+. "$SCRIPT_DIR/ymir-platform.sh"
+ENGINE="$(ymir_container_engine)" || {
+  printf 'error: no container engine (docker/podman) reachable\nhelp: install Docker or Podman, or set YMIR_CONTAINER_ENGINE to the one you use\n' >&2
+  exit 1
+}
+
+case "$CMD" in
+  build)
+    while [ $# -gt 0 ]; do case "$1" in --tag) TAG=${2-}; shift 2 ;; *) shift ;; esac; done
+    [ -f "$SANDBOX/Dockerfile.utgard" ] || { printf 'error: Dockerfile.utgard missing\n' >&2; exit 1; }
+    if "$ENGINE" build -q -f "$SANDBOX/Dockerfile.utgard" -t "$TAG" "$SANDBOX" >/dev/null 2>&1; then
+      printf 'utgard[1]{image,status}:\n  "%s","built"\n' "$TAG"
+    else
+      printf 'error: build failed for %s\nhelp: run %s build -f .agents/sandbox/Dockerfile.utgard -t %s .agents/sandbox\n' "$TAG" "$ENGINE" "$TAG" >&2
+      exit 1
+    fi
+    ;;
+
+  status)
+    if "$ENGINE" image inspect "$TAG" >/dev/null 2>&1; then
+      printf 'utgard[1]{image,status,net_default,caps}:\n  "%s","ready","none","cpus+mem+timeout"\n' "$TAG"
+    else
+      printf 'utgard[1]{image,status,net_default,caps}:\n  "%s","missing","none","cpus+mem+timeout"\n' "$TAG"
+      printf 'help[1]: bin/utgard.sh build\n'
+    fi
+    ;;
+
+  run)
+    WT=""
+    while [ $# -gt 0 ]; do
+      case "$1" in
+        --) shift; break ;;
+        --network) NET=${2-none}; shift 2 ;;
+        --cpus) CPUS=${2-1.0}; shift 2 ;;
+        --memory) MEM=${2-512m}; shift 2 ;;
+        --timeout) TO=${2-30}; shift 2 ;;
+        *) WT=$1; shift ;;
+      esac
+    done
+    [ -n "$WT" ] || { printf 'error: run needs a worktree path\nhelp: bin/utgard.sh run <worktree> -- <command>\n' >&2; exit 2; }
+    [ -d "$WT" ] || { printf 'error: worktree not found: %s\n' "$WT" >&2; exit 1; }
+    [ "$#" -gt 0 ] || { printf 'error: run needs a command after --\n' >&2; exit 2; }
+    WT="$(cd "$WT" && pwd)"
+    NET="${NET:-none}"; CPUS="${CPUS:-1.0}"; MEM="${MEM:-512m}"; TO="${TO:-30}"
+    UID_GID="$(id -u):$(id -g)"
+    "$ENGINE" image inspect "$TAG" >/dev/null 2>&1 || { printf 'error: image %s missing\nhelp: bin/utgard.sh build\n' "$TAG" >&2; exit 1; }
+    # Rootless Podman maps the host user differently: use --userns=keep-id so the
+    # mounted worktree stays writable by the invoking user; Docker keeps --user.
+    ARGS=(run --rm --network "$NET" --cpus "$CPUS" -m "$MEM"
+          --security-opt no-new-privileges
+          --read-only --tmpfs /tmp:rw,size=64m)
+    if ymir_rootless_podman; then
+      ARGS+=(--userns=keep-id)
+    else
+      ARGS+=(--user "$UID_GID")
+    fi
+    # `:Z` relabels the bind mount on enforcing-SELinux hosts (Fedora), else empty.
+    ARGS+=(-v "$WT":/sandbox/workspace"$(ymir_volume_suffix)" -w /sandbox/workspace "$TAG" bash -lc "$*")
+    timeout "$TO" "$ENGINE" "${ARGS[@]}"
+    rc=$?
+    [ "$rc" = 124 ] && { printf 'error: utgard run exceeded %ss timeout (sealed)\n' "$TO" >&2; exit 124; }
+    exit "$rc"
+    ;;
+
+  *)
+    printf 'error: unknown command %s\nhelp: bin/utgard.sh [build|status|run|--version]\n' "$CMD" >&2
+    exit 2 ;;
+esac

package/bin/valhalla.sh

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+# valhalla.sh — the process hall (Valhalla). List, inspect, revive, and read logs
+# of the fleet's daemons across PM2, Docker, and systemd. Deterministic: every
+# action dispatches to the owning manager, never an ad-hoc shell. Galdr-style TOON.
+#
+# Usage:
+#   valhalla.sh list
+#   valhalla.sh status <id>
+#   valhalla.sh restart <id> | stop <id> | start <id>
+#   valhalla.sh logs <id> [n]
+#   valhalla.sh --version
+#
+# ids: pm2:<name>, docker:<name>, systemd:<unit>
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=bin/ymir-platform.sh
+. "$SCRIPT_DIR/ymir-platform.sh"
+# Docker or rootless Podman (Fedora). Empty when neither binary exists.
+ENGINE="$(ymir_container_engine_name 2>/dev/null || true)"
+
+usage() { sed -n '2,14p' "$0" | sed 's/^# \{0,1\}//'; }
+
+CMD="${1-}"; shift || true
+case "$CMD" in
+  -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h|--help|"") usage; exit 0 ;;
+esac
+
+id_status() { # id -> "status"
+  local id=$1 mgr=${1%%:*} name=${1#*:}
+  case "$mgr" in
+    pm2) pm2 jlist 2>/dev/null | python3 -c 'import json,sys
+try: d=json.load(sys.stdin)
+except: d=[]
+name=sys.argv[1]
+for p in d:
+    if p.get("name")==name: print(p.get("pm2_env",{}).get("status","?")); break' "$name" ;;
+    docker) "${ENGINE:-docker}" inspect -f '{{.State.Status}}' "$name" 2>/dev/null | head -1 ;;
+    systemd) systemctl is-active "$name" 2>/dev/null ;;
+  esac
+}
+
+case "$CMD" in
+  list)
+    rows=()
+    # PM2
+    if command -v pm2 >/dev/null 2>&1; then
+      while IFS=$'\t' read -r name status cpu mem restarts uptime; do
+        [ -n "$name" ] && rows+=("pm2:$name|pm2|$name|$status|$cpu|$mem|$restarts|$uptime")
+      done < <(pm2 jlist 2>/dev/null | python3 -c "
+import json,sys
+try: d=json.load(sys.stdin)
+except: d=[]
+for p in d:
+    e=p.get('pm2_env',{}); m=p.get('monit',{})
+    print('\t'.join([p.get('name',''),e.get('status',''),str(m.get('cpu',0)),str(round(m.get('memory',0)/1e6)),str(e.get('restart_time',0)),str(int((__import__('time').time()*1000-e.get('pm_uptime',__import__('time').time()*1000))/1000))]))")
+    fi
+    # Containers — Docker or rootless Podman (Fedora); quadlets appear here too.
+    if [ -n "$ENGINE" ] && "$ENGINE" info >/dev/null 2>&1; then
+      while IFS=$'\t' read -r name status; do
+        [ -n "$name" ] && rows+=("docker:$name|$ENGINE|$name|$status|0|0|0|0")
+      done < <("$ENGINE" ps --format '{{.Names}}\t{{.State}}' 2>/dev/null)
+    fi
+    # systemd (user + system), running services only, capped
+    if command -v systemctl >/dev/null 2>&1; then
+      while IFS=" " read -r unit load state sub desc; do
+        case "$unit" in *.service) unit=${unit%.service}; rows+=("systemd:$unit|systemd|$unit|$state|0|0|0|0") ;; esac
+      done < <(systemctl list-units --type=service --state=running --no-legend --no-pager 2>/dev/null | head -20)
+      # Quadlet-generated user units (Podman): /etc or ~/.config/containers/systemd
+      while IFS=" " read -r unit load state sub desc; do
+        case "$unit" in *.service) unit=${unit%.service}; rows+=("systemd:$unit|systemd|$unit|$state|0|0|0|0") ;; esac
+      done < <(systemctl --user list-units --type=service --state=running --no-legend --no-pager 2>/dev/null | head -20)
+    fi
+    printf 'processes[%s]{id,manager,name,status,cpu,mem,restarts,uptime}:\n' "${#rows[@]}"
+    for r in "${rows[@]}"; do IFS='|' read -r id mgr name st cpu mem rs up <<<"$r"; printf '  "%s","%s","%s","%s",%s,%s,%s,%s\n' "$id" "$mgr" "$name" "$st" "$cpu" "$mem" "$rs" "$up"; done
+    ;;
+
+  status)
+    id=${1-}; [ -n "$id" ] || { printf 'error: status needs an id (pm2:<name>|docker:<name>|systemd:<unit>)\n' >&2; exit 2; }
+    st=$(id_status "$id"); [ -n "$st" ] || { printf 'error: not found: %s\n' "$id" >&2; exit 1; }
+    printf 'process[1]{id,status}:\n  "%s","%s"\n' "$id" "$st"
+    ;;
+
+  restart|stop|start)
+    id=${1-}; [ -n "$id" ] || { printf 'error: %s needs an id\n' "$CMD" >&2; exit 2; }
+    mgr=${id%%:*}; name=${id#*:}
+    case "$mgr" in
+      pm2) pm2 "$CMD" "$name" >/dev/null 2>&1 && printf 'process[1]{id,action,ok}:\n  "%s","%s","yes"\n' "$id" "$CMD" || { printf 'error: pm2 %s failed\n' "$CMD" >&2; exit 1; } ;;
+      docker)
+        case "$CMD" in
+          stop) "${ENGINE:-docker}" stop "$name" >/dev/null 2>&1 ;;
+          start) "${ENGINE:-docker}" start "$name" >/dev/null 2>&1 ;;
+          restart) "${ENGINE:-docker}" restart "$name" >/dev/null 2>&1 ;;
+        esac && printf 'process[1]{id,action,ok}:\n  "%s","%s","yes"\n' "$id" "$CMD" || { printf 'error: %s %s failed\n' "${ENGINE:-docker}" "$CMD" >&2; exit 1; } ;;
+      systemd) systemctl "$CMD" "$name" >/dev/null 2>&1 && printf 'process[1]{id,action,ok}:\n  "%s","%s","yes"\n' "$id" "$CMD" || { printf 'error: systemctl %s failed (needs privilege?)\n' "$CMD" >&2; exit 1; } ;;
+      *) printf 'error: unknown manager %s\nhelp: id is pm2:<name>|docker:<name>|systemd:<unit>\n' "$mgr" >&2; exit 2 ;;
+    esac
+    ;;
+
+  logs)
+    id=${1-}; n=${2:-30}; [ -n "$id" ] || { printf 'error: logs needs an id\n' >&2; exit 2; }
+    mgr=${id%%:*}; name=${id#*:}
+    printf 'logs[1]{id,lines}:\n  "%s",%s\n' "$id" "$n"
+    case "$mgr" in
+      pm2) pm2 logs "$name" --lines "$n" --nostream 2>/dev/null | tail -n "$n" ;;
+      docker) "${ENGINE:-docker}" logs --tail "$n" "$name" 2>&1 | tail -n "$n" ;;
+      systemd) journalctl -u "$name" -n "$n" --no-pager 2>/dev/null ;;
+      *) printf 'error: unknown manager %s\n' "$mgr" >&2; exit 2 ;;
+    esac
+    ;;
+
+  *) printf 'error: unknown command %s\nhelp: bin/valhalla.sh [list|status|restart|stop|start|logs|--version]\n' "$CMD" >&2; exit 2 ;;
+esac

package/bin/valknut-load.sh

@@ -0,0 +1,260 @@
+#!/usr/bin/env bash
+# valknut-load.sh — Valknut, the knot that binds the repo distro into each tool's
+# load path. Galdr-style: TOON output, structured errors, no prompts, idempotent.
+#
+# The repo is the source of truth: agents live in `.agents/agents/`, skills in
+# `.agents/skills/`, Pi extensions in `.pi/extensions/`, the backend in
+# `bin/` + `.agents/backend/`. This command binds them where each harness looks.
+#
+# Usage:
+#   bin/valknut-load.sh [--opencode] [--pi] [--global] [--status] [--all]
+#   bin/valknut-load.sh --version | -v
+#
+# Exit: 0 ok, 1 error, 2 usage.
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+AGENTS="$ROOT/.agents/agents"
+PI_LOCAL="$ROOT/.pi/agents"
+PI_GLOBAL="${HOME}/.pi/agent/agents"
+# Shared Pi extensions have ONE home: ${HOME}/.pi/agent/extensions/ (see
+# galdr/assets/harness-integration/README.md). The repo keeps their SOURCE at
+# .pi/shared/extensions/ — never at .pi/extensions/, because an extension present
+# in both load paths makes pi exit with a tool-name conflict and no agent can be
+# seated. This loader DEPLOYS that source into the single home.
+PI_EXT_SRC="$ROOT/.pi/shared/extensions"
+PI_EXT_HOME="${HOME}/.pi/agent/extensions"
+OC_LOCAL="$ROOT/.opencode/agent"
+SKILLS="$ROOT/.agents/skills"
+
+usage() {
+  sed -n '2,16p' "$0" | sed 's/^# \{0,1\}//'
+}
+
+for a in "$@"; do
+  case "$a" in
+    -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+    -h|--help) usage; exit 0 ;;
+  esac
+done
+
+MODE_OPENCODE=0; MODE_PI=0; MODE_GLOBAL=0; MODE_STATUS=0
+for a in "$@"; do
+  case "$a" in
+    --opencode) MODE_OPENCODE=1 ;;
+    --pi|--agents) MODE_PI=1 ;;
+    --global) MODE_GLOBAL=1 ;;
+    --status) MODE_STATUS=1 ;;
+    --all) MODE_OPENCODE=1; MODE_PI=1 ;;
+    *) printf 'error: unknown flag %s\nhelp: bin/valknut-load.sh [--opencode|--pi|--global|--status|--all]\n' "$a" >&2; exit 2 ;;
+  esac
+done
+[ $((MODE_OPENCODE + MODE_PI + MODE_STATUS)) -eq 0 ] && { MODE_OPENCODE=1; MODE_PI=1; }
+
+if [ ! -d "$AGENTS" ]; then
+  printf 'error: agents dir not found: %s\nhelp: expected .agents/agents/ inside %s\n' "$AGENTS" "$ROOT"
+  exit 1
+fi
+
+# ── machine config, rendered from its example ────────────────────────────────
+# opencode.json and .pi/mcp.json must contain ABSOLUTE paths, so they cannot be
+# tracked — a tracked copy would hand every operator the previous one's home.
+# They are rendered from the shipped *.example with the real $HOME and root.
+#
+# TWO WRITERS touch opencode.json: this loader, and `bin/agents-config.sh apply`
+# (which owns the ROSTER — providers and per-agent models, from
+# config/agents.yaml). A blind render here DELETED the roster's work: the Apodex
+# provider lived only in the live file and vanished on the next loader run. So
+# this merges and never overwrites: missing keys are added, existing ones are
+# left alone, and the skills tree is ensured. A live value is never lost, from
+# either writer. Seeding happens only when the target is absent.
+#
+# Returns one of: seeded | merged(<what>) | unchanged | kept | absent.
+config_out() {  # <rendered-json-or-text> <target>
+  local ex=$1 out=$2
+  [ -r "$ex" ] || { printf 'absent'; return 0; }
+  python3 - "$ex" "$out" "$HOME" "$ROOT" <<'PY'
+import json, os, sys
+
+ex, out, home, root = sys.argv[1:5]
+raw = open(ex).read().replace("__YMIR_HOME__", home).replace("__YMIR_ROOT__", root)
+
+def write(text):
+    with open(out, "w") as fh:
+        fh.write(text)
+
+try:
+    want = json.loads(raw)
+except Exception:
+    # Not JSON (or not yet): seed a missing file, but never overwrite a live one.
+    if os.path.exists(out):
+        print("kept")
+    else:
+        write(raw); print("seeded")
+    raise SystemExit
+
+if not os.path.exists(out):
+    write(json.dumps(want, indent=2) + "\n"); print("seeded"); raise SystemExit
+
+cur = json.load(open(out))
+added = []
+
+def merge(cur, want, path=""):
+    for k, v in want.items():
+        if k not in cur:
+            cur[k] = v; added.append(path + k)
+        elif isinstance(v, dict) and isinstance(cur[k], dict):
+            merge(cur[k], v, path + k + ".")
+
+merge(cur, want)
+
+# This loader's own contract: the ONE skills tree must stay reachable.
+paths = cur.setdefault("skills", {}).setdefault("paths", [])
+if ".agents/skills" not in paths:
+    paths.append(".agents/skills"); added.append("skills.paths")
+
+if not added:
+    print("unchanged"); raise SystemExit
+write(json.dumps(cur, indent=2) + "\n")
+print("merged(%s)" % ",".join(added[:4]))
+PY
+}
+
+declare -a T P S
+add() { T+=("$1"); P+=("$2"); S+=("$3"); }
+
+link_agent_dir() {  # <target-dir> <rel-prefix>
+  local target=$1 prefix=$2 made=0
+  mkdir -p "$target" || return 1
+  local f base
+  for f in "$AGENTS"/*.md; do
+    [ -e "$f" ] || continue
+    base=$(basename "$f")
+    ln -sfn "${prefix}/${base}" "$target/$base" 2>/dev/null || return 1
+    made=$((made + 1))
+  done
+  printf '%s' "$made"
+}
+
+# Skills are ONE tree (`.agents/skills/`). Each harness reaches it its own way:
+#   opencode — `skills.paths: [".agents/skills"]` in opencode.json (rendered below)
+#   pi       — discovery, natively: it walks up from the cwd looking for
+#              `.agents/skills` (and `~/.agents/skills`), so it needs NO link,
+#              and a second root under `.pi/` would only invite double-loading
+#   claude · codex · cursor — project skills live under the harness dir, so each
+#              gets `<harness>/skills -> ../.agents/skills`
+link_skills() {  # <harness-dir>  → binds <harness-dir>/skills
+  local dir=$1
+  [ -d "$dir" ] || return 1
+  ln -sfn ../.agents/skills "$dir/skills" 2>/dev/null || return 1
+  printf 'bound'
+}
+
+if [ "$MODE_STATUS" = 1 ]; then
+  [ -d "$OC_LOCAL" ] && add opencode "$OC_LOCAL" "$(ls "$OC_LOCAL"/*.md 2>/dev/null | wc -l | tr -d ' ') files" || add opencode "$OC_LOCAL" absent
+  [ -d "$PI_LOCAL" ] && add pi-local "$PI_LOCAL" "$(ls "$PI_LOCAL"/*.md 2>/dev/null | wc -l | tr -d ' ') links" || add pi-local "$PI_LOCAL" absent
+  [ -d "$PI_GLOBAL" ] && add pi-global "$PI_GLOBAL" "$(ls "$PI_GLOBAL"/*.md 2>/dev/null | wc -l | tr -d ' ') links" || add pi-global "$PI_GLOBAL" absent
+  add agents-source "$AGENTS" "$(ls "$AGENTS"/*.md 2>/dev/null | wc -l | tr -d ' ') files"
+  add opencode-skills "$SKILLS" "$(grep -q '\.agents/skills' "$ROOT/opencode.json" 2>/dev/null && printf 'via skills.paths' || printf 'absent')"
+  add pi-skills "$SKILLS" "native discovery (walks up to .agents/skills)"
+  for hd in .claude .codex .cursor; do
+    [ -d "$ROOT/$hd" ] || continue
+    [ -L "$ROOT/$hd/skills" ] && add "$hd-skills" "$ROOT/$hd/skills" linked || add "$hd-skills" "$ROOT/$hd/skills" absent
+  done
+fi
+
+if [ "$MODE_OPENCODE" = 1 ]; then
+  add opencode-config "$ROOT/opencode.json" "$(config_out "$ROOT/opencode.json.example" "$ROOT/opencode.json")"
+  if [ -d "$OC_LOCAL" ]; then
+    n=$(ls "$OC_LOCAL"/*.md 2>/dev/null | wc -l | tr -d ' ')
+    add opencode "$OC_LOCAL" "native ($n agents)"
+  else
+    add opencode "$OC_LOCAL" "ERROR absent"
+  fi
+  # The skills tree reaches opencode through its config, not a link.
+  if [ -f "$ROOT/opencode.json" ] && grep -q '\.agents/skills' "$ROOT/opencode.json"; then
+    add opencode-skills "$SKILLS" "via skills.paths"
+  else
+    add opencode-skills "$SKILLS" "ERROR not in opencode.json"
+  fi
+fi
+
+if [ "$MODE_PI" = 1 ]; then
+  add pi-mcp "$ROOT/.pi/mcp.json" "$(config_out "$ROOT/.pi/mcp.json.example" "$ROOT/.pi/mcp.json")"
+  n=$(link_agent_dir "$PI_LOCAL" "../../.agents/agents") && add pi-local "$PI_LOCAL" "bound ($n links)" || add pi-local "$PI_LOCAL" "ERROR"
+  if [ "$MODE_GLOBAL" = 1 ]; then
+    g=$(link_agent_dir "$PI_GLOBAL" "$AGENTS") && add pi-global "$PI_GLOBAL" "bound ($g links)" || add pi-global "$PI_GLOBAL" "ERROR"
+  fi
+  # Deploy the shared extensions into their single home. Copy, not link: a
+  # broken link would silently disable a tool, and pi reads the file directly.
+  # Idempotent — identical files are left untouched.
+  if [ -d "$PI_EXT_SRC" ]; then
+    mkdir -p "$PI_EXT_HOME" 2>/dev/null
+    dep_n=0
+    for f in "$PI_EXT_SRC"/*.ts; do
+      [ -e "$f" ] || continue
+      b=$(basename "$f")
+      if [ -f "$PI_EXT_HOME/$b" ] && cmp -s "$f" "$PI_EXT_HOME/$b"; then continue; fi
+      cp -f "$f" "$PI_EXT_HOME/$b" && dep_n=$((dep_n+1))
+    done
+    add pi-extensions "$PI_EXT_HOME" "$dep_n deployed (shared single home)"
+  fi
+fi
+
+# Agents for every harness: `.agents/agents/` is canonical, and each harness dir
+# is a directory of symlinks into it (Rule 02). Pi and opencode have their own
+# bindings above; claude, codex and cursor are bound here, so no harness is left
+# holding a hand-made subset. opencode names an agent by its `name:` frontmatter
+# (bragi.md -> bragi-marketer.md), the others by the profile file name.
+agent_name_of() {  # <profile> -> the frontmatter `name:`
+  sed -n 's/^name:[[:space:]]*//p' "$1" 2>/dev/null | head -1 | tr -d '[:space:]'
+}
+link_agents() {  # <harness-dir> [short]
+  local dir=$1 short=${2:-} made=0 f base want
+  [ -d "$(dirname "$dir")" ] || return 1
+  mkdir -p "$dir" || return 1
+  for f in "$AGENTS"/*.md; do
+    [ -e "$f" ] || continue
+    base=$(basename "$f")
+    if [ "$short" = "short" ]; then
+      want="$(agent_name_of "$f")"; [ -n "$want" ] || continue; want="$want.md"
+    else
+      want="$base"
+    fi
+    ln -sfn "../../.agents/agents/$base" "$dir/$want" 2>/dev/null || return 1
+    made=$((made + 1))
+  done
+  printf '%s' "$made"
+}
+if [ "$MODE_STATUS" = 0 ]; then
+  # Skills for the CLIs whose project scope is their own directory. Pi needs no
+  # link (it discovers `.agents/skills` by walking up); opencode reaches that
+  # tree through `skills.paths`. claude, codex and cursor each get one link, so
+  # all of them read the ONE skills tree.
+  linked=""
+  for hd in .claude .codex .cursor; do
+    [ -d "$ROOT/$hd" ] || continue
+    link_skills "$ROOT/$hd" >/dev/null 2>&1 && linked="$linked $hd"
+  done
+  [ -n "$linked" ] && add harness-skills "$SKILLS" "linked into:$linked"
+
+  # …and AGENTS for the same harnesses, plus opencode, so every tool loads every
+  # agent — never a hand-made subset.
+  for hd in .claude .codex .cursor; do
+    [ -d "$ROOT/$hd" ] || continue
+    n=$(link_agents "$ROOT/$hd/agents") || n=0
+    add "${hd#.}-agents" "$ROOT/$hd/agents" "bound ($n)"
+  done
+  if [ -d "$ROOT/.opencode" ]; then
+    n=$(link_agents "$ROOT/.opencode/agent" short) || n=0
+    add opencode-agents "$ROOT/.opencode/agent" "bound ($n)"
+  fi
+fi
+
+printf 'loaders[%s]{tool,path,status}:\n' "${#T[@]}"
+for i in "${!T[@]}"; do
+  printf '  "%s","%s","%s"\n' "${T[$i]}" "${P[$i]}" "${S[$i]}"
+done
+printf 'help[1]: run `bin/valknut-load.sh --status` to inspect bindings\n'

package/bin/vor-crew-state.sh

@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+# vor-crew-state.sh - deterministic read of an Eindri worker's CURRENT state.
+#
+# Vör ("awareness of what is") reconciles the possibly-stale append-only
+# state/<id>.status event log against the authoritative endpoint liveness read
+# from state/<id>.meta, and emits one stable, parseable, token-tight line:
+#
+#   state: <working|parked|done|blocked|paused|failed|unknown> · source: <backend|status-log|none> · <detail>
+#
+# Why this exists: state/<id>.status is an append-only, best-effort event log,
+# so `tail -1` reports the last EVENT, not the current STATE. This helper reads
+# the rendered backend endpoint (tmux/herdr) recorded in the task meta and
+# reconciles the log against it. It never shells out to a model, never infers
+# from a tail alone, and is read-only.
+#
+# Ported from the upstream distro crew-state reconciliation for plan 29
+# (docs/plans/29-brokk-distro-runtime.md).
+#
+# Usage: vor-crew-state.sh <task-id>
+# Exits 0 on any successful read regardless of state; exit 2 on a usage error.
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="${BROKK_ROOT_OVERRIDE:-$(cd "$SCRIPT_DIR/.." && pwd)}"
+BROKK_HOME="${BROKK_HOME:-${BROKK_ROOT_OVERRIDE:-$ROOT}}"
+STATE="${BROKK_STATE_OVERRIDE:-$BROKK_HOME/state}"
+PAUSED_VERB="${BROKK_PAUSED_VERB:-paused}"
+SEP=' · '
+
+ID=${1:-}
+[ -n "$ID" ] || { echo "usage: vor-crew-state.sh <task-id>" >&2; exit 2; }
+
+emit() {  # <state> <source> [detail]
+  local line="state: $1${SEP}source: $2"
+  [ -n "${3:-}" ] && line="$line${SEP}$3"
+  printf '%s\n' "$line"
+  exit 0
+}
+
+META="$STATE/$ID.meta"
+LOG="$STATE/$ID.status"
+[ -f "$META" ] || emit unknown none "no metadata for $ID"
+
+meta_value() {  # <key>
+  grep "^$1=" "$META" 2>/dev/null | tail -1 | cut -d= -f2- || true
+}
+
+WT=$(meta_value worktree)
+KIND=$(meta_value kind); KIND=${KIND:-ship}
+BACKEND=$(meta_value backend); BACKEND=${BACKEND:-tmux}
+TARGET=$(meta_value window)
+
+if [ -z "$WT" ] || [ ! -d "$WT" ]; then
+  emit unknown none "worktree gone (torn down?)"
+fi
+
+log_last_line() {
+  [ -f "$LOG" ] || return 1
+  grep -v '^[[:space:]]*$' "$LOG" 2>/dev/null | tail -1
+}
+
+LOG_LINE=$(log_last_line || true)
+LOG_VERB=""
+if [ -n "$LOG_LINE" ]; then
+  LOG_VERB=${LOG_LINE%%:*}
+  LOG_VERB=$(printf '%s' "$LOG_VERB" | tr -d '[:space:]')
+fi
+
+# Map a status-log verb onto a canonical state. `resolved` closes a decision
+# and is deliberately not a state.
+map_log_state() {  # <verb>
+  case "$1" in
+    working) echo working ;;
+    needs-decision) echo parked ;;
+    blocked) echo blocked ;;
+    done) echo done ;;
+    failed) echo failed ;;
+    "$PAUSED_VERB") echo "$PAUSED_VERB" ;;
+    *) echo unknown ;;
+  esac
+}
+
+log_detail() {
+  printf '%s' "${LOG_LINE#*:}" | sed 's/^[[:space:]]*//'
+}
+
+backend_alive() {  # <backend> <target>
+  local backend=$1 target=$2
+  [ -n "$target" ] || return 1
+  case "$backend" in
+    tmux) tmux display-message -p -t "$target" '#{pane_id}' >/dev/null 2>&1 ;;
+    herdr) herdr pane get "$target" >/dev/null 2>&1 ;;
+    *) return 1 ;;
+  esac
+}
+
+if [ -z "$TARGET" ]; then
+  # No endpoint recorded: fall back to the status log only when it maps to a
+  # recognized run-state, so a trailing `resolved:` never becomes the state.
+  if [ -n "$LOG_VERB" ]; then
+    LOG_STATE=$(map_log_state "$LOG_VERB")
+    if [ "$LOG_STATE" != unknown ]; then
+      emit "$LOG_STATE" status-log "$(log_detail)"
+    fi
+  fi
+  emit unknown none "no backend target recorded"
+fi
+
+if backend_alive "$BACKEND" "$TARGET"; then
+  LOG_STATE=unknown
+  [ -n "$LOG_VERB" ] && LOG_STATE=$(map_log_state "$LOG_VERB")
+  case "$LOG_STATE" in
+    done|failed) emit "$LOG_STATE" status-log "$(log_detail)" ;;
+    working|parked|blocked|"$PAUSED_VERB") emit "$LOG_STATE" status-log "$(log_detail)" ;;
+    *) emit working backend "endpoint alive: $TARGET" ;;
+  esac
+fi
+
+# Endpoint is gone. A terminal log verdict is durable truth; otherwise the
+# crew has no current-state source.
+case "$(map_log_state "$LOG_VERB")" in
+  done|failed) emit "$(map_log_state "$LOG_VERB")" status-log "$(log_detail)" ;;
+esac
+emit unknown none "backend target gone: $TARGET"

package/bin/wedge-notify.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# wedge-notify.sh — the Ymir wedge-alarm notifier.
+#
+# The away-mode supervisor (bin/fm-supervise-daemon.sh) raises a loud, rate-
+# limited alarm when an escalation cannot be delivered into the primary pane past
+# FM_MAX_DEFER_SECS — the "wedge" case, where the pane itself is the thing that is
+# broken and no digest can reach the Allfather. Its alarm routes through a
+# notifier seam (`FM_WEDGE_ALARM_EXEC <channel> <summary>`) so a channel can reach
+# him when every pane is unreadable.
+#
+# This is that notifier on an Omarchy host: an Omarchy desktop notification, and
+# the same line appended to a durable file so a missed popup is still found.
+#
+# Usage (as the seam):  FM_WEDGE_ALARM_EXEC=bin/wedge-notify.sh
+#   bin/wedge-notify.sh <channel> <summary>
+# Exit: 0 fired (or discarded), 1 could not fire at all.
+set -u
+
+CHANNEL="${1:-unknown}"
+SUMMARY="${2:-}"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+STATE_DIR="${BROKK_STATE_OVERRIDE:-$ROOT/state}"
+LOG="$STATE_DIR/wedge-alarm.log"
+
+# "discard" is the library-mode default so no test posts a real notification.
+[ "$CHANNEL" = "discard" ] && exit 0
+[ -n "$SUMMARY" ] || SUMMARY="an escalation could not reach the pane"
+
+mkdir -p "$STATE_DIR" 2>/dev/null || true
+printf '%s\twedge\t%s\t%s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$CHANNEL" "$SUMMARY" >>"$LOG" 2>/dev/null || true
+
+fired=0
+# Speak through the one voice: bin/ymir-say.sh owns the desktop manner.
+if [ -x "$ROOT/bin/ymir-say.sh" ]; then
+  "$ROOT/bin/ymir-say.sh" --mark-alarm "wedge: escalation stuck" "$SUMMARY" >/dev/null 2>&1 && fired=1
+elif command -v omarchy-notification-send >/dev/null 2>&1; then
+  omarchy-notification-send -u critical -g "" "Ymir wedge: escalation stuck" "$SUMMARY" >/dev/null 2>&1 && fired=1
+elif command -v notify-send >/dev/null 2>&1; then
+  notify-send -u critical "Ymir wedge: escalation stuck" "$SUMMARY" >/dev/null 2>&1 && fired=1
+fi
+
+# The durable line above already recorded it; a silent host is not a failure of
+# the record, so exit 0 when the log was written even if no popup could show.
+[ "$fired" = 1 ] && exit 0
+[ -s "$LOG" ] && exit 0
+exit 1