@zerwiz/ymir 0.1.4 → 0.1.7

package/bin/syn-asset-pretool-check.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# syn-asset-pretool-check.sh — PreToolUse seatbelt for governed paths.
+#
+# Editing a governed file without having loaded its owning asset is how the
+# runtime drifts from its documentation. This seatbelt denies an `edit`/`write`
+# of a governed path unless the matching asset was read earlier in the session
+# (recorded in state/asset-reads). Advisory routes exist (AGENTS.md, the session
+# digest); this is the enforced one.
+#
+# Contract (same as bin/syn-arm-pretool-check.sh):
+#   syn-asset-pretool-check.sh --path <file> [--tool edit|write]
+#   syn-asset-pretool-check.sh --note <asset-path>   # record an asset as read
+#   syn-asset-pretool-check.sh --status
+# Exit: 0 = allow, 2 = block (stderr carries the reason).
+set -u
+
+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
+READS="${SYN_ASSET_READS:-$YMIR_STATE_DIR/asset-reads}"
+TARGET=""; NOTE=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --path) TARGET=${2-}; shift 2 ;;
+    --tool) shift 2 ;;
+    --note) NOTE=${2-}; shift 2 ;;
+    --status) exec "$0" --path __status__ ;;
+    *) shift ;;
+  esac
+done
+
+# Record an asset as read (called after a read of an asset path). Store BOTH the
+# path as given and its repo-relative form, so either spelling unlocks the gate.
+if [ -n "$NOTE" ]; then
+  mkdir -p "$(dirname "$READS")" 2>/dev/null || true
+  printf '%s\n' "$NOTE" >>"$READS" 2>/dev/null || true
+  case "$NOTE" in
+    "$ROOT"/*) printf '%s\n' "${NOTE#"$ROOT"/}" >>"$READS" 2>/dev/null || true ;;
+  esac
+  exit 0
+fi
+
+[ -n "$TARGET" ] || exit 0
+[ "$TARGET" = "__status__" ] && { [ -f "$READS" ] && cat "$READS" || true; exit 0; }
+
+# Map a governed path to its owning asset. Order matters — first match wins.
+asset_for() {
+  case "$1" in
+    *bin/ymir-install.sh)                         printf '%s' ".agents/skills/galdr-ymirsystem/assets/installation.md" ;;
+    *apps/hlidskjalf/*)                           printf '%s' ".agents/skills/galdr-ymirsystem/assets/hlidskjalf-ui.md" ;;
+    *bin/mimir*)                                  printf '%s' ".agents/skills/galdr-ymirsystem/assets/memory-well.md" ;;
+    *bin/nornir-*|*config/cron.yaml)              printf '%s' ".agents/skills/galdr-ymirsystem/assets/nornir-jobs.md" ;;
+    *bin/valknut-load.sh|*/.pi/*|*/.opencode/*)   printf '%s' ".agents/skills/galdr-ymirsystem/assets/harness-integration/README.md" ;;
+    *bin/smidja*|*.agents/skills/smidja-factory/*)        printf '%s' ".agents/skills/galdr-ymirsystem/assets/smidja.md" ;;
+    *)                                            printf '' ;;
+  esac
+}
+
+ASSET="$(asset_for "$TARGET")"
+[ -n "$ASSET" ] || exit 0   # not governed — allow
+
+# Already loaded this session? Accept the asset recorded either as a repo-relative
+# path or as an absolute path (the harness records what it read, which may be
+# either); compare on a normalised suffix.
+if [ -f "$READS" ]; then
+  while IFS= read -r seen; do
+    [ -n "$seen" ] || continue
+    case "$seen" in
+      "$ASSET"|"$ROOT/$ASSET") exit 0 ;;
+    esac
+  done <"$READS"
+fi
+
+printf 'denied: %s is governed by %s\n' "$TARGET" "$ASSET" >&2
+printf 'help: read that asset first (the read is recorded automatically), then edit.\n' >&2
+printf 'why: a code change not reflected in its asset is an incomplete change.\n' >&2
+exit 2

package/bin/syn-cd-pretool-check.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# syn-cd-pretool-check.sh - PreToolUse seatbelt for directory-changing commands.
+#
+# Sýn guards the working directory. v0 is inert (always allow); the contract
+# exists so the Sýn Pi extension can deny a bash invocation that would strand
+# the primary outside its checkout. Owner: plan 29
+# (docs/plans/29-brokk-distro-runtime.md).
+#
+# Usage: syn-cd-pretool-check.sh --command <bash command>
+# Exit:  0 = allow, 2 = block (stderr carries the reason)
+set -u
+
+command_text=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --command) command_text=${2-}; shift 2 ;;
+    *) shift ;;
+  esac
+done
+
+case "$command_text" in
+  *'cd '*'/../'*)
+    printf 'denied: refusing a cd that escapes the Brokk home\n' >&2
+    exit 2
+    ;;
+esac
+
+exit 0

package/bin/syn-guard-pretool-check.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# syn-guard-pretool-check.sh - PreToolUse seatbelt for the runtime's load-bearing
+# invariants. Best-effort guardrail, NOT a security boundary: bash is too
+# expressive to sandbox here, so this denies the few shapes that silently break
+# something hard to detect — a hand-tampered lock, a clobbered supervision
+# marker, a rewritten audit chain, an edit to the seatbelt itself, a leaked
+# secret, or a silent change to a fleet-steering registry.
+#
+# Owned by the Sýn harness extension; wired beside syn-arm-pretool-check.sh.
+# Exit: 0 = allow, 2 = block (stderr carries the reason).
+set -u
+
+command_text=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --command) command_text=${2-}; shift 2 ;;
+    *) shift ;;
+  esac
+done
+[ -n "$command_text" ] || exit 0
+cmd="$command_text"
+
+deny() { printf 'denied: %s\n' "$1" >&2; exit 2; }
+
+# A destructive shape is one that removes, overwrites, or rewrites a path.
+destructive_on() {  # <needle>
+  local n=$1
+  case "$cmd" in
+    *" rm "*"$n"*|*"rm -"*"$n"*|*" mv "*"$n"*|*"mv -"*"$n"*) return 0 ;;
+    *"truncate"*"$n"*|*"sed -i"*"$n"*|*"tee "*"$n"*|*"dd "*"$n"*) return 0 ;;
+    *"chmod "*"$n"*|*"chown "*"$n"*) return 0 ;;
+    *">"*"$n"*) return 0 ;;
+  esac
+  return 1
+}
+
+# Reading a secret is itself the leak.
+reads_on() {  # <needle>
+  local n=$1
+  case "$cmd" in
+    *"cat "*"$n"*|*"less "*"$n"*|*"head "*"$n"*|*"tail "*"$n"*) return 0 ;;
+    *"grep"*"$n"*|*"rg"*"$n"*|*"printenv"*"$n"*|*"env "*"$n"*) return 0 ;;
+  esac
+  return 1
+}
+
+# 1. The session lock — owned by session-start / lease, never by hand.
+for n in 'state/.lock' '.lock-path' 'brokk.lock'; do
+  destructive_on "$n" && deny "the session lock ($n) is owned by session-start/lease; do not edit it by hand"
+done
+
+# 2. Supervision markers — a stale one silences the turn-end guard.
+for n in '.supervision-armed' '.watch.heartbeat' '.watcher-stop' '.wake-queue'; do
+  destructive_on "$n" && deny "the supervision marker ($n) is owned by the watcher/drain; do not edit it by hand"
+done
+
+# 3. The Runes ledger — an append-only hash chain; rewriting breaks the audit.
+for n in 'runes_audit.md' 'runes.lock'; do
+  destructive_on "$n" && deny "the Runes ledger ($n) is append-only; write through bin/runes-append.sh"
+done
+
+# 4. The seatbelt machinery — never edit what decides your own pass.
+for n in 'bin/syn-' '.pi/extensions/' '.opencode/plugins/' '.agents/harness/'; do
+  destructive_on "$n" && deny "the guard/extension machinery ($n) is off-limits to a bash mutation; change it through a reviewed commit"
+done
+
+# 5. Secrets — never read, echo, or stage them.
+for n in '.env.local' '.env.realm' 'auth.json' '.token'; do
+  destructive_on "$n" && deny "secrets ($n) must never be written or staged by a shell command"
+  reads_on "$n" && deny "secrets ($n) must never be read or echoed by a shell command"
+done
+case "$cmd" in
+  *"git add"*'.env.local'*|*"git add"*'.env.realm'*)
+    deny "never stage .env.local / .env.realm"
+    ;;
+esac
+
+# 6. Fleet-steering registries — route changes through their owning scripts.
+for n in 'data/eindri-homes.md' 'workspace/projects.yaml' 'config/cron.yaml'; do
+  destructive_on "$n" && deny "the registry ($n) steers the fleet; edit it deliberately, not with a shell rewrite"
+done
+
+exit 0

package/bin/syn-spawn-pretool-check.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# syn-spawn-pretool-check.sh - PreToolUse seatbelt for spawning and for typing.
+#
+# Sýn guards how workers are raised. The failure this exists to end, observed
+# live: an agent (me) hand-fired `herdr-run.sh eindri`, then delivered the brief
+# by TYPING it into the pane — and when the agent had already exited the brief
+# was typed into **bash**, where it sat as a command. Workers were "sent" and
+# never started, and text was executed in a shell. One door exists for this and
+# it is `bin/einherjar-spawn.sh` (firstmate's `fm-spawn.sh`, ported): it creates
+# the worktree, records `state/<id>.meta`, and fails closed on an unverified
+# harness.
+#
+# Usage: syn-spawn-pretool-check.sh --command <bash command>
+# Exit:  0 = allow, 2 = block (stderr carries the reason and the remedy)
+set -u
+
+command_text=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --command) command_text=${2-}; shift 2 ;;
+    *) shift ;;
+  esac
+done
+
+# 1. Never type into a pane. A brief is not keystrokes: typing lands in whatever
+#    owns the pane, and when the agent has exited that is the shell.
+case "$command_text" in
+  *"pane input"*|*"send-keys"*|*"pane type"*)
+    printf 'denied: do not type into a pane — a brief delivered as keystrokes lands in whatever owns it (a shell, once the agent has exited)\n' >&2
+    printf 'help: seat the worker through the door: bin/einherjar-spawn.sh <task-id> <project-dir> --mode local-only --harness opencode --model <model> --backend herdr\n' >&2
+    exit 2 ;;
+esac
+
+# 2. Never hand-raise an Eindri. `herdr-run.sh run` (a command in a pane) is
+#    fine; raising a WORKER by hand is not — it skips the worktree, the meta
+#    record, and the harness verification.
+case "$command_text" in
+  *"herdr-run.sh eindri"*|*"herdr-run.sh agent"*)
+    printf 'denied: an Eindri is raised through the door, not by hand — herdr-run.sh eindri skips the worktree, state/<id>.meta, and the harness check\n' >&2
+    printf 'help: bin/einherjar-spawn.sh <task-id> <project-dir> --mode <direct-PR|local-only|no-mistakes> [--harness <name>] [--model <name>] [--backend tmux|herdr]\n' >&2
+    exit 2 ;;
+esac
+
+# 3. A LOCAL model needs a live local server. Requesting one while the router is
+#    down is how a seat came up, errored, and left a shell behind.
+case "$command_text" in
+  *"einherjar-spawn.sh"*)
+    case "$command_text" in
+      *"llama-cpp/"*|*"llama.cpp/"*|*"lmstudio/"*|*"ollama/"*)
+        if ! (exec 3<>/dev/tcp/127.0.0.1/8080) 2>/dev/null; then
+          printf 'denied: a local model was requested but no local server answers on :8080 — the worker will start, fail, and leave a shell\n' >&2
+          printf 'help: raise the llama-router (bin/models-detect.sh reports what is served), or seat the worker on an online model\n' >&2
+          exit 2
+        fi ;;
+    esac ;;
+esac
+
+exit 0

package/bin/syn-turnend-guard.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# syn-turnend-guard.sh - refuse to let a Brokk turn end blind.
+#
+# Sýn guards the turn boundary: if supervision was armed and the watcher has
+# since gone missing or unhealthy, this prints the recovery instruction and
+# exits 2 so the harness extension can re-prompt instead of ending the turn.
+# Inert until the first successful arm (state/.supervision-armed). Ported from
+# the upstream agent-distro reference, retargeted for plan 29.
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="${BROKK_ROOT_OVERRIDE:-$(cd "$SCRIPT_DIR/.." && pwd)}"
+BROKK_HOME="${BROKK_HOME:-$ROOT}"
+STATE="${BROKK_STATE_OVERRIDE:-$BROKK_HOME/state}"
+STALE_SECONDS="${BROKK_WATCH_HEARTBEAT_STALE_SECONDS:-60}"
+
+# The hook contract passes {"stop_hook_active":false} on stdin; unused here.
+cat >/dev/null 2>&1 || true
+
+[ -f "$STATE/.supervision-armed" ] || exit 0
+
+heartbeat="$STATE/.watch.heartbeat"
+if [ -r "$heartbeat" ]; then
+  beat=$(tr -d '[:space:]' <"$heartbeat")
+  now=$(date -u +%s)
+  case "$beat" in
+    ''|*[!0-9]*) beat=0 ;;
+  esac
+  if [ "$((now - beat))" -le "$STALE_SECONDS" ]; then
+    exit 0
+  fi
+fi
+
+printf 'Brokk supervision is off: the watcher cycle is missing, failed, or unhealthy.\n' >&2
+printf 'Recovery: re-arm through the harness extension (gna_watch_arm). Do not end the turn blind.\n' >&2
+exit 2

package/bin/syn-watch-arm.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+# syn-watch-arm.sh - arm one Brokk supervision watcher cycle.
+#
+# Sýn ("the one who sees") watches the runtime state and exits with an
+# actionable `signal:`/`stale:`/`check:`/`heartbeat:` line when something needs
+# the primary. The Pi extension (gna-pi-watch.ts) owns continuity and re-arms.
+# Ported/trimmed from the upstream agent-distro reference for plan 29
+# (docs/plans/29-brokk-distro-runtime.md).
+#
+# Usage: syn-watch-arm.sh --restart
+#        syn-watch-arm.sh --handling-delivered <generation> --watcher-pid <pid>
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="${BROKK_ROOT_OVERRIDE:-$(cd "$SCRIPT_DIR/.." && pwd)}"
+BROKK_HOME="${BROKK_HOME:-$ROOT}"
+STATE="${BROKK_STATE_OVERRIDE:-$BROKK_HOME/state}"
+# shellcheck source=bin/gleipnir-lock-lib.sh
+. "$SCRIPT_DIR/gleipnir-lock-lib.sh"
+
+POLL_SECONDS="${BROKK_WATCH_POLL_SECONDS:-5}"
+HEARTBEAT_STALE_SECONDS="${BROKK_WATCH_HEARTBEAT_STALE_SECONDS:-60}"
+
+mkdir -p "$STATE"
+
+if [ "${1-}" = "--handling-delivered" ]; then
+  generation=${2-}
+  watcher_pid=${4-}
+  printf 'watcher: handling delivered generation=%s watcher-pid=%s\n' "$generation" "$watcher_pid"
+  exit 0
+fi
+
+lock_owner=$(gleipnir_lock_owner _lo 2>/dev/null; printf '%s' "${_lo:-}")
+if [ -z "$lock_owner" ] || ! gleipnir_pid_alive "$lock_owner"; then
+  # The helm is vacant: no owner, or an owner verifiably gone (dead, zombie,
+  # recycled, or a truncated/empty lock). Enter through the lib's acquire,
+  # which refuses only a genuinely live other session — so a vacant helm is
+  # taken here, never punted to a manual session start.
+  if ! gleipnir_lock_acquire; then
+    printf 'watcher: read-only - the session helm is held by another live session\n' >&2
+    exit 0
+  fi
+  lock_owner=$(gleipnir_lock_owner _lo 2>/dev/null; printf '%s' "${_lo:-}")
+fi
+
+GENERATION="${BROKK_WATCH_PREDECESSOR_ARM_PID:-arm}-$$"
+printf 'watcher: started pid=%s recovery-generation=%s\n' "$$" "$GENERATION"
+: >"$STATE/.supervision-armed"
+
+touch_heartbeat() { date -u +%s >"$STATE/.watch.heartbeat"; }
+
+actionable() {
+  # A non-empty wake queue or an actionable status append ends the cycle.
+  if [ -s "$STATE/.wake-queue" ]; then
+    printf 'signal: wake queue\n'
+    return 0
+  fi
+  local sig
+  sig=$(find "$STATE" -maxdepth 1 -name '*.signal' -print -quit 2>/dev/null || true)
+  if [ -n "$sig" ]; then
+    rm -f "$sig"
+    printf 'signal: %s\n' "$(basename "$sig" .signal)"
+    return 0
+  fi
+  local check
+  check=$(find "$STATE" -maxdepth 1 -name '*.check' -print -quit 2>/dev/null || true)
+  if [ -n "$check" ]; then
+    rm -f "$check"
+    printf 'check: %s\n' "$(basename "$check" .check)"
+    return 0
+  fi
+  if [ -f "$STATE/.watcher-stop" ]; then
+    rm -f "$STATE/.watcher-stop"
+    printf 'stale: watcher stopped by operator\n'
+    return 0
+  fi
+  return 1
+}
+
+touch_heartbeat
+while :; do
+  # The lock is a live-session contract, not an arm-time snapshot. If the
+  # harness that held this home's lock has exited — or a replacement never took
+  # it — this watcher is an orphan and must retire rather than beat forever for
+  # a dead session (which would also strand `state/.supervision-armed` with a
+  # fresh-enough heartbeat and silence the turn-end guard). Retiring is not
+  # actionable: it prints no `signal:`/`stale:`/`check:` line, so it never wakes
+  # a session.
+  lock_owner=$(gleipnir_lock_owner _lo 2>/dev/null; printf '%s' "${_lo:-}")
+  if [ -z "$lock_owner" ] || ! gleipnir_pid_alive "$lock_owner"; then
+    printf 'watcher: retired - session lock is no longer held\n' >&2
+    exit 0
+  fi
+  if actionable; then
+    exit 0
+  fi
+  sleep "$POLL_SECONDS"
+  touch_heartbeat
+done

package/bin/tailscale-sync.sh

@@ -0,0 +1,203 @@
+#!/usr/bin/env bash
+# tailscale-sync.sh — sync the Allfather's pi data across his OWN machines over
+# Tailscale. Peer-allowlisted, dry-runnable, never a central server.
+#
+#   bin/tailscale-sync.sh status            # tailnet + configured peers
+#   bin/tailscale-sync.sh init              # seed the config from its template
+#   bin/tailscale-sync.sh push [peer]       # local → peer (all peers if omitted)
+#   bin/tailscale-sync.sh pull <peer>       # peer → local
+#   bin/tailscale-sync.sh --dry-run push    # show what would move
+#   bin/tailscale-sync.sh --version
+#
+# Config: config/tailscale-sync.yaml (private, from the tracked .example).
+# Transport: rsync over ssh, addressed by Tailscale MagicDNS. No relay.
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(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
+CFG="${YMIR_TAILSCALE_SYNC:-$YMIR_SETTINGS_DIR/tailscale-sync.yaml}"
+DRY=0; ACTION=""; PEER=""
+
+for a in "$@"; do
+  case "$a" in
+    -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+    -h|--help) sed -n '2,14p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    --dry-run|-n) DRY=1 ;;
+    status|push|pull|check|init|receive) ACTION="$a" ;;
+    -*) printf 'error: unknown flag %s\n' "$a" >&2; exit 2 ;;
+    *) PEER="$a" ;;
+  esac
+done
+ACTION="${ACTION:-status}"
+
+have() { command -v "$1" >/dev/null 2>&1; }
+
+# Expand a leading ~ locally (rsync/taildrop receive it literally otherwise).
+expand_path() { case "$1" in "~/"*) printf '%s' "$HOME/${1#\~/}" ;; *) printf '%s' "$1" ;; esac; }
+
+if [ "$ACTION" = status ]; then
+  ts_state="absent"; ts_self=""
+  if have tailscale; then
+    ts_state="$(tailscale status --json 2>/dev/null | python3 -c 'import json,sys
+try:
+    d=json.load(sys.stdin); print(d.get("BackendState") or "unknown")
+except Exception: print("unavailable")' 2>/dev/null)"
+    ts_self="$(tailscale status --json 2>/dev/null | python3 -c 'import json,sys
+try:
+    d=json.load(sys.stdin); print((d.get("Self") or {}).get("DNSName") or "")
+except Exception: pass' 2>/dev/null)"
+  else
+    ts_state="not installed"
+  fi
+  online=""
+  if have tailscale; then
+    online="$(tailscale status 2>/dev/null | awk 'NR>1 && $0 !~ /offline/ {print $2}' | paste -sd, -)"
+  fi
+  peers="none"
+  [ -r "$CFG" ] && peers="$(python3 -c 'import yaml,sys; d=yaml.safe_load(open(sys.argv[1])) or {}; print(",".join(p if isinstance(p,str) else p.get("host","") for p in (d.get("peers") or [])))' "$CFG" 2>/dev/null)"
+  printf 'tailscale-sync[1]{backend,self,online,peers,config}:\n'
+  printf '  "%s","%s","%s","%s","%s"\n' "$ts_state" "${ts_self:-?}" "${online:-none}" "${peers:-none}" "$( [ -r "$CFG" ] && echo present || echo "absent (bin/tailscale-sync.sh init)" )"
+  exit 0
+fi
+
+if [ "$ACTION" = init ]; then
+  TPL="$YMIR_SETTINGS_DIR/tailscale-sync.example.yaml"
+  if [ -r "$CFG" ]; then printf 'tailscale-sync[1]{action,state}:\n  "init","kept — %s exists"\n' "$CFG"; exit 0; fi
+  [ -r "$TPL" ] || { printf 'error: template missing: %s\n' "$TPL" >&2; exit 1; }
+  cp "$TPL" "$CFG" && printf 'tailscale-sync[1]{action,path}:\n  "init","%s"\n' "$CFG"
+  exit 0
+fi
+
+[ -r "$CFG" ] || { printf 'error: no config %s\nhelp: bin/tailscale-sync.sh init\n' "$CFG" >&2; exit 1; }
+have tailscale || { printf 'error: tailscale is not installed\nhelp: https://tailscale.com/download\n' >&2; exit 1; }
+have rsync || { printf 'error: rsync is not installed\n' >&2; exit 1; }
+[ "$(tailscale status --json 2>/dev/null | python3 -c 'import json,sys;print((json.load(sys.stdin) or {}).get("BackendState",""))' 2>/dev/null)" = "Running" ] \
+  || { printf 'error: tailscale is not up\nhelp: sudo tailscale up\n' >&2; exit 1; }
+
+# The config drives every transfer: peers (allowlist) + paths (what may move).
+mapfile -t META < <(python3 - "$CFG" "$PEER" <<'PY'
+import sys, yaml
+cfg = yaml.safe_load(open(sys.argv[1])) or {}
+only = sys.argv[2]
+peers = cfg.get("peers") or []
+def host(p): return p if isinstance(p, str) else (p.get("host") or "")
+print("include_auth=%s" % ("1" if cfg.get("include_auth") else "0"))
+for p in peers:
+    h = host(p)
+    if h and (not only or h == only):
+        print("peer=%s" % h)
+for path in (cfg.get("paths") or []):
+    print("path=%s" % path)
+PY
+)
+include_auth=0; PEERS=(); PATHS=()
+for line in "${META[@]:-}"; do
+  case "$line" in
+    include_auth=*) include_auth="${line#*=}" ;;
+    peer=*) PEERS+=("${line#*=}") ;;
+    path=*) PATHS+=("${line#*=}") ;;
+  esac
+done
+[ "${#PEERS[@]}" -gt 0 ] || { printf 'error: no matching peer\nhelp: bin/tailscale-sync.sh status\n' >&2; exit 1; }
+[ "${#PATHS[@]}" -gt 0 ] || { printf 'error: config lists no paths\n' >&2; exit 1; }
+[ "$include_auth" = 1 ] || PATHS=("${PATHS[@]/~\/.pi\/agent\/auth.json/}")
+
+rsync_flags=(-a --info=NAME --exclude 'sessions/' --exclude '*.log')
+if [ "$ACTION" = check ]; then
+  # verify: parity-only walk. --checksum compares content, not just size/time;
+  # --dry-run moves nothing; --itemize-changes names what WOULD differ. Exit 0
+  # when the far end already mirrors the near end, 1 when anything drifts
+  # (added/changed/missing/deleted) — the hoard's collision and loss alarm.
+  check_flags=(-a -c --dry-run --itemize-changes --exclude 'sessions/' --exclude '*.log')
+  [ "$DRY" = 1 ] && check_flags+=(--dry-run)
+  rc=0
+  ssh_cmd="${YMIR_SSH:-ssh -o StrictHostKeyChecking=accept-new -o ConnectTimeout=10}"
+  for peer in "${PEERS[@]}"; do
+    for path in "${PATHS[@]}"; do
+      [ -n "$path" ] || continue
+      case "$path" in auth.json|*auth.json) [ "$include_auth" = 1 ] || continue ;; esac
+      src="$(expand_path "$path")"; dst="$peer:$path"
+      printf 'tailscale-sync[1]{action,peer,path}:
+  "check","%s","%s"\n' "$peer" "$path"
+      out=$(rsync "${check_flags[@]}" -e "$ssh_cmd" --mkpath "$src" "$dst" 2>&1) || rc=1
+      changes=$(printf '%s\n' "$out" | grep -cE '^[<>ch.*]' || true)
+      if [ "${changes:-0}" -gt 0 ]; then
+        printf 'tailscale-sync[1]{state,path,drift}:
+  "DRIFT","%s","%s lines differ"\n' "$path" "$changes"
+      else
+        printf 'tailscale-sync[1]{state,path,parity}:
+  "IN SYNC","%s"\n' "$path"
+      fi
+    done
+  done
+  [ "$rc" = 0 ] && printf 'tailscale-sync[1]{verdict}:
+  "hoard mirrors the far end"\n' || printf 'tailscale-sync[1]{verdict}:
+  "DRIFT — run push to reconcile"\n'
+  exit "$rc"
+fi
+
+[ "$DRY" = 1 ] && rsync_flags+=(--dry-run)
+
+# Taildrop road: when the tailnet's SSH ACL forbids SSH (but Taildrop works),
+# bundle the configured paths into ONE tarball and send that — Taildrop carries
+# files, not folders. The peer runs `receive` to fetch and unpack.
+if [ "${YMIR_SYNC_VIA:-rsync}" = taildrop ]; then
+  [ "$ACTION" = push ] || { printf 'error: taildrop transport supports push (and receive on the peer)\n' >&2; exit 2; }
+  rel=()
+  for path in "${PATHS[@]}"; do
+    [ -n "$path" ] || continue
+    case "$path" in auth.json|*auth.json) [ "$include_auth" = 1 ] || continue ;; esac
+    case "$path" in "~/"*) rel+=("${path#\~/}") ;; *) rel+=("$path") ;; esac
+  done
+  tmp="$(mktemp -d)"; bundle="$tmp/ymir-sync-$(hostname -s)-$(date +%Y%m%d-%H%M%S).tar.gz"
+  tar -czf "$bundle" -C "$HOME" "${rel[@]}" 2>/dev/null || { printf 'error: could not bundle paths\n' >&2; exit 1; }
+  rc=0
+  for peer in "${PEERS[@]}"; do
+    printf 'tailscale-sync[1]{via,peer,bundle}:\n  "taildrop","%s","%s"\n' "$peer" "$(basename "$bundle")"
+    tailscale file cp "$bundle" "$peer:" || rc=1
+  done
+  rm -rf "$tmp"
+  exit "$rc"
+fi
+
+# receive — on the peer: fetch the Taildrop inbox and unpack any ymir-sync bundle
+# into $HOME (paths were stored relative to HOME).
+if [ "$ACTION" = receive ]; then
+  dir="${PEER:-$HOME/Downloads}"; mkdir -p "$dir"
+  tailscale file get "$dir" || exit 1
+  rc=0
+  for b in "$dir"/ymir-sync-*.tar.gz; do
+    [ -e "$b" ] || continue
+    printf 'tailscale-sync[1]{action,bundle}:\n  "receive","%s"\n' "$(basename "$b")"
+    tar -xzf "$b" -C "$HOME" || rc=1
+    rm -f "$b"
+  done
+  exit "$rc"
+fi
+
+ssh_cmd="${YMIR_SSH:-ssh -o StrictHostKeyChecking=accept-new -o ConnectTimeout=10}"
+rc=0
+for peer in "${PEERS[@]}"; do
+  for path in "${PATHS[@]}"; do
+    [ -n "$path" ] || continue
+    case "$path" in auth.json|*auth.json) [ "$include_auth" = 1 ] || continue ;; esac
+    if [ "$ACTION" = push ]; then src="$(expand_path "$path")"; dst="$peer:$path"; else src="$peer:$path"; dst="$(expand_path "$path")"; fi
+    printf 'tailscale-sync[1]{dir,peer,path}:\n  "%s","%s","%s"\n' "$ACTION" "$peer" "$path"
+    rsync "${rsync_flags[@]}" -e "$ssh_cmd" --mkpath "$src" "$dst" || rc=1
+  done
+done
+exit "$rc"