@zerwiz/ymir 0.1.4 → 0.1.7

package/bin/hlidskjalf-agents.sh

@@ -0,0 +1,172 @@
+#!/usr/bin/env bash
+# hlidskjalf-agents.sh — WHO IS ACTUALLY STANDING, and what they are doing.
+#
+# The control plane showed the ROSTER: the twenty profiles that *could* run.
+# A roster is a leaflet; the panes are the truth. This reads the live pane list
+# (herdr) and emits the sessions that exist right now, so the Fleet gate shows a
+# fleet rather than a painting of one — every opencode and pi session, with its
+# kind, its state, its pane and where it works.
+#
+#   bin/hlidskjalf-agents.sh            # JSON (what /api/agents serves)
+#   bin/hlidskjalf-agents.sh --toon     # TOON (for a human at a terminal)
+#
+# State comes from the pane's own reported status. Nothing here infers liveness
+# from a process list or from prose: if herdr does not say an agent is there, it
+# is not on the board.
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+HERDR="${HERDR_BIN_PATH:-herdr}"
+MODE="json"
+[ "${1:-}" = "--toon" ] && MODE="toon"
+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
+
+command -v "$HERDR" >/dev/null 2>&1 || { [ "$MODE" = json ] && printf '[]\n' || printf 'agents[0]{name}:\n'; exit 0; }
+
+raw="$("$HERDR" pane list 2>/dev/null)"
+
+MODE="$MODE" RAW="$raw" python3 - <<'PY'
+import json, os, sys
+
+mode = os.environ.get("MODE", "json")
+raw = os.environ.get("RAW", "")
+
+ROSTER_DIR = os.environ.get("ROSTER_DIR", ".agents/agents")
+
+def panes():
+    """The STANDING seats: a herdr pane an agent runs in. A pane is the WHERE."""
+    try:
+        d = json.loads(raw)
+    except Exception:
+        return []
+    pl = (d.get("result") or {}).get("panes") or d.get("panes") or []
+    out = []
+    for p in pl:
+        agent = p.get("agent") or ""
+        if not agent and p.get("agent_status") in (None, "", "unknown"):
+            continue
+        title = (p.get("terminal_title_stripped") or p.get("terminal_title") or "").strip()
+        out.append({
+            "id": p.get("pane_id", ""),
+            "name": title.split("|")[0].strip() or agent or p.get("pane_id", ""),
+            "harness": agent or "agent",
+            "state": p.get("agent_status") or "unknown",
+            "title": title,
+            "cwd": p.get("foreground_cwd") or p.get("cwd") or "",
+            "workspace": p.get("workspace_id", ""),
+            "task": title.split("|", 1)[1].strip() if "|" in title else "",
+            "matched": False,
+        })
+    return out
+
+
+def roster():
+    """The AGENTS, from the canonical roster (.agents/agents/*.md).
+
+    A pane is the where; this is the WHO. Emitting panes alone is why the Fleet
+    showed thirteen OpenCode terminals and not one of the smiths who might be
+    standing in them. The roster is canonical (RULES/02); a harness seat is not an
+    agent, and an agent is not its seat.
+    """
+    try:
+        files = sorted(f for f in os.listdir(ROSTER_DIR) if f.endswith(".md"))
+    except Exception:
+        return []
+    out = []
+    for f in files:
+        stem = f[:-3]
+        parts = stem.split("-")
+        model = mode = domain = ""
+        try:
+            with open(os.path.join(ROSTER_DIR, f)) as fh:
+                txt = fh.read(6000)
+            if txt.startswith("---"):
+                for line in txt.split("---", 2)[1].splitlines():
+                    if line.startswith("model:") and not model:
+                        model = line.split(":", 1)[1].strip()
+                    if line.startswith("mode:") and not mode:
+                        mode = line.split(":", 1)[1].strip()
+                    if line.startswith("domain:") and not domain:
+                        domain = line.split(":", 1)[1].strip()
+        except Exception:
+            pass
+        out.append({
+            "stem": stem,
+            "figure": parts[0],
+            "craft": parts[1] if len(parts) > 1 else "agent",
+            "model": model,
+            "mode": mode,
+            "domain": domain,
+        })
+    return out
+
+
+ps = panes()
+rs = roster()
+rows = []
+
+def card(name, role, model, state, domain="ymirlabs", pane=None, task="", where=""):
+    status = {"working": "nominal", "idle": "nominal", "unseated": "seated"}.get(state, "degraded")
+    return {
+        "id": pane["id"] if pane else "roster:" + name,
+        "name": name,
+        "role": role,
+        "realm": "work",
+        "domain": domain,
+        "status": status,
+        "capabilities": [],
+        "skills": [],
+        "interface": {
+            "protocol": "a2a/1.0",
+            "endpoint": ("local://%s" % pane["id"]) if pane else "",
+            "signed": False,
+        },
+        "model": model or (pane["harness"] if pane else ""),
+        "uptime": 0,
+        "tasksDone": 0,
+        "kind": role,
+        "state": state,
+        "pane": pane["id"] if pane else "",
+        "cwd": (pane["cwd"] if pane else where),
+        "task": task,
+        "live": ({
+            "kind": pane["harness"], "state": state, "pane": pane["id"],
+            "workspace": pane["workspace"], "cwd": pane["cwd"], "task": pane["task"],
+        } if pane else None),
+    }
+
+# THE AGENTS FIRST — every smith on the roster, seated or not. An unseated agent is
+# still an agent; hiding it made the board look like a rack of terminals.
+for a in rs:
+    hit = None
+    for p in ps:
+        hay = ("%s %s %s" % (p["name"], p["harness"], p["title"])).lower()
+        if a["figure"] and a["figure"] in hay:
+            p["matched"] = True
+            hit = p
+            break
+    rows.append(card(a["figure"], a["craft"], a["model"],
+                     hit["state"] if hit else "unseated",
+                     domain=a["domain"] or "ymirlabs",
+                     pane=hit, task=hit["task"] if hit else ""))
+
+# Harness seats that answer to no one on the roster: kept visible, named honestly.
+for p in ps:
+    if not p["matched"]:
+        rows.append(card(p["name"], p["harness"], p["harness"], p["state"], pane=p,
+                         task=p["task"]))
+
+if mode == "json":
+    print(json.dumps(rows))
+    raise SystemExit
+
+print("agents[%d]{name,kind,state,pane,cwd,task}:" % len(rows))
+for r in rows:
+    q = lambda s: '"%s"' % str(s).replace('"', '\\"')
+    print("  %s,%s,%s,%s,%s,%s" % (q(r["name"]), q(r["kind"]), q(r["state"]), q(r["pane"]), q(r["cwd"]), q(r["task"])))
+if not rows:
+    print("agents: 0 live sessions — nothing is standing")
+PY

package/bin/hlidskjalf-usage.sh

@@ -0,0 +1,196 @@
+#!/usr/bin/env bash
+# hlidskjalf-usage.sh — what the HARNESSES spent, not just the smithy.
+#
+# The Statistics gate counted only smithy runs (smidja.db), so a machine burning
+# tokens through opencode and pi from morning to night reported "No runs yet". The
+# sessions are the usage; this reads them.
+#
+#   bin/hlidskjalf-usage.sh [--days N]   # JSON, aggregated
+#
+# SOURCES (verified on this machine):
+#   opencode  ~/.local/share/opencode/opencode.db  (SQLite, Drizzle)
+#             session / message / part; usage lives in message.data as JSON:
+#             {role, modelID, providerID, cost, tokens:{total,input,output,
+#              reasoning,cache:{read,write}}}. cost is stored 0 - tokens are truth.
+#   pi        ~/.pi/agent/sessions/**/*.jsonl
+#
+# BOUNDED BY CONSTRUCTION: the db here is 37 GB and holds 132k messages. Nothing
+# loads rows into the UI - the aggregation is one SQL statement with json_extract,
+# a time window, and a hard row cap, and the result is small by definition.
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+case "${1-}" in
+  -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h|--help) sed -n '2,18p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+esac
+
+DAYS="${YMIR_USAGE_DAYS:-30}"
+while [ $# -gt 0 ]; do
+  case "$1" in --days) DAYS="${2:-30}"; shift 2 ;; *) shift ;; esac
+done
+
+DAYS="$DAYS" python3 - <<'PY'
+import json, os, sqlite3, sys, glob
+from datetime import datetime, timedelta, timezone
+
+days = int(os.environ.get("DAYS", "30"))
+since_ms = int((datetime.now(timezone.utc) - timedelta(days=days)).timestamp() * 1000)
+out = {"window_days": days, "sources": {}, "totals": {}, "by_model": []}
+
+oc = os.path.expanduser("~/.local/share/opencode/opencode.db")
+if os.path.exists(oc):
+    try:
+        c = sqlite3.connect("file:%s?mode=ro" % oc, uri=True)
+        c.execute("PRAGMA query_only=ON")
+        # One statement, aggregated in the engine: never the rows, only the sums.
+        rows = c.execute("""
+            select coalesce(json_extract(data,'$.modelID'),'unknown') model,
+                   count(*) msgs,
+                   sum(coalesce(json_extract(data,'$.tokens.input'),0)) input,
+                   sum(coalesce(json_extract(data,'$.tokens.output'),0)) output,
+                   sum(coalesce(json_extract(data,'$.tokens.cache.read'),0)) cache_read,
+                   sum(coalesce(json_extract(data,'$.tokens.cache.write'),0)) cache_write,
+                   sum(coalesce(json_extract(data,'$.tokens.reasoning'),0)) reasoning
+            from message
+            where json_extract(data,'$.tokens') is not null
+              and coalesce(json_extract(data,'$.time.created'), 0) >= ?
+            group by model order by (sum(coalesce(json_extract(data,'$.tokens.input'),0))
+                                   + sum(coalesce(json_extract(data,'$.tokens.output'),0))) desc
+            limit 40
+        """, (since_ms,)).fetchall()
+        rows = [r for r in rows if r[1]]
+        out["sources"]["opencode"] = {
+            "model": "harness",
+            "messages": sum(r[1] for r in rows),
+            "input": sum(r[2] for r in rows), "output": sum(r[3] for r in rows),
+            "cache_read": sum(r[4] for r in rows), "cache_write": sum(r[5] for r in rows),
+            "reasoning": sum(r[6] for r in rows),
+        }
+        out["by_model"] += [
+            {"source": "opencode", "model": r[0], "messages": r[1], "input": r[2],
+             "output": r[3], "cache_read": r[4], "cache_write": r[5], "reasoning": r[6]}
+            for r in rows
+        ]
+    except Exception as e:
+        out["sources"]["opencode"] = {"error": str(e)[:120]}
+
+# pi keeps TWO stores: the agent home and the older tree beside it. Scanning only
+# one under-reported the harness by an order of magnitude (75 messages against 657
+# session files), which is how a "small number" masks a missing source.
+pi_files = []
+for root in ("~/.pi/agent/sessions", "~/.pi/sessions"):
+    pi_files += glob.glob(os.path.expanduser(root + "/**/*.jsonl"), recursive=True)
+if pi_files:
+    agg = {"input": 0, "output": 0, "cache_read": 0, "cache_write": 0, "messages": 0}
+    models = {}
+    for f in pi_files:
+        try:
+            with open(f, "r", errors="ignore") as fh:
+                for line in fh:
+                    if '"tokens"' not in line and '"usage"' not in line:
+                        continue
+                    try:
+                        d = json.loads(line)
+                    except Exception:
+                        continue
+                    t = d.get("tokens") or d.get("usage") or {}
+                    if not t:
+                        continue
+                    inp = t.get("input") or t.get("input_tokens") or 0
+                    outp = t.get("output") or t.get("output_tokens") or 0
+                    cr = (t.get("cache") or {}).get("read") or t.get("cache_read_input_tokens") or 0
+                    cw = (t.get("cache") or {}).get("write") or t.get("cache_creation_input_tokens") or 0
+                    agg["input"] += inp; agg["output"] += outp
+                    agg["cache_read"] += cr; agg["cache_write"] += cw; agg["messages"] += 1
+                    m = d.get("modelID") or d.get("model") or "unknown"
+                    mm = models.setdefault(m, {"input": 0, "output": 0, "messages": 0})
+                    mm["input"] += inp; mm["output"] += outp; mm["messages"] += 1
+        except Exception:
+            continue
+    out["sources"]["pi"] = {"model": "harness", **agg}
+    out["by_model"] += [{"source": "pi", "model": k, **v} for k, v in
+                        sorted(models.items(), key=lambda kv: -(kv[1]["input"] + kv[1]["output"]))[:20]]
+
+tot = {"messages": 0, "input": 0, "output": 0, "cache_read": 0, "cache_write": 0, "reasoning": 0}
+for s in out["sources"].values():
+    for k in tot:
+        tot[k] += int(s.get(k) or 0)
+tot["total"] = tot["input"] + tot["output"]
+prompt = tot["input"] + tot["cache_read"]
+# local = our own hardware; online = a cloud API. By model id, honestly.
+LOCAL_MARKERS = ("llama", "lmstudio", "ollama", "local", "qwen3.6-35b-a3b")
+for m in out["by_model"]:
+    mid = str(m.get("model", "")).lower()
+    m["kind"] = "local" if any(k in mid for k in LOCAL_MARKERS) else "online"
+
+def _empty():
+    return {"tokens": 0, "calls": 0, "input": 0, "output": 0, "cache_read": 0}
+lo = {"local": _empty(), "online": _empty()}
+for m in out["by_model"]:
+    k = m.get("kind", "online")
+    lo[k]["tokens"] += int(m.get("input") or 0) + int(m.get("output") or 0)
+    lo[k]["calls"] += int(m.get("messages") or 0)
+    lo[k]["input"] += int(m.get("input") or 0)
+    lo[k]["output"] += int(m.get("output") or 0)
+    lo[k]["cache_read"] += int(m.get("cache_read") or 0)
+out["local_online"] = lo
+
+# the gate's section names, filled from the harnesses
+oc = out["sources"].get("opencode", {})
+pi = out["sources"].get("pi", {})
+out["runs"] = {
+    "total": int(tot["messages"]), "success": int(tot["messages"]), "fail": 0, "running": 0,
+    "success_rate": 100.0 if tot["messages"] else 0.0,
+    "tokens": int(tot["input"]) + int(tot["output"]),
+    "cost": 0,
+    "by_source": {"opencode": int(oc.get("messages") or 0), "pi": int(pi.get("messages") or 0)},
+}
+out["by_chain"] = [
+    {"chain": m.get("source", "harness"), "workflow": m.get("source", "harness"),
+     "runs": int(m.get("messages") or 0), "success": int(m.get("messages") or 0),
+     "rate": 100.0, "tokens": int(m.get("input") or 0) + int(m.get("output") or 0), "cost": 0}
+    for m in out["by_model"][:12]
+]
+
+tot["cache_hit_ratio"] = round(tot["cache_read"] / prompt, 4) if prompt else 0.0
+out["totals"] = tot
+
+# THE GATE'S OWN NAMES, filled from the harnesses - so Statistics reports pi and
+# opencode, and the smithy's runs stay the smithy's.
+out["gate"] = {
+    "totals": {
+        "runs": int(tot["messages"]), "success": int(tot["messages"]), "fail": 0,
+        "running": 0, "tokens": int(tot["input"]) + int(tot["output"]), "cost": 0,
+    },
+    "usage": {
+        "input": int(tot["input"]), "output": int(tot["output"]),
+        "cache_read": int(tot["cache_read"]), "cache_write": int(tot["cache_write"]),
+        "total": int(tot["input"]) + int(tot["output"]),
+    },
+    "providers": {
+        "local":  {"events": lo["local"]["calls"],  "sessions": lo["local"]["calls"],
+                   "tokens": lo["local"]["tokens"],  "cost": 0,
+                   "input": lo["local"]["tokens"],  "output": 0, "cache_read": 0},
+        "online": {"events": lo["online"]["calls"], "sessions": lo["online"]["calls"],
+                   "tokens": lo["online"]["tokens"], "cost": 0,
+                   "input": lo["online"]["input"],  "output": lo["online"]["output"], "cache_read": lo["online"]["cache_read"]},
+        "per_model": [
+            {"model": m["model"], "agent": m.get("source", "harness"), "kind": m.get("kind", "online"),
+             "cells": int(m.get("messages") or 0), "tokens": int(m.get("input") or 0) + int(m.get("output") or 0), "cost": 0}
+            for m in out["by_model"]
+        ],
+    },
+    "by_chain": out["by_chain"],
+    "by_model": [
+        {"model": m["model"], "agent": m.get("source", "harness"), "kind": m.get("kind", "online"),
+         "cells": int(m.get("messages") or 0),
+         "tokens": int(m.get("input") or 0) + int(m.get("output") or 0), "cost": 0}
+        for m in out["by_model"]
+    ],
+}
+
+print(json.dumps(out))
+PY

package/bin/hoard-guard.sh

@@ -0,0 +1,135 @@
+#!/usr/bin/env bash
+# hoard-guard.sh — the ward for the PRIVATE HOME repo ($YMIR_HOME).
+#
+# Why this exists: the public repo has six guards, the home had none — yet the
+# home is where every private byte lives. The one real leak of 2026-09-17
+# (platform.env.prev-fill, 44 credentials) happened HERE, in a scratch backup
+# swept up by `git add -A`. Nothing was watching.
+#
+# This is not a script an agent must remember to run. It is seated as
+# .git/hooks/pre-commit in the home repo, so GIT runs it on every commit —
+# including the ones made in a hurry, by a loop, or by an agent that has never
+# heard of it.
+#
+#   bin/hoard-guard.sh            # scan the staged change (used as pre-commit)
+#   bin/hoard-guard.sh --install  # seat it in $YMIR_HOME/.git/hooks/pre-commit
+#   bin/hoard-guard.sh --all      # scan every tracked file in the home
+#   bin/hoard-guard.sh --log-bypass <reason>   # record a --no-verify commit
+#
+# Exit 1 on any hit, so the commit is blocked before the secret is committed.
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=bin/hoard-lib.sh
+. "$SCRIPT_DIR/hoard-lib.sh"
+hoard_root HOARD
+HOME_REPO="$(cd "$HOARD/.." && pwd)"
+LEDGER="$HOARD/memory/runes_audit.md"
+
+case "${1:-}" in
+  -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h|--help) sed -n '2,20p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+  --install)
+    [ -d "$HOME_REPO/.git" ] || { printf 'hoard-guard: not a git repo: %s\n' "$HOME_REPO" >&2; exit 1; }
+    hook="$HOME_REPO/.git/hooks/pre-commit"
+    mkdir -p "$(dirname "$hook")" || exit 1
+    printf '#!/usr/bin/env bash\n# seated by bin/hoard-guard.sh --install — the ward for the private home\nexec "%s/hoard-guard.sh" "$@"\n' "$SCRIPT_DIR" >"$hook"
+    chmod +x "$hook"
+    printf 'hoard-guard[1]{action,path}:\n  "install","%s"\n' "$hook"
+    exit 0 ;;
+  --log-bypass)
+    # Called when a --no-verify commit is detected, so a bypass is visible after
+    # the fact rather than silent.
+    mkdir -p "$(dirname "$LEDGER")" 2>/dev/null || true
+    printf '%s | hoard-guard BYPASS | %s | %s\n' \
+      "$(date -Is)" "${1:-no reason given}" "$(git -C "$HOME_REPO" log -1 --format=%h 2>/dev/null || echo unknown)" >>"$LEDGER" 2>/dev/null || true
+    printf 'hoard-guard[1]{action,logged}:\n  "bypass","%s"\n' "$LEDGER"
+    exit 0 ;;
+esac
+
+# ── The checks ────────────────────────────────────────────────────────────────
+# Every shape that caused, or could cause, a real leak.
+SECRET_SHAPES='(AKIA[0-9A-Z]{16}|-----BEGIN [A-Z ]*PRIVATE KEY-----|-----BEGIN OPENSSH PRIVATE KEY-----|(ghp|gho|ghs|ghr)_[A-Za-z0-9]{36}|github_pat_[A-Za-z0-9_]{20,}|sk-[A-Za-z0-9]{20,}|xox[baprs]-[A-Za-z0-9-]+|AIza[0-9A-Za-z_-]{35}|npm_[A-Za-z0-9]{30,})'
+
+# Filenames that must never be tracked: plaintext vault files, scratch backups,
+# anything that is a copy of a secret under another name.
+BAD_NAME_RE='(^|/)(platform\.env|id_rsa|id_ed25519|\.env\.local|\.env\.realm)$'
+SCRATCH_RE='(\.prev-|\.prev\.|\.bak$|\.orig$|\.scratch$|\.save$|~$|\.env\.[0-9])'
+# Deliberately allowed: age.key IS the vault key and is committed by decision
+# (see hodd/docs/secrets-vault.md). It is exempt BY NAME, in one place, so the
+# exception is auditable rather than accidental.
+ALLOWED_RE='^hodd/secrets/age\.key$'
+
+why() { printf 'hoard-guard: %s: %s\n' "$2" "$1" >&2; }
+
+# A base64 blob whose DECODE contains a PEM header — the evasion that would have
+# hidden a key. The data arrives on fd 3, NOT stdin: a heredoc on stdin would
+# otherwise consume the pipe and the checker would read nothing.
+check_base64_pem() {  # <path-in-repo>; data on fd 3
+  local f=$1
+  python3 - "$f" /dev/fd/3 3<&3 <<'PY'
+import base64, re, sys
+try:
+    data = open(sys.argv[2], 'rb').read()
+except OSError:
+    sys.exit(0)
+for m in re.finditer(rb'[A-Za-z0-9+/=]{120,}', data):
+    chunk = m.group(0)
+    for cand in (chunk, chunk + b'=' * (-len(chunk) % 4)):
+        try:
+            dec = base64.b64decode(cand, validate=True)
+        except Exception:
+            continue
+        if b'PRIVATE KEY' in dec or b'BEGIN OPENSSH' in dec:
+            print(f"hoard-guard: possible secret in {sys.argv[1]} (base64-encoded key)", file=sys.stderr)
+            sys.exit(1)
+sys.exit(0)
+PY
+}
+
+scan_list() {
+  local hit=0 f blob
+  while IFS= read -r f; do
+    [ -n "$f" ] || continue
+
+    case "$f" in
+      */.gitignore|.gitignore) continue ;;
+    esac
+    if printf '%s' "$f" | grep -Eq "$ALLOWED_RE"; then continue; fi
+
+    if printf '%s' "$f" | grep -Eq "$BAD_NAME_RE"; then
+      why "$f" "plaintext secret file"; hit=1; continue
+    fi
+    if printf '%s' "$f" | grep -Eq "$SCRATCH_RE"; then
+      why "$f" "scratch/backup file — this is the shape that leaked on 2026-09-17"
+      hit=1; continue
+    fi
+
+    # Text only — a binary (sqlite, engram, image) has no secret shape to read
+    # and would only emit null-byte noise.
+    case "$f" in
+      *.engram|*.engram-wal|*.engram-shm|*.db|*.db-wal|*.db-shm|*.png|*.jpg|*.jpeg|*.gif|*.pdf|*.zip|*.gz|*.tar|*.woff|*.woff2|*.ttf|*.ico|*.icns) continue ;;
+    esac
+    blob="$(git -C "$HOME_REPO" show ":$f" 2>/dev/null | head -c 400000 | tr -d '\000')" || continue
+    [ -n "$blob" ] || continue
+
+    if printf '%s' "$blob" | grep -Eq "$SECRET_SHAPES"; then
+      why "$f" "possible secret"; hit=1; continue
+    fi
+    if ! check_base64_pem "$f" 3< <(printf '%s' "$blob"); then hit=1; fi
+  done
+  return "$hit"
+}
+
+if [ "${1:-}" = "--all" ]; then
+  scan_list < <(git -C "$HOME_REPO" ls-files)
+else
+  scan_list < <(git -C "$HOME_REPO" diff --cached --name-only --diff-filter=ACM)
+fi || {
+  printf '\nhoard-guard: BLOCKED — the home repo is the vault. Do not commit this.\n' >&2
+  printf '  move the secret to hodd/secrets/platform.env.age (encrypted)\n' >&2
+  printf '  or delete the scratch file; see hodd/docs/secrets-vault.md\n' >&2
+  exit 1
+}
+exit 0

package/bin/hoard-lib.sh

@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+# hoard-lib.sh — where the operator's HOME lives, and the two roots beneath it.
+#
+# The law (RULES/04-hoard.md): no private thing — not a name, a key, a plan, a
+# schedule, a client, a note — ever sits inside this repo. It lives in ONE place
+# the operator OWNS and CHOSE at installation, and every script resolves that
+# place HERE, so the answer can never drift between them (Rule 07: configuration
+# is never hardcoded; ONE documented default).
+#
+#   ymir_home_root   the chosen home        ($YMIR_HOME → the recorded choice → the default)
+#   hoard_root       the hoard within it    ($YMIR_HOARD → <home>/hodd)
+#   hoard_data_dir   this machine's records ($YMIR_DATA_DIR → <hoard>/data)
+#   hoard_state_dir  runtime state          ($YMIR_STATE_DIR → <home>/state)
+#
+# The recorded choice is machine state, not user data: a path under
+# `~/.config/ymir/` (the same place `engram-python` and `accounts.json` live), so
+# a packaged install can be told where the home is without the home having to sit
+# in the package. The tree is code; the home is the operator's.
+#
+# Source-safe, defines functions only; call `<fn> <result-var>`.
+set -u
+
+# Where a machine records its choices (never in the repo, never in the home).
+YMIR_CONFIG_DIR="${YMIR_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/ymir}"
+YMIR_HOME_DEFAULT="${YMIR_HOME_DEFAULT:-$HOME/Documents/Ymir}"
+
+ymir_home_record() {  # <result-var> — the home recorded at installation, or empty
+  local result_var=${1-} f="$YMIR_CONFIG_DIR/home"
+  [ -n "$result_var" ] || return 2
+  if [ -r "$f" ]; then
+    printf -v "$result_var" '%s' "$(head -n1 "$f" 2>/dev/null | tr -d '[:space:]')"
+  else
+    printf -v "$result_var" '%s' ""
+  fi
+}
+
+ymir_home_root() {  # <result-var> — the operator's home: env → recorded → default
+  local result_var=${1-} rec=""
+  [ -n "$result_var" ] || return 2
+  if [ -n "${YMIR_HOME:-}" ]; then
+    printf -v "$result_var" '%s' "$YMIR_HOME"; return 0
+  fi
+  ymir_home_record rec
+  printf -v "$result_var" '%s' "${rec:-$YMIR_HOME_DEFAULT}"
+}
+
+ymir_home_record_set() {  # <path> — record the operator's choice (machine state)
+  local home=${1-}
+  [ -n "$home" ] || return 2
+  mkdir -p "$YMIR_CONFIG_DIR" 2>/dev/null || return 1
+  printf '%s\n' "$home" >"$YMIR_CONFIG_DIR/home" || return 1
+}
+
+hoard_root() {  # <result-var> — the hoard inside the home (may not exist yet)
+  local result_var=${1-} home
+  [ -n "$result_var" ] || return 2
+  if [ -n "${YMIR_HOARD:-}" ]; then
+    printf -v "$result_var" '%s' "$YMIR_HOARD"; return 0
+  fi
+  ymir_home_root home
+  printf -v "$result_var" '%s' "$home/hodd"
+}
+
+hoard_env() {  # <result-var> — the platform env file inside the hoard
+  local result_var=${1-} root
+  [ -n "$result_var" ] || return 2
+  hoard_root root
+  printf -v "$result_var" '%s' "$root/secrets/platform.env"
+}
+
+# This machine's own records (operator, fleet, the host profile) and the runtime
+# state (pids, logs, locks). Both live in the HOME — never in the code tree: a
+# packaged install treats its tree as read-only and the next upgrade replaces it,
+# so state written there is state lost. One documented default each; an env
+# override wins, so a single machine can point a root elsewhere without a fork.
+hoard_data_dir() {  # <result-var> — where this machine's records live
+  local result_var=${1-} root
+  [ -n "$result_var" ] || return 2
+  hoard_root root
+  printf -v "$result_var" '%s' "${YMIR_DATA_DIR:-$root/data}"
+}
+
+hoard_state_dir() {  # <result-var> — runtime state: ephemeral, outside the tree
+  local result_var=${1-} home
+  [ -n "$result_var" ] || return 2
+  ymir_home_root home
+  printf -v "$result_var" '%s' "${YMIR_STATE_DIR:-$home/state}"
+}
+
+# The operator's SETTINGS — the agent set, cron, the local env file with its
+# credentials. Settings are the operator's, not the package's: a packaged tree is
+# replaced on upgrade, and a credential must never sit in a tree that ships.
+hoard_settings_dir() {  # <result-var> — the settings dir inside the home
+  local result_var=${1-} home
+  [ -n "$result_var" ] || return 2
+  ymir_home_root home
+  printf -v "$result_var" '%s' "${YMIR_SETTINGS_DIR:-$home/config}"
+}
+
+hoard_local_env() {  # <result-var> — the operator's env file (secrets, ports)
+  local result_var=${1-} home
+  [ -n "$result_var" ] || return 2
+  ymir_home_root home
+  printf -v "$result_var" '%s' "${YMIR_ENV_FILE:-$home/.env.local}"
+}