@zerwiz/ymir 0.1.4 → 0.1.7

package/bin/herdr-ensure.sh

@@ -0,0 +1,104 @@
+#!/usr/bin/env bash
+# herdr-ensure.sh — Þjazi: guarantee the terminal backend Ymir needs.
+#
+# Ymir is a herdr-first system: agent panes need a backend with Þjazi protocol
+# 14+ (presentation spaces need herdr 0.8.0+). This helper detects, verifies the
+# version, and installs when absent — in user space. tmux remains an acceptable
+# backend, so a host with tmux is not treated as broken.
+#
+# Usage:
+#   bin/herdr-ensure.sh status            # what is present, and does it meet the floor
+#   bin/herdr-ensure.sh ensure [--install]
+#   bin/herdr-ensure.sh --version
+#
+# Output: Galdr TOON. Exit 0 when a usable backend exists, 1 when none does.
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+MIN_PROTOCOL=14          # agent panes
+MIN_SPACES="0.8.0"       # presentation spaces
+PINNED_INSTALLER="$ROOT/.agents/backend/fm-install-herdr.sh"
+
+have() { command -v "$1" >/dev/null 2>&1; }
+
+herdr_version() { herdr --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1; }
+
+# version_ge A B -> A >= B
+version_ge() { [ "$(printf '%s\n%s\n' "$2" "$1" | sort -V | head -1)" = "$2" ]; }
+
+status() {
+  local hv="" backend="none" note=""
+  if have herdr; then
+    hv="$(herdr_version)"
+    backend="herdr"
+  elif have tmux; then
+    backend="tmux"
+  fi
+  case "$backend" in
+    herdr)
+      if [ -n "$hv" ] && version_ge "$hv" "$MIN_SPACES"; then
+        note="panes ok (protocol ${MIN_PROTOCOL}+) · presentation spaces ok"
+      else
+        note="present but older than ${MIN_SPACES}; presentation spaces unavailable"
+      fi
+      printf 'thjazi[1]{backend,version,state,note}:\n  "herdr","%s","present","%s"\n' "${hv:-?}" "$note"
+      ;;
+    tmux)
+      printf 'thjazi[1]{backend,version,state,note}:\n  "tmux","%s","present","verified reference backend; herdr preferred for presentation spaces"\n' "$(tmux -V 2>/dev/null | awk '{print $2}')"
+      ;;
+    *)
+      printf 'thjazi[1]{backend,version,state,note}:\n  "none","-","absent","no herdr and no tmux — agent panes cannot be spawned"\n'
+      return 1
+      ;;
+  esac
+  return 0
+}
+
+# One backend, two names: upstream ships `herdr`, the Omarchy/Þjazi layer calls
+# the same binary `hdr`. Alias them so either name reaches the same tool and
+# every script (Ymir, Omarchy) shares one code path — never two.
+link_hdr() {
+  have hdr && return 0
+  local bin
+  bin="$(command -v herdr 2>/dev/null)" || return 0
+  mkdir -p "$HOME/.local/bin" || return 1
+  ln -sf "$bin" "$HOME/.local/bin/hdr" 2>/dev/null || return 1
+}
+
+ensure() {
+  local install="${1:-}"
+  if have herdr; then link_hdr; status; return $?; fi
+  if [ "$install" != "--install" ]; then
+    status
+    printf 'help: bin/herdr-ensure.sh ensure --install  (or install tmux as a fallback)\n'
+    return 1
+  fi
+  # Preferred: the pinned, SHA-verified installer (exact version + protocol check).
+  if [ -x "$PINNED_INSTALLER" ]; then
+    mkdir -p "$HOME/.local/bin"
+    if "$PINNED_INSTALLER" "$HOME/.local/bin" >/dev/null 2>&1 && have herdr; then
+      link_hdr
+      status; return $?
+    fi
+  fi
+  # Fallback: tmux, which Ymir accepts as its verified reference backend.
+  if ! have tmux; then
+    if have pacman; then printf 'help: sudo pacman -S --needed tmux\n' >&2
+    elif have apt-get; then printf 'help: sudo apt-get install -y tmux\n' >&2; fi
+  fi
+  status
+  return $?
+}
+
+case "${1-}" in
+  -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h|--help) sed -n '2,16p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+esac
+
+case "${1-}" in
+  status) status ;;
+  ensure|"") ensure "${2:-}" ;;
+  *) printf 'error: unknown action %s\nhelp: bin/herdr-ensure.sh [status|ensure [--install]]\n' "$1" >&2; exit 2 ;;
+esac

package/bin/herdr-run.sh

@@ -0,0 +1,452 @@
+#!/usr/bin/env bash
+# herdr-run.sh — raise an Eindri in herdr, by the grain that fits the errand.
+#
+# An Eindri is a delegated hand (AGENTS.md; docs/lore.md §II). Two roads seat one,
+# and each fits its own country:
+#
+#   TAB      one tab in this home's workspace. Durable, ordinary, the default.
+#            Use when the work will outlast the moment — a task with a worktree.
+#   SPACE    a disposable workspace holding exactly this one errand, torn down
+#            when it is done. Use when the work should leave no trace in the
+#            workspace you are living in. Needs herdr 0.8.0+ (the projection
+#            floor: below it, projected cleanup can steal the active workspace).
+#
+# And the first law, before either: a SHORT ERRAND IS DONE IN HAND. A question, a
+# one-line check, a lookup — those are answered directly. Only a TASK earns a
+# smith, because a smith costs a context, a seat, and your attention.
+#
+# Hermes' skill is the `ymir` thjazi asset; the role chooser is `bin/eindri-role.sh`.
+#
+# Usage:
+#   bin/herdr-run.sh available                      # can we use herdr right now?
+#   bin/herdr-run.sh worth-a-smith "<errand>"       # is this an errand at all?
+#   bin/herdr-run.sh eindri [NAME] [--role R] [--space] -- "<task>"
+#   bin/herdr-run.sh run <name> -- <command...>     # a command in a pane
+#   bin/herdr-run.sh agent-status                   # who stands, and in what state
+#   bin/herdr-run.sh close-all                      # clear the tabs/panes we made
+#   bin/herdr-run.sh --version
+#
+# Env:
+#   YMIR_HERDR_PANES=0      force inline even inside herdr
+#   YMIR_HERDR_KIND=pi      the agent kind raised for `eindri`
+#   YMIR_HERDR_AGENT_WAIT=1 wait for the Eindri to reach done before returning
+#   YMIR_HERDR_SETTLE=300   seconds to wait for a step before declaring it hung
+set -u
+
+
+VERSION="2.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
+STATE_DIR="${BROKK_STATE_OVERRIDE:-$YMIR_STATE_DIR}"
+TAB_LOG="$STATE_DIR/herdr-seats"
+SETTLE="${YMIR_HERDR_SETTLE:-300}"
+
+case "${1-}" in
+  -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h|--help|"") sed -n '2,32p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+esac
+ACTION="${1:-available}"; shift || true
+
+have() { command -v "$1" >/dev/null 2>&1; }
+
+# herdr --session is the ONLY reliable router: HERDR_SESSION alone silently
+# falls back to whichever server is already bound (Brokk .agents/skills/herdr-panes/assets/herdr-backend.md,
+# "Session targeting"). We always pass the flag explicitly.
+HDR_SESSION="${HERDR_SESSION:-}"
+# One backend, two names: upstream ships `herdr`, the Omarchy/Þjazi layer calls
+# the same binary `hdr`. Resolve once so both hosts share this code path.
+HDR_BIN="${HDR:-$(command -v herdr || command -v hdr || printf 'herdr')}"
+hdr() { if [ -n "$HDR_SESSION" ]; then "$HDR_BIN" --session "$HDR_SESSION" "$@"; else "$HDR_BIN" "$@"; fi; }
+
+can_use_herdr() {
+  [ "${YMIR_HERDR_PANES:-1}" = "1" ] || return 1
+  [ "${HERDR_ENV:-}" = "1" ] || return 1
+  have herdr || have hdr || return 1
+  return 0
+}
+
+current_pane() {
+  printf '%s' "${HERDR_PANE_ID:-}"
+}
+
+# Which workspace this home's children belong in. One workspace per env home;
+# the pane we sit in names it, else the injected workspace id.
+home_workspace() {
+  [ -n "${HERDR_WORKSPACE_ID:-}" ] && { printf '%s' "$HERDR_WORKSPACE_ID"; return 0; }
+  hdr pane current 2>/dev/null | python3 -c '
+import json,sys
+try:
+    d = json.load(sys.stdin); p = d.get("result", {}).get("pane", {})
+    print(p.get("workspace_id") or "")
+except Exception:
+    pass' 2>/dev/null
+}
+
+# The projection floor: a disposable workspace per errand needs herdr 0.8.0+,
+# below which a workspace-emptying close can steal the active workspace.
+space_supported() {
+  local protocol version
+  protocol="$(hdr status --json 2>/dev/null | python3 -c '
+import json,sys
+try:
+    d=json.load(sys.stdin); print((d.get("client") or {}).get("protocol") or "")
+except Exception:
+    pass' 2>/dev/null)"
+  version="$(hdr status --json 2>/dev/null | python3 -c '
+import json,sys
+try:
+    d=json.load(sys.stdin); print((d.get("client") or {}).get("version") or "")
+except Exception:
+    pass' 2>/dev/null)"
+  # protocol 19 is the structural signal for the 0.8.0 floor (0.8.0 reports 19).
+  case "$protocol" in ''|*[!0-9]*) ;; *) [ "$protocol" -ge 19 ] && return 0 ;; esac
+  case "$version" in
+    0.8.*|0.9.*|1.*|[1-9].*) return 0 ;;
+  esac
+  return 1
+}
+
+# The first law: is this worth a smith at all? A question, a lookup, a one-line
+# check is done in hand. A task — work with an artifact, a worktree, a life
+# beyond the answer — earns a seat.
+worth_a_smith() {
+  local text; text="$(printf '%s' "${1:-}" | tr '[:upper:]' '[:lower:]')"
+  [ -n "$text" ] || { printf 'worth[1]{verdict,why}:\n  "no","empty"\n'; return 1; }
+  local words; words="$(printf '%s' "$text" | wc -w | tr -d ' ')"
+  # Interrogative and lookup shapes are answered in hand.
+  case "$text" in
+    *\?*|what\ *|why\ *|when\ *|where\ *|who\ *|how\ many*|how\ much*|show\ me*|tell\ me*|explain\ *|whats\ *|what\'s\ *)
+      printf 'worth[1]{verdict,why}:\n  "no","a question — answer it in hand"\n'; return 1 ;;
+  esac
+  # A task names an artifact or an act of making.
+  case "$text" in
+    *build*|*fix*|*implement*|*refactor*|*write*|*create*|*add*|*migrate*|*port*|*test*|*review*|*research*|*audit*|*plan*|*design*|*document*|*investigate*|*compare*|*draft*|*forge*|*set\ up*|*install*)
+      if [ "$words" -ge 4 ]; then
+        printf 'worth[1]{verdict,why,words}:\n  "yes","a task with an artifact",%s\n' "$words"; return 0
+      fi
+      printf 'worth[1]{verdict,why,words}:\n  "no","too brief to seat a smith",%s\n' "$words"; return 1 ;;
+  esac
+  if [ "$words" -ge 24 ]; then
+    printf 'worth[1]{verdict,why,words}:\n  "yes","substantial errand",%s\n' "$words"; return 0
+  fi
+  printf 'worth[1]{verdict,why,words}:\n  "no","short errand — do it in hand",%s\n' "$words"; return 1
+}
+
+# Seat an Eindri in a TAB of this home's workspace (the durable road).
+# The reply carries result.tab.tab_id and result.root_pane.pane_id.
+seat_tab() {  # <name> <cwd> -> prints "<tab_id> <pane_id>"
+  local name=$1 cwd=$2 ws out
+  ws="$(home_workspace)"
+  if [ -n "$ws" ]; then
+    out="$(hdr tab create --workspace "$ws" --cwd "$cwd" --label "$name" 2>/dev/null)"
+  else
+    out="$(hdr tab create --cwd "$cwd" --label "$name" 2>/dev/null)"
+  fi
+  printf '%s' "$out" | python3 -c '
+import json,sys
+try:
+    d=json.load(sys.stdin); r=d.get("result", {})
+    tab=(r.get("tab") or {}).get("tab_id") or ""
+    pane=(r.get("root_pane") or {}).get("pane_id") or ""
+    print(tab, pane)
+except Exception:
+    pass' 2>/dev/null
+}
+
+# Seat an Eindri in a DISPOSABLE workspace (the projection road). One errand,
+# one space, torn down when the errand ends.
+seat_space() {  # <name> <cwd> -> prints "<workspace_id> <tab_id> <pane_id>"
+  local name=$1 cwd=$2 out
+  out="$(hdr workspace create --cwd "$cwd" --label "ymir:$name" 2>/dev/null)"
+  printf '%s' "$out" | python3 -c '
+import json,sys
+try:
+    d=json.load(sys.stdin); r=d.get("result", {})
+    w=r.get("workspace", r)
+    ws=w.get("workspace_id") or w.get("id") or ""
+    tab=(r.get("tab") or {}).get("tab_id") or ""
+    pane=(r.get("root_pane") or {}).get("pane_id") or ""
+    print(ws, tab, pane)
+except Exception:
+    pass' 2>/dev/null
+}
+
+first_pane_of_tab() {  # <tab-id> -> pane id
+  hdr tab get "$1" 2>/dev/null | python3 -c '
+import json,sys
+try:
+    d=json.load(sys.stdin); r=d.get("result",{}); t=r.get("tab", r)
+    panes=t.get("panes") or []
+    print(panes[0].get("pane_id") if panes else (t.get("pane_id") or ""))
+except Exception:
+    pass' 2>/dev/null
+}
+
+# A pane to split when we are NOT sitting inside herdr: the active pane of this
+# home's workspace. Inside herdr, the current pane is used directly.
+home_pane() {
+  local ws at
+  ws="$(home_workspace)"; [ -n "$ws" ] || return 1
+  at="$(hdr workspace list 2>/dev/null | python3 -c '
+import json,sys
+ws=sys.argv[1]
+try:
+    d=json.load(sys.stdin); wss=(d.get("result",{}) or {}).get("workspaces",[])
+    for w in wss:
+        if w.get("workspace_id")==ws:
+            print(w.get("active_tab_id") or ""); break
+except Exception:
+    pass' "$ws" 2>/dev/null)"
+  [ -n "$at" ] || return 1
+  first_pane_of_tab "$at"
+}
+
+# Seat an Eindri in a PANE SPLIT — the companion road, so an Eindri sits beside
+# the work rather than hidden in a tab. Splits the current pane (inside herdr)
+# or this home's active pane. Prints "<tab_id> <pane_id>".
+seat_pane() {  # <name> <cwd>
+  local cwd=$2 target out
+  target="$(current_pane)"; [ -n "$target" ] || target="$(home_pane)"
+  [ -n "$target" ] || return 1
+  out="$(hdr pane split "$target" --direction right --cwd "$cwd" 2>/dev/null)"
+  printf '%s' "$out" | python3 -c '
+import json,sys
+try:
+    d=json.load(sys.stdin); p=(d.get("result",{}) or {}).get("pane",{})
+    print(p.get("tab_id") or "", p.get("pane_id") or "")
+except Exception:
+    pass' 2>/dev/null
+}
+
+case "$ACTION" in
+  available)
+    if can_use_herdr; then
+      printf 'herdr-run[1]{herdr,session,workspace,space_ok}:\n  "yes","%s","%s","%s"\n' \
+        "$HDR_SESSION" "$(home_workspace)" "$(space_supported && echo yes || echo no)"
+    else
+      reason=""
+      [ "${HERDR_ENV:-}" != "1" ] && reason="not inside herdr (HERDR_ENV unset)"
+      [ "${YMIR_HERDR_PANES:-1}" != "1" ] && reason="YMIR_HERDR_PANES=0"
+      have herdr || reason="herdr binary absent"
+      printf 'herdr-run[1]{herdr,reason}:\n  "no","%s"\n' "${reason:-unknown}"
+    fi
+    exit 0 ;;
+  worth-a-smith)
+    worth_a_smith "${*:-}"; exit $? ;;
+  run)
+    NAME="${1:-step}"; shift || true
+    [ "${1:-}" = "--" ] && shift
+    [ $# -gt 0 ] || { printf 'error: run needs a command after --\n' >&2; exit 2; }
+    if ! can_use_herdr; then "$@"; exit $?; fi
+    mkdir -p "$STATE_DIR"
+    read -r tab pane <<<"$(seat_tab "ymir:$NAME" "$PWD")"
+    if [ -z "$pane" ]; then "$@"; exit $?; fi
+    printf '%s\t%s\n' "$tab" "$NAME" >>"$TAB_LOG" 2>/dev/null || true
+    # A pane runs its command through a shell, so every argument must be quoted
+    # on the way in. Unquoted, a multi-word argument (`--brief "the whole task"`)
+    # arrives as separate words and the command dies on its own second word.
+    cmd=""
+    for a in "$@"; do cmd="$cmd$(printf '%q ' "$a")"; done
+    hdr pane run "$pane" "$cmd" >/dev/null 2>&1; rc=$?
+    hdr pane wait-output "$pane" --idle-ms 800 --timeout-secs "$SETTLE" >/dev/null 2>&1 || true
+    printf 'herdr-run[1]{tab,pane,step,exit}:\n  "%s","%s","%s",%s\n' "$tab" "$pane" "$NAME" "$rc"
+    exit "$rc" ;;
+  agent|eindri)
+    NAME=""; ROLE=""; SPACE=0; TAB=0; MODEL_REQ=""; MAIN=0
+    while [ $# -gt 0 ]; do
+      case "$1" in
+        --role) ROLE=${2-}; shift 2 ;;
+        --role=*) ROLE=${1#--role=}; shift ;;
+        --model) MODEL_REQ=${2-}; shift 2 ;;
+        --model=*) MODEL_REQ=${1#--model=}; shift ;;
+        --space) SPACE=1; shift ;;
+        --tab) TAB=1; shift ;;
+        --pane) SPACE=0; TAB=0; shift ;;
+        --main) MAIN=1; shift ;;
+        --) shift; break ;;
+        -*) shift ;;
+        *) if [ -z "$NAME" ]; then NAME="$1"; shift; else break; fi ;;
+      esac
+    done
+    [ "${1:-}" = "--" ] && shift
+    PROMPT="${*:-}"
+    if ! can_use_herdr; then
+      printf 'error: no herdr session — cannot seat an Eindri\nhelp: inside herdr, or use bin/einherjar-spawn.sh\n' >&2
+      exit 1
+    fi
+    [ -n "$PROMPT" ] || { printf 'error: eindri needs a task after --\n' >&2; exit 2; }
+
+    # The first law: short errands are done in hand.
+    if ! worth_a_smith "$PROMPT" >/dev/null 2>&1; then
+      printf 'herdr-run[1]{eindri,verdict}:\n  "none","short errand — answer it in hand"\n'
+      exit 3
+    fi
+
+    # The right smith for the right metal.
+    if [ -z "$ROLE" ] && [ -x "$SCRIPT_DIR/eindri-role.sh" ]; then
+      ROLE="$("$SCRIPT_DIR/eindri-role.sh" choose "$PROMPT" 2>/dev/null | sed -n '2p' | sed -E 's/^ *"([^"]+)".*/\1/')"
+    fi
+    [ -n "$NAME" ] || NAME="${ROLE:-eindri}"
+    KIND="${YMIR_HERDR_KIND:-pi}"
+
+    # Resolve a model request (friendly or exact) to harness+provider+model.
+    # local -> pi, online -> opencode. Unresolved -> report and continue default.
+    MODEL_ARGS=()
+    if [ -n "$MODEL_REQ" ] && [ -x "$SCRIPT_DIR/model-resolve.sh" ]; then
+      r="$("$SCRIPT_DIR/model-resolve.sh" resolve "$MODEL_REQ" 2>/dev/null | sed -n '2p')"
+      case "$r" in
+        ""|*unresolved*)
+          printf 'herdr-run[1]{model,state}:\n  "%s","unresolved — ask the Allfather"\n' "$MODEL_REQ" >&2 ;;
+        *)
+          loc="$(printf '%s' "$r" | cut -d'"' -f4)"
+          h="$(printf '%s' "$r"   | cut -d'"' -f6)"
+          pv="$(printf '%s' "$r"  | cut -d'"' -f8)"
+          md="$(printf '%s' "$r"  | cut -d'"' -f10)"
+          # The harness FOLLOWS the model: a local provider is pi's work, an
+          # online one is opencode's. Trusting a field position here seated
+          # pi with an online model id, so the worker started and sat IDLE -
+          # "sent but never started" - while the dispatch row reported success.
+          case "${md:-}:${pv:-}:${h:-}" in
+            *llama*|*lmstudio*|*ollama*) KIND=pi ;;
+            "")                          KIND=pi ;;   # nothing resolved: stay local
+            *)                           KIND=opencode ;;
+          esac
+          [ -n "$md" ] && MODEL_ARGS=(-- --model "$pv/$md")
+          printf 'herdr-run[1]{model,harness,provider,model_id}:\n  "%s","%s","%s","%s"\n' "$MODEL_REQ" "$h" "$pv" "$md" >&2 ;;
+      esac
+    fi
+
+    # No explicit model: use the AGENT'S configured harness+model from
+    # config/agents.yaml (local->pi, online->opencode) — never default silently.
+    if [ -z "$MODEL_REQ" ] && [ -x "$SCRIPT_DIR/agents-config.sh" ]; then
+      _h="$("$SCRIPT_DIR/agents-config.sh" get "$ROLE" harness 2>/dev/null)"
+      _m="$("$SCRIPT_DIR/agents-config.sh" get "$ROLE" model 2>/dev/null)"
+      [ -n "$_h" ] && KIND="$_h"
+      [ -n "$_m" ] && MODEL_ARGS=(-- --model "$_m")
+      printf 'herdr-run[1]{agent,harness,model}:\n  "%s","%s","%s"\n' "$ROLE" "${_h:-?}" "${_m:-?}" >&2
+    fi
+
+    # Where the Eindri sits, in herdr's hierarchy (workspace > tab > pane):
+    #   --space  a disposable workspace (one errand, torn down)
+    #   --tab    a new tab in this home's workspace
+    #   default  a PANE SPLIT beside the work (the companion road)
+    # ISOLATION (law ygg1): never seat an Eindri in the main tree. Create or
+    # reuse a Yggdrasil worktree and seat there.
+    SEAT_CWD="$PWD"
+    if [ "${MAIN:-0}" = 1 ]; then
+      printf 'herdr-run[1]{isolation,worktree}:\n  "off (main tree — Allfather chose --main)"\n' >&2
+    elif [ -x "$SCRIPT_DIR/yggdrasil.sh" ]; then
+      # Reuse an existing worktree for this id; create only when absent.
+      wt_path="$(git -C "$PWD" rev-parse --show-toplevel 2>/dev/null)/.yggdrasil/$NAME"
+      if [ ! -d "$wt_path" ]; then
+        wt_out="$("$SCRIPT_DIR/yggdrasil.sh" create "$NAME" 2>/dev/null)"
+        wt_path="$(printf '%s' "$wt_out" | sed -n '2p' | cut -d'"' -f6)"
+      fi
+      if [ -n "$wt_path" ] && [ -d "$wt_path" ]; then
+        SEAT_CWD="$(cd "$wt_path" && pwd)"
+        printf 'herdr-run[1]{isolation,worktree}:\n  "on","%s"\n' "$SEAT_CWD" >&2
+      else
+        printf 'error: isolation — could not create a Yggdrasil worktree; refusing to seat in the main tree\nhelp: bin/yggdrasil.sh create %s\n' "$NAME" >&2
+        exit 4
+      fi
+    fi
+
+    seat_note="pane"
+    if [ "$SPACE" = 1 ]; then
+      if space_supported; then
+        read -r ws tab pane <<<"$(seat_space "$NAME" "$SEAT_CWD")"
+        [ -n "$ws" ] && seat_note="space $ws" && printf '%s\t%s\tspace:%s\n' "$tab" "$NAME" "$ws" >>"$TAB_LOG" 2>/dev/null || true
+      else
+        seat_note="tab (space floor not met)"
+      fi
+    elif [ "$TAB" = 1 ]; then
+      seat_note="tab"
+    else
+      read -r tab pane <<<"$(seat_pane "$NAME" "$SEAT_CWD")"
+      if [ -n "$tab" ]; then
+        printf '%s\t%s\tpane\n' "$tab" "$NAME" >>"$TAB_LOG" 2>/dev/null || true
+      else
+        seat_note="tab (pane split unavailable)"
+      fi
+    fi
+    if [ -z "${tab:-}" ]; then
+      read -r tab pane <<<"$(seat_tab "$NAME" "$SEAT_CWD")"
+      [ -n "$tab" ] && printf '%s\t%s\n' "$tab" "$NAME" >>"$TAB_LOG" 2>/dev/null || true
+    fi
+    [ -n "$tab" ] || { printf 'error: could not seat the Eindri\n' >&2; exit 1; }
+    [ -n "$pane" ] || { printf 'error: the tab has no pane\n' >&2; exit 1; }
+
+    if ! hdr agent start "$NAME" --kind "$KIND" --pane "$pane" "${MODEL_ARGS[@]}" >/dev/null 2>&1; then
+      printf 'error: could not start a %s Eindri in %s\nhelp: the pane must sit at an interactive shell prompt\n' "$KIND" "$pane" >&2
+      exit 1
+    fi
+    # Inject the task — retry until it lands. `agent start` can return before the
+    # harness accepts input (opencode is slower than pi), and a single swallowed
+    # prompt is the "it started but nothing was injected" bug.
+    injected=no
+    for _try in 1 2 3 4 5 6 7 8 9 10; do
+      if hdr agent prompt "$NAME" "$PROMPT" >/dev/null 2>&1; then injected=yes; break; fi
+      sleep 3
+    done
+    printf 'herdr-run[1]{eindri,injected,attempts}:\n  "%s","%s",%s\n' "$NAME" "$injected" "${_try:-0}" >&2
+    if [ "${YMIR_HERDR_AGENT_WAIT:-1}" = "1" ]; then
+      hdr agent wait "$NAME" --until done --until idle --timeout $((SETTLE * 1000)) >/dev/null 2>&1 || true
+    fi
+    printf 'herdr-run[1]{seat,eindri,role,kind,tab,state}:\n  "%s","%s","%s","%s","%s","%s"\n' \
+      "$seat_note" "$NAME" "${ROLE:-unspecified}" "$KIND" "$tab" \
+      "$(hdr agent get "$NAME" 2>/dev/null | python3 -c '
+import json,sys
+try:
+    d=json.load(sys.stdin); r=d.get("result",{}); a=r.get("agent",r)
+    print(a.get("agent_status") or a.get("status") or "unknown")
+except Exception:
+    print("unknown")' 2>/dev/null)"
+    ;;
+  agent-status)
+    if [ -x "$SCRIPT_DIR/herdr-agents.py" ]; then python3 "$SCRIPT_DIR/herdr-agents.py"
+    else printf 'herdr-run[1]{state}:\n  "herdr-agents.py missing"\n'; fi
+    ;;
+  agent-stop)
+    NAME="${1:-}"
+    [ -n "$NAME" ] || { printf 'error: agent-stop needs a name\n' >&2; exit 2; }
+    hdr agent stop "$NAME" >/dev/null 2>&1 || true
+    printf 'herdr-run[1]{eindri,state}:\n  "%s","stopped"\n' "$NAME"
+    ;;
+  close-all)
+    if [ -r "$TAB_LOG" ]; then
+      while IFS=$'\t' read -r id name extra; do
+        [ -n "$id" ] || continue
+        case "$extra" in
+          space:*) hdr workspace close "${extra#space:}" >/dev/null 2>&1 || hdr tab close "$id" >/dev/null 2>&1 || true ;;
+          *)       hdr tab close "$id" >/dev/null 2>&1 || true ;;
+        esac
+      done <"$TAB_LOG"
+      rm -f "$TAB_LOG"
+    fi
+    printf 'herdr-run[1]{state}:\n  "seats cleared"\n'
+    ;;
+  status)
+    if [ -r "$TAB_LOG" ]; then
+      printf 'herdr-run[%d]{seat,eindri}:\n' "$(grep -c . "$TAB_LOG" 2>/dev/null || echo 0)"
+      while IFS=$'\t' read -r id name extra; do
+        [ -n "$id" ] && printf '  "%s","%s"\n' "${extra:-$id}" "$name"
+      done <"$TAB_LOG"
+    else
+      printf 'herdr-run[1]{state}:\n  "no seats recorded"\n'
+    fi
+    ;;
+  *) printf 'error: unknown action %s\nhelp: bin/herdr-run.sh [available|worth-a-smith|eindri|run|agent-status|close-all|status]\n' "$ACTION" >&2; exit 2 ;;
+esac

package/bin/hermes-ensure.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# hermes-ensure.sh — ensure the Hermes agent runtime is present.
+#
+# **Hermes** is Nous Research's open-source agent runtime
+# (https://hermes-agent.nousresearch.com, MIT) — its own brain, config, memory,
+# skills, scheduling, and subagents. Ymir adopts it as a **worker runtime** (an
+# external engine, like opencode / pi / treehouse); the name is the product's,
+# never a Norse rename.
+#
+# Usage:
+#   hermes-ensure.sh status
+#   hermes-ensure.sh ensure [--install] [--quiet]
+#   hermes-ensure.sh install
+#   hermes-ensure.sh --version
+#
+# Exit: 0 present (or installed), 1 absent and not installed, 2 usage.
+set -u
+
+VERSION="1.0.0"
+HOME_DIR="${HERMES_HOME:-$HOME/.hermes}"
+INSTALL_URL="${HERMES_INSTALL_URL:-https://hermes-agent.nousresearch.com/install.sh}"
+
+case "${1-}" in -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;; -h|--help|"") sed -n '2,15p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; esac
+CMD="${1-}"; shift || true
+DO_INSTALL=0
+case "$CMD" in ensure) ;; status|install) ;; *) printf 'error: unknown command %s\nhelp: bin/hermes-ensure.sh [status|ensure|install]\n' "$CMD" >&2; exit 2 ;; esac
+while [ $# -gt 0 ]; do case "$1" in --install) DO_INSTALL=1; shift ;; --quiet) shift ;; *) shift ;; esac; done
+[ "$CMD" = install ] && DO_INSTALL=1
+
+hermes_bin() {
+  if command -v hermes >/dev/null 2>&1; then command -v hermes; return; fi
+  for p in "$HOME_DIR/bin/hermes" "$HOME/.local/bin/hermes"; do
+    [ -x "$p" ] && { printf '%s' "$p"; return; }
+  done
+  return 1
+}
+
+hermes_version() {
+  local b; b="$(hermes_bin)" || return 1
+  "$b" --version 2>/dev/null | head -n1
+}
+
+status() {
+  local b v method dir
+  if b="$(hermes_bin)"; then
+    v="$(hermes_version)"
+    dir="$HOME_DIR/hermes-agent"; [ -d "$dir" ] || dir="$HOME_DIR"
+    method="binary"
+    [ -d "$HOME_DIR/hermes-agent/.git" ] && method="git"
+    printf 'hermes[1]{installed,version,path,method}:\n'
+    printf '  "true","%s","%s","%s"\n' "$v" "$b" "$method"
+    return 0
+  fi
+  printf 'hermes[1]{installed,version,path,method}:\n'
+  printf '  "false","—","—","—"\n'
+  return 1
+}
+
+install_hermes() {
+  command -v curl >/dev/null 2>&1 || { printf 'error: curl not found — cannot install Hermes\nhelp: %s\n' "$INSTALL_URL" >&2; return 1; }
+  printf 'hermes: installing from %s …\n' "$INSTALL_URL" >&2
+  if curl -fsSL "$INSTALL_URL" | bash >/dev/null 2>&1; then
+    printf 'hermes: install finished\n' >&2
+  else
+    printf 'hermes: install failed (offline?) — install manually: curl -fsSL %s | bash\n' "$INSTALL_URL" >&2
+    return 1
+  fi
+}
+
+case "$CMD" in
+  status) status; exit $? ;;
+  install) install_hermes; status; exit $? ;;
+  ensure)
+    if status >/dev/null 2>&1; then
+      [ -n "${1-}" ] || status
+      status
+      exit 0
+    fi
+    if [ "$DO_INSTALL" = 1 ]; then
+      install_hermes || true
+      status
+      hermes_bin >/dev/null 2>&1
+      exit $?
+    fi
+    printf 'hermes[1]{installed,version,path,method}:\n  "false","—","—","—"\n'
+    printf 'hermes: not installed — run `bin/hermes-ensure.sh install` or curl -fsSL %s | bash\n' "$INSTALL_URL" >&2
+    exit 1 ;;
+esac