@zerwiz/ymir 0.1.4 → 0.1.7

package/bin/hamr-harness.sh

@@ -0,0 +1,246 @@
+#!/usr/bin/env bash
+# hamr-harness.sh - detect the agent harness (Hamr) this process tree runs on.
+#
+# Hamr ("shape") is the form a being wears. Detection answers which agent
+# runtime the process tree is wearing so Brokk can choose the correct adapter,
+# launch flags, and dispatch profile. Ported from the upstream agent-distro
+# reference (bin/hamr-harness.sh) and retargeted to the Brokk runtime
+# (docs/plans/29-brokk-distro-runtime.md).
+#
+# Usage:
+#   hamr-harness.sh                 print own harness:
+#                                   claude|codex|opencode|pi|pi-signed|grok|kimi|cursor|unknown
+#   hamr-harness.sh eindri          print the effective EINDRI harness from
+#                                   config/eindri-harness; an absent file or the
+#                                   value "default" resolves to own.
+#   hamr-harness.sh eindri-model    print the optional MODEL token from
+#                                   config/eindri-harness, or empty when absent.
+#   hamr-harness.sh eindri-effort   print the optional EFFORT token from
+#                                   config/eindri-harness, or empty when absent.
+#
+# config/eindri-harness format: a single line "<harness> [<model>] [<effort>]",
+# whitespace-separated. A bare "<harness>" (today's format) behaves exactly as
+# harness-only with no model/effort. Only the first non-empty, non-comment line
+# is parsed. Model/effort come ONLY from this file.
+#
+# Detection layers: verified environment markers first, then process ancestry.
+# Record each newly verified env marker here.
+set -u
+
+# --- portability shim: bin/ymir-platform.sh --------------------------------
+# One place knows the OS differences (readlink -f, /proc, setsid, stat, nproc).
+if [ -z "${YMIR_PLATFORM_LOADED:-}" ]; then
+  _ymir_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+  for _ymir_c in "$_ymir_dir/ymir-platform.sh" "$(dirname "$_ymir_dir")/bin/ymir-platform.sh"; do
+    [ -r "$_ymir_c" ] && { . "$_ymir_c"; YMIR_PLATFORM_LOADED=1; break; }
+  done
+  unset _ymir_dir _ymir_c
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+BROKK_ROOT="${BROKK_ROOT_OVERRIDE:-$(cd "$SCRIPT_DIR/.." && pwd)}"
+BROKK_HOME="${BROKK_HOME:-${BROKK_ROOT_OVERRIDE:-$BROKK_ROOT}}"
+CONFIG="${BROKK_CONFIG_OVERRIDE:-$BROKK_HOME/config}"
+
+# --- Cursor process identity ------------------------------------------------
+# Cursor ships two executable names: `cursor-agent` and the legacy alias
+# `agent`. `agent` is far too generic to trust on its name alone, so structural
+# evidence (canonical name or Cursor's versioned install tree) is required.
+# This is inlined because the Brokk runtime has no separate cursor library;
+# keep this block the single owner of Cursor process identity in this file.
+#
+# Canonical absolute path for $1, or the input unchanged when it cannot be
+# resolved. Symlink resolution is what makes the structural signal work.
+hamr_cursor_canonical_path() {  # <path>
+  local path=$1 resolved
+  [ -n "$path" ] || return 1
+  if command -v readlink >/dev/null 2>&1; then
+    resolved=$(ymir_readlink_f "$path" 2>/dev/null || true)
+    [ -n "$resolved" ] && { printf '%s\n' "$resolved"; return 0; }
+  fi
+  printf '%s\n' "$path"
+}
+
+# True when path $1 carries Cursor's structural evidence: its canonical name is
+# cursor-agent, or it lives inside Cursor's cursor-agent/versions/<version>/
+# install tree. A directory component merely named `agent` is NEVER enough.
+hamr_cursor_path_is_cursor() {  # <path>
+  local path=$1 canonical
+  [ -n "$path" ] || return 1
+  canonical=$(hamr_cursor_canonical_path "$path") || return 1
+  case "${canonical##*/}" in cursor-agent) return 0 ;; esac
+  case "$canonical" in */cursor-agent/versions/*/*) return 0 ;; esac
+  return 1
+}
+
+# Read argv[0] without flattening it into a whitespace-delimited command line.
+hamr_cursor_argv0_for_pid() {  # <pid> [comm-fallback]
+  local pid=$1 fallback=${2:-} proc_root=${BROKK_PROC_ROOT_OVERRIDE:-/proc} argv0=
+  if [ -r "$proc_root/$pid/cmdline" ]; then
+    IFS= read -r -d '' argv0 < "$proc_root/$pid/cmdline" || true
+    [ -n "$argv0" ] && { printf '%s\n' "$argv0"; return 0; }
+  fi
+  if [ -z "$fallback" ]; then
+    fallback=$(LC_ALL=C ps -p "$pid" -o comm= 2>/dev/null || true)
+  fi
+  [ -n "$fallback" ] || return 1
+  printf '%s\n' "$fallback"
+}
+
+hamr_cursor_argv0_is_cursor() {  # <argv0>
+  local argv0=$1
+  [ -n "$argv0" ] || return 1
+  case "$argv0" in
+    ''|MainThread) return 1 ;;
+    cursor-agent) return 0 ;;
+  esac
+  hamr_cursor_path_is_cursor "$argv0"
+}
+
+# True when the process described by command name $1 and structured argv0 $2 is
+# Cursor. Rejects a bare MainThread with no Cursor evidence, any executable
+# whose basename merely happens to be `agent`, and any path with an `agent/`
+# directory component that is running something else.
+hamr_cursor_process_matches() {  # <comm> [argv0]
+  local comm=$1 argv0=${2:-} base
+  [ -n "$comm" ] || [ -n "$argv0" ] || return 1
+  argv0=${argv0:-$comm}
+  base=$(basename -- "$comm")
+  base=${base#-}
+  case "$base" in
+    cursor-agent) return 0 ;;
+    agent|MainThread|node|node-*|node[0-9]*|python|python[0-9]*|python[0-9].[0-9]*)
+      hamr_cursor_argv0_is_cursor "$argv0" && return 0
+      hamr_cursor_path_is_cursor "$comm" && return 0
+      return 1
+      ;;
+  esac
+  case "$comm" in */*) hamr_cursor_path_is_cursor "$comm" && return 0 ;; esac
+  return 1
+}
+
+detect_own() {
+  # Layer 1: environment markers for verified harnesses. Keep marker detection
+  # before ancestry detection as an explicit precedence rule.
+  #
+  # Cursor is checked BEFORE claude, deliberately: cursor-agent does NOT clear
+  # an inherited CLAUDECODE, so a cursor worker launched from a claude primary
+  # carries BOTH markers and whichever is tested first wins. Cursor's own
+  # markers are unambiguous when present.
+  [ "${CURSOR_AGENT:-}" = "1" ] && { echo cursor; return; }
+  [ "${CURSOR_INVOKED_AS:-}" = "cursor-agent" ] && { echo cursor; return; }
+  [ "${CLAUDECODE:-}" = "1" ] && { echo claude; return; }
+  if [ "${PI_CODING_AGENT:-}" = "true" ]; then
+    if [ "${BROKK_PI_HARNESS:-}" = pi-signed ]; then echo pi-signed; else echo pi; fi
+    return
+  fi
+  # grok sets GROK_AGENT=1 for its child/tool processes (verified, grok 0.2.73).
+  # It does NOT set CLAUDECODE despite being Claude-Code-compatible, so the
+  # marker is unambiguous WHEN PRESENT. A grok hook process carries
+  # GROK_HOOK_EVENT/GROK_HOOK_NAME instead, so treat this as a fast path only;
+  # the ancestry walk below is what reliably identifies grok.
+  [ "${GROK_AGENT:-}" = "1" ] && { echo grok; return; }
+  # codex, opencode, and kimi publish no verified harness-identity marker, so
+  # they are detected by ancestry alone below.
+  #
+  # Layer 2: walk the parent chain and match the command name.
+  local pid=$$ comm args argv0
+  for _ in 1 2 3 4 5 6 7 8; do
+    comm=$(ps -o comm= -p "$pid" 2>/dev/null) || break
+    argv0=$(hamr_cursor_argv0_for_pid "$pid" "$comm" 2>/dev/null || true)
+    if hamr_cursor_process_matches "$comm" "$argv0"; then
+      echo cursor
+      return
+    fi
+    case "$(basename -- "$comm")" in
+      *claude*) echo claude; return ;;
+      *codex*) echo codex; return ;;
+      *opencode*) echo opencode; return ;;
+      *grok*) echo grok; return ;;
+      kimi) echo kimi; return ;;
+      pi-signed) echo pi; return ;;
+      pi) echo pi; return ;;
+      node*|python*)
+        # Bare interpreter: match the harness name in its script path.
+        args=$(ps -o args= -p "$pid" 2>/dev/null)
+        case "$args" in
+          *claude*) echo claude; return ;;
+          *codex*) echo codex; return ;;
+          *opencode*) echo opencode; return ;;
+          *grok*) echo grok; return ;;
+          *" pi "*|*/pi) echo pi; return ;;
+        esac ;;
+    esac
+    pid=$(ps -o ppid= -p "$pid" 2>/dev/null | tr -d ' ')
+    if [ -z "$pid" ] || [ "$pid" -le 1 ]; then
+      break
+    fi
+  done
+  echo unknown
+}
+
+# Print the first non-empty, non-comment line of config/eindri-harness
+# (leading/trailing whitespace trimmed), or nothing when the file is absent or
+# holds only blank/comment lines.
+eindri_line() {
+  local line
+  [ -f "$CONFIG/eindri-harness" ] || return 0
+  while IFS= read -r line || [ -n "$line" ]; do
+    line="${line#"${line%%[![:space:]]*}"}"
+    line="${line%"${line##*[![:space:]]}"}"
+    [ -n "$line" ] || continue
+    case "$line" in
+      '#'*) continue ;;
+    esac
+    printf '%s\n' "$line"
+    return 0
+  done < "$CONFIG/eindri-harness"
+}
+
+# Print the 1-based whitespace-separated token (1=harness, 2=model, 3=effort) of
+# the resolved eindri_line, or nothing if the line or that field is absent.
+eindri_field() {
+  local idx=$1 line
+  line=$(eindri_line)
+  [ -n "$line" ] || return 0
+  # shellcheck disable=SC2086  # deliberate word-splitting: tokenizing the line into fields
+  set -- $line
+  case "$idx" in
+    1) printf '%s\n' "${1:-}" ;;
+    2) printf '%s\n' "${2:-}" ;;
+    3) printf '%s\n' "${3:-}" ;;
+  esac
+}
+
+# Resolve the effective Eindri harness: config/eindri-harness wins; absent or
+# "default" mirrors Brokk's own harness.
+resolve_eindri() {
+  local harness
+  harness=$(eindri_field 1)
+  if [ -z "$harness" ] || [ "$harness" = "default" ]; then detect_own; else echo "$harness"; fi
+}
+
+# Print the optional model token (2nd field) from config/eindri-harness, or
+# empty when the harness token is absent/"default" or no model token is present.
+resolve_eindri_model() {
+  local harness
+  harness=$(eindri_field 1)
+  [ -n "$harness" ] && [ "$harness" != "default" ] || return 0
+  eindri_field 2
+}
+
+# Print the optional effort token (3rd field) from config/eindri-harness, the
+# same way.
+resolve_eindri_effort() {
+  local harness
+  harness=$(eindri_field 1)
+  [ -n "$harness" ] && [ "$harness" != "default" ] || return 0
+  eindri_field 3
+}
+
+case "${1:-}" in
+  eindri) resolve_eindri ;;
+  eindri-model) resolve_eindri_model ;;
+  eindri-effort) resolve_eindri_effort ;;
+  *) detect_own ;;
+esac

package/bin/heimdall-ssh-keys.sh

@@ -0,0 +1,374 @@
+#!/usr/bin/env bash
+# heimdall-ssh-keys.sh — Heimdall's SSH-keys surface.
+#
+# Heimdall is the authentication guardian: he admits an entrant only by the rune
+# of introduction they carry. For the OpenSSH server on a Ymir host, those runes
+# live on GitHub — this script fetches `https://github.com/<user>.keys`, validates
+# every key, and authorizes the valid ones in `~/.ssh/authorized_keys`, so a new
+# machine joins the fleet by publishing its public key to GitHub and nothing else.
+#
+# The mechanism follows Omarchy's `omarchy-setup-security-sshd --gh-keys`: fetch,
+# validate, authorize; and only *then* offer to turn password logins off.
+#
+# Usage:
+#   heimdall-ssh-keys.sh status
+#   heimdall-ssh-keys.sh add [<github-user> ...] [--key=<public-key>] [--quiet]
+#   heimdall-ssh-keys.sh harden | unharden
+#   heimdall-ssh-keys.sh timer install | remove | status
+#   heimdall-ssh-keys.sh --version
+#
+# Examples:
+#   heimdall-ssh-keys.sh add zerwiz
+#   heimdall-ssh-keys.sh add --key 'ssh-ed25519 AAAA… laptop'   # paste a key instead
+#   heimdall-ssh-keys.sh add --quiet          # refresh every configured user
+#   heimdall-ssh-keys.sh harden              # needs sudo; disables password logins
+#   heimdall-ssh-keys.sh timer install       # user timer, refresh every 15 min
+#
+# Env:
+#   HEIMDALL_GH_USERS   extra/user list when none is configured (space separated)
+#   HEIMDALL_KEYS_FILE  override the authorized_keys target
+#   HEIMDALL_HTTP_TIMEOUT  curl timeout seconds (default 15)
+#
+# Exit: 0 ok, 1 failure, 2 usage, 3 nothing to do.
+set -u
+
+VERSION="1.0.0"
+KEYS_FILE="${HEIMDALL_KEYS_FILE:-$HOME/.ssh/authorized_keys}"
+CONF_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/heimdall"
+USERS_FILE="$CONF_DIR/gh-users"
+DROPIN="/etc/ssh/sshd_config.d/10-heimdall-hardening.conf"
+HTTP_TIMEOUT="${HEIMDALL_HTTP_TIMEOUT:-15}"
+QUIET=0
+
+case "${1-}" in
+  -v | -V | --version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h | --help | "")
+    sed -n '2,30p' "$0" | sed 's/^# \{0,1\}//'
+    exit 0
+    ;;
+esac
+
+say() { [ "$QUIET" = 1 ] || printf '%s\n' "$*" >&2; }
+die() {
+  printf 'error: %s\n' "$*" >&2
+  exit 1
+}
+usage() {
+  printf 'error: %s\nhelp: bin/heimdall-ssh-keys.sh {status|add|harden|unharden|timer}\n' "$1" >&2
+  exit 2
+}
+
+need_curl() { command -v curl >/dev/null 2>&1 || die "curl not found — cannot reach github.com"; }
+need_sshkeygen() { command -v ssh-keygen >/dev/null 2>&1 || die "ssh-keygen not found"; }
+
+fingerprint() {
+  ssh-keygen -lf /dev/stdin 2>/dev/null <<<"$1" | awk '{print $2}'
+}
+
+fetch_keys() {
+  local user="$1" out
+  out="$(curl -fsSL --max-time "$HTTP_TIMEOUT" "https://github.com/$user.keys")" || return 1
+  [ -n "$out" ] || return 1
+  printf '%s\n' "$out"
+}
+
+valid_users() {
+  local u
+  if [ -s "$USERS_FILE" ]; then
+    while IFS= read -r u; do
+      [ -n "$u" ] && printf '%s\n' "$u"
+    done <"$USERS_FILE"
+  fi
+  [ -n "${HEIMDALL_GH_USERS:-}" ] && printf '%s\n' ${HEIMDALL_GH_USERS}
+  return 0
+}
+
+remember_user() {
+  local user="$1"
+  mkdir -p "$CONF_DIR"
+  if [ -s "$USERS_FILE" ] && grep -qxF "$user" "$USERS_FILE"; then return 0; fi
+  printf '%s\n' "$user" >>"$USERS_FILE"
+}
+
+# Merge existing + supplied files into one authorized_keys-shaped stream:
+# comments kept, blanks dropped, CRLF normalised, duplicates collapsed by key
+# fingerprint, every line newline-terminated.
+merge_keys() {
+  local target="$1"
+  shift
+  declare -A seen=()
+  local src line fp
+  for src in "$target" "$@"; do
+    [ -r "$src" ] || continue
+    while IFS= read -r line || [ -n "$line" ]; do
+      line="${line%$'\r'}"
+      [ -z "$line" ] && continue
+      case "$line" in \#*)
+        printf '%s\n' "$line"
+        continue
+        ;;
+      esac
+      fp="$(fingerprint "$line")"
+      [ -n "$fp" ] || continue
+      [ "${seen[$fp]:-}" = 1 ] && continue
+      seen[$fp]=1
+      printf '%s\n' "$line"
+    done <"$src"
+  done
+}
+
+count_keys_in() {
+  local n
+  n="$(ssh-keygen -lf "$1" 2>/dev/null | wc -l)"
+  printf '%s' "$((n))"
+}
+
+count_keys() {
+  [ -r "$KEYS_FILE" ] || {
+    printf '0'
+    return
+  }
+  count_keys_in "$KEYS_FILE"
+}
+
+password_auth_state() {
+  command -v sshd >/dev/null 2>&1 || {
+    printf 'unknown'
+    return
+  }
+  if grep -qiE '^[[:space:]]*PasswordAuthentication[[:space:]]+no' "$DROPIN" 2>/dev/null; then
+    printf 'no'
+  else
+    printf 'yes'
+  fi
+}
+
+cmd_status() {
+  need_sshkeygen
+  local users keys pw hardened file
+  users="$(valid_users | paste -sd, -)"
+  keys="$(count_keys)"
+  pw="$(password_auth_state)"
+  hardened=false
+  [ "$pw" = no ] && hardened=true
+  [ -n "$users" ] || users="—"
+  file="$KEYS_FILE"
+  printf 'heimdall[1]{keys,gh_users,password_auth,hardened,file}:\n'
+  printf '  "%s","%s","%s","%s","%s"\n' "$keys" "$users" "$pw" "$hardened" "$file"
+}
+
+cmd_add() {
+  need_sshkeygen
+  local users=() literals=() arg
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --quiet)
+        QUIET=1
+        shift
+        ;;
+      --key=*)
+        literals+=("${1#--key=}")
+        shift
+        ;;
+      --key)
+        shift
+        [ $# -gt 0 ] || usage "--key needs a public key"
+        literals+=("$1")
+        shift
+        ;;
+      -*) usage "unknown option '$1'" ;;
+      *)
+        users+=("$1")
+        shift
+        ;;
+    esac
+  done
+  if [ "${#users[@]}" -eq 0 ] && [ "${#literals[@]}" -eq 0 ]; then
+    while IFS= read -r arg; do
+      [ -n "$arg" ] && users+=("$arg")
+    done < <(valid_users)
+  fi
+  [ "${#users[@]}" -gt 0 ] || [ "${#literals[@]}" -gt 0 ] ||
+    die "nothing to authorize — use: add <github-user> or add --key '<public-key>'"
+
+  mkdir -p "$(dirname "$KEYS_FILE")"
+  chmod 700 "$(dirname "$KEYS_FILE")" 2>/dev/null || true
+  [ -e "$KEYS_FILE" ] || : >"$KEYS_FILE"
+  chmod 600 "$KEYS_FILE"
+
+  local staging fetched_keys raw added label tmp before after k key user
+  staging="$(mktemp)"
+  fetched_keys="$(mktemp)"
+  cp -a "$KEYS_FILE" "$staging"
+
+  printf 'heimdall_add[%d]{source,fetched,added,total}:\n' "$((${#users[@]} + ${#literals[@]}))"
+  local rc=0
+
+  absorb() {
+    before="$(count_keys_in "$staging")"
+    tmp="$(mktemp)"
+    merge_keys "$staging" "$fetched_keys" >"$tmp"
+    mv "$tmp" "$staging"
+    after="$(count_keys_in "$staging")"
+    added=$((after - before))
+    [ "$added" -lt 0 ] && added=0
+    printf '  "%s","%s","%s","%s"\n' "$label" "$(grep -c . "$fetched_keys")" "$added" "$after"
+  }
+
+  for key in "${literals[@]}"; do
+    label="key"
+    : >"$fetched_keys"
+    if [ -z "$(fingerprint "$key")" ]; then
+      say "heimdall: skipping invalid key: ${key:0:32}…"
+      rc=1
+      continue
+    fi
+    printf '%s\n' "$key" >>"$fetched_keys"
+    absorb
+  done
+
+  if [ "${#users[@]}" -gt 0 ]; then
+    need_curl
+    for user in "${users[@]}"; do
+      label="$user"
+      : >"$fetched_keys"
+      if raw="$(fetch_keys "$user")"; then
+        while IFS= read -r k; do
+          [ -z "$k" ] && continue
+          [ -n "$(fingerprint "$k")" ] || {
+            say "heimdall: skipping invalid key advertised by $user"
+            continue
+          }
+          printf '%s github:%s\n' "$k" "$user" >>"$fetched_keys"
+        done <<<"$raw"
+      else
+        say "heimdall: could not fetch keys for '$user' (offline or unknown user)"
+        printf '  "%s","0","0","%s"\n' "$user" "$(count_keys)"
+        rc=1
+        continue
+      fi
+      absorb
+      remember_user "$user"
+    done
+  fi
+  rm -f "$fetched_keys"
+  chmod 600 "$staging"
+
+  if cmp -s "$staging" "$KEYS_FILE"; then
+    rm -f "$staging"
+    say "heimdall: authorized keys already current"
+  else
+    cp -a "$KEYS_FILE" "$KEYS_FILE.bak.$(date +%Y%m%d-%H%M%S)" 2>/dev/null || true
+    mv "$staging" "$KEYS_FILE"
+    say "heimdall: authorized keys updated ($(count_keys) keys)"
+  fi
+  return $rc
+}
+
+as_root() {
+  if [ "$(id -u)" -eq 0 ]; then "$@"; else sudo "$@"; fi
+}
+
+write_dropin() {
+  as_root tee "$DROPIN" >/dev/null <<'CONF'
+# Written by bin/heimdall-ssh-keys.sh once an SSH key was authorized.
+# Delete this file and reload sshd to allow password logins again.
+PasswordAuthentication no
+KbdInteractiveAuthentication no
+CONF
+}
+
+reload_sshd() {
+  as_root systemctl reload ssh 2>/dev/null || as_root systemctl reload sshd
+}
+
+cmd_harden() {
+  need_sshkeygen
+  [ "$(count_keys)" -gt 0 ] || die "no authorized keys — refusing to disable password logins (that would strand the machine)"
+  say "heimdall: disabling SSH password authentication"
+  write_dropin
+  if ! as_root sshd -t; then
+    as_root rm -f "$DROPIN"
+    die "sshd rejected the hardening config; removed it, passwords stay on"
+  fi
+  local effective
+  if ! effective="$(as_root sshd -T)" ||
+    ! grep -qixF 'passwordauthentication no' <<<"$effective" ||
+    ! grep -qixF 'kbdinteractiveauthentication no' <<<"$effective"; then
+    as_root rm -f "$DROPIN"
+    die "sshd did not apply the restrictions (an earlier rule wins); removed the ineffective config"
+  fi
+  reload_sshd
+  cmd_status
+}
+
+cmd_unharden() {
+  if [ ! -e "$DROPIN" ]; then
+    say "heimdall: not hardened; nothing to remove"
+    cmd_status
+    return 0
+  fi
+  as_root rm -f "$DROPIN"
+  as_root sshd -t && reload_sshd
+  cmd_status
+}
+
+timer_unit_dir() { printf '%s' "${HEIMDALL_UNIT_DIR:-$HOME/.config/systemd/user}"; }
+
+cmd_timer() {
+  local action="${1-}"
+  local self unit_dir
+  self="$(cd "$(dirname "$0")" && pwd)/$(basename "$0")"
+  unit_dir="$(timer_unit_dir)"
+  case "$action" in
+    install)
+      mkdir -p "$unit_dir"
+      cat >"$unit_dir/heimdall-ssh-keys.service" <<UNIT
+[Unit]
+Description=Heimdall — refresh SSH authorized keys from GitHub
+
+[Service]
+Type=oneshot
+ExecStart=$self add --quiet
+UNIT
+      cat >"$unit_dir/heimdall-ssh-keys.timer" <<'UNIT'
+[Unit]
+Description=Heimdall — SSH authorized keys refresh timer
+
+[Timer]
+OnBootSec=2min
+OnUnitActiveSec=15min
+Persistent=true
+
+[Install]
+WantedBy=timers.target
+UNIT
+      systemctl --user daemon-reload
+      systemctl --user enable --now heimdall-ssh-keys.timer
+      say "heimdall: timer enabled (every 15 min). For headless hosts: sudo loginctl enable-linger $USER"
+      cmd_timer status
+      ;;
+    remove)
+      systemctl --user disable --now heimdall-ssh-keys.timer 2>/dev/null || true
+      rm -f "$unit_dir/heimdall-ssh-keys.service" "$unit_dir/heimdall-ssh-keys.timer"
+      systemctl --user daemon-reload
+      say "heimdall: timer removed"
+      ;;
+    status)
+      systemctl --user is-active heimdall-ssh-keys.timer 2>/dev/null || printf 'inactive\n'
+      systemctl --user list-timers heimdall-ssh-keys.timer --no-pager 2>/dev/null | head -3
+      ;;
+    *) usage "timer needs install|remove|status" ;;
+  esac
+}
+
+CMD="${1-}"
+shift || true
+case "$CMD" in
+  status) cmd_status ;;
+  add) cmd_add "$@" ;;
+  harden) cmd_harden ;;
+  unharden) cmd_unharden ;;
+  timer) cmd_timer "${1-}" ;;
+  *) usage "unknown command '$CMD'" ;;
+esac

package/bin/herdr-agents.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+"""herdr-agents.py — list the agents standing in this herdr session, as TOON.
+
+Kept as its own file rather than an inline -c: the JSON shape has nested quotes
+that are painful to escape inside a shell heredoc, and a separate file can be
+tested on its own.
+
+Usage: herdr-agents.py [--json]
+"""
+import json
+import subprocess
+import sys
+
+TOON = "--json" not in sys.argv
+
+
+def main() -> int:
+    try:
+        raw = subprocess.run(
+            ["herdr", "agent", "list"],
+            capture_output=True, text=True, timeout=15,
+        ).stdout
+        data = json.loads(raw)
+    except Exception as exc:  # noqa: BLE001
+        print(f"herdr-agents[1]{{state}}:\n  \"cannot read herdr agents ({exc})\"")
+        return 1
+
+    agents = (data.get("result") or {}).get("agents") or []
+    if not TOON:
+        print(json.dumps(agents, indent=2))
+        return 0
+
+    print(f"herdr-agents[{len(agents)}]{{kind,state,pane,cwd}}:")
+    for a in agents:
+        kind = a.get("agent") or "?"
+        state = a.get("agent_status") or "unknown"
+        pane = a.get("pane_id") or "?"
+        cwd = a.get("cwd") or "?"
+        print(f'  "{kind}","{state}","{pane}","{cwd}"')
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())