@zerwiz/ymir 0.1.5 → 0.1.7

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

@@ -1,20 +1,64 @@
 #!/usr/bin/env bash
-# hoard-lib.sh — where Hodd (the private hoard) lives. ONE documented default.
+# hoard-lib.sh — where the operator's HOME lives, and the two roots beneath it.
 #
-# The hoard is NEVER inside the checkout (RULES/04-hoard.md): the repo's `hodd/`
-# holds only the guard, the README and `*.example` scaffolds. Private data —
-# docs, secrets, identity, tenants — lives at $YMIR_HOARD, else $YMIR_HOME, else
-# $HOME/Documents/Ymir. Scripts resolve it HERE so the default can never drift
-# between them (Rule 07: configuration is never hardcoded; one documented
-# default).
+# 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).
 #
-# Source-safe; call hoard_root <result-var>.
+#   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
 
-hoard_root() {  # <result-var> — the hoard root (may not exist yet)
-  local result_var=${1-}
+# 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
-  printf -v "$result_var" '%s' "${YMIR_HOARD:-${YMIR_HOME:-$HOME/Documents/Ymir}/hodd}"
+  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
@@ -23,3 +67,39 @@ hoard_env() {  # <result-var> — the platform env file inside the hoard
   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}"
+}

package/bin/hodd.sh

@@ -42,6 +42,24 @@ PY
   printf 'hodd[1]{action,file}:\n  "load","%s"\n' "$f"
 }
 
+# Resolve a secrets path: if the plaintext is absent but an .age sibling and the
+# hoard key exist, decrypt to stdout. Prints a path to a readable file (a temp
+# when decrypted) via the result var. Secrets stay encrypted at rest; the agent
+# never reads ciphertext directly — it asks for the resolved path.
+resolve_secret() {  # <file> <result-var>
+  local f=$1 var=$2 tmp key
+  if [ -r "$f" ]; then printf -v "$var" '%s' "$f"; return 0; fi
+  if [ -r "$f.age" ]; then
+    key="$HOARD/secrets/age.key"
+    command -v age >/dev/null 2>&1 || { printf 'error: %s is encrypted but age is not installed\nhelp: sudo pacman -S age\n' "$f.age" >&2; return 1; }
+    [ -r "$key" ] || { printf 'error: encrypted %s but no key at %s\n' "$f.age" "$key" >&2; return 1; }
+    tmp="$(mktemp)"; chmod 600 "$tmp"
+    age -d -i "$key" "$f.age" >"$tmp" 2>/dev/null || { rm -f "$tmp"; printf 'error: cannot decrypt %s\n' "$f.age" >&2; return 1; }
+    printf -v "$var" '%s' "$tmp"; return 0
+  fi
+  printf 'error: not readable: %s (and no %s.age)\n' "$f" "$f" >&2; return 1
+}
+
 case "$ACTION" in
   path)  printf '%s\n' "$HOARD" ;;
   init)
@@ -56,23 +74,29 @@ case "$ACTION" in
   load)
     f="${1:-}"; [ -n "$f" ] || { printf 'error: load needs a path under the Hoard\n' >&2; exit 2; }
     case "$f" in /*) ;; *) f="$HOARD/$f" ;; esac
-    load_env "$f" ;;
+    resolve_secret "$f" rf || exit 1
+    load_env "$rf"
+    case "$rf" in "$f") ;; *) rm -f "$rf" ;; esac ;;
   emit)
     # Print `export KEY=value` lines (quoting-safe) for the CALLER to eval, so
     # `eval "$(bin/hodd.sh emit <file>)"` sets the vars in the invoking shell.
+    # Transparently decrypts an .age sibling when the plaintext is absent.
     f="${1:-}"; [ -n "$f" ] || { printf 'error: emit needs a path under the Hoard\n' >&2; exit 2; }
     case "$f" in /*) ;; *) f="$HOARD/$f" ;; esac
-    [ -r "$f" ] || { printf 'error: not readable: %s\n' "$f" >&2; exit 1; }
-    python3 - "$f" <<'PY'
+    resolve_secret "$f" rf || exit 1
+    python3 - "$rf" <<'PY'
 import re, shlex, sys
 for line in open(sys.argv[1]):
     m = re.match(r'^([A-Za-z_][A-Za-z0-9_]*)=(.*)$', line.rstrip("\n"))
     if m:
         print(f"export {m.group(1)}={shlex.quote(m.group(2))}")
 PY
+    case "$rf" in "$f") ;; *) rm -f "$rf" ;; esac
     ;;
   tenant)
     t="${1:-}"; [ -n "$t" ] || { printf 'error: tenant needs a name\n' >&2; exit 2; }
-    load_env "$HOARD/tenants/$t/.env" ;;
+    resolve_secret "$HOARD/tenants/$t/.env" rf || exit 1
+    load_env "$rf"
+    case "$rf" in "$HOARD/tenants/$t/.env") ;; *) rm -f "$rf" ;; esac ;;
   *) printf 'error: unknown action %s\nhelp: bin/hodd.sh [path|init|ls|load|emit|tenant]\n' "$ACTION" >&2; exit 2 ;;
 esac

package/bin/huginn-research-worker.sh

@@ -12,6 +12,19 @@ set -u
 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
+
 BRIEF="" OUTDIR="" MODEL=""
 while [ $# -gt 0 ]; do
   case "$1" in
@@ -28,7 +41,7 @@ done
 mkdir -p "$OUTDIR"
 
 # Resolve env — source .env.local if present.
-for f in "$ROOT/.env.local" "${YMIR_HOARD:-$HOME/Documents/Ymir}/.env.local"; do
+for f in "$YMIR_ENV_FILE" "${YMIR_HOARD:-$HOME/Documents/Ymir}/.env.local"; do
   [ -f "$f" ] && . "$f" 2>/dev/null || true
 done
 

package/bin/local-model-lock.sh

@@ -12,8 +12,27 @@ set -u
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
-CFG="${YMIR_AGENTS_YAML:-$ROOT/config/agents.yaml}"
-LOCK="$ROOT/state/local-model.lock"
+
+# 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
+hoard_state_dir YMIR_STATE_DIR
+hoard_data_dir YMIR_DATA_DIR
+
+# 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).
+CFG="${YMIR_AGENTS_YAML:-$YMIR_SETTINGS_DIR/agents.yaml}"
+LOCK="$YMIR_STATE_DIR/local-model.lock"
 WAIT="${LOCAL_MODEL_WAIT:-1800}"
 
 [ $# -gt 0 ] || { printf 'error: usage: bin/local-model-lock.sh <command...>\n' >&2; exit 2; }
@@ -31,7 +50,7 @@ PY
 )"
 [ -n "$N" ] || N=1
 
-mkdir -p "$ROOT/state"
+mkdir -p "$YMIR_STATE_DIR"
 
 if [ "$N" -le 1 ]; then
   # one at a time — exclusive lock, wait for the peer to finish

package/bin/mimir-bridge.py

@@ -49,6 +49,35 @@ def engine(agent: str | None) -> Engram:
         return _pool[key]
 
 
+def layers():
+    """What the well actually holds, layer by layer - the record a UI reads."""
+    out = {"facts": 0, "facts_active": 0, "facts_superseded": 0, "entities": 0,
+           "edges": 0, "reflections": 0, "last_reflection": None, "vec_index": 0}
+    try:
+        con = sqlite3.connect(f"file:{STORE}?mode=ro", uri=True)
+        for key, sql in (
+            ("facts", "select count(*) from facts"),
+            ("facts_active", "select count(*) from facts where superseded_at is null"),
+            ("facts_superseded", "select count(*) from facts where superseded_at is not null"),
+            ("entities", "select count(*) from entities"),
+            ("edges", "select count(*) from edges"),
+            ("reflections", "select count(*) from reflections"),
+            ("vec_index", "select count(*) from vec_episodes_rowids"),
+        ):
+            try:
+                out[key] = int(con.execute(sql).fetchone()[0])
+            except Exception:
+                pass
+        try:
+            out["last_reflection"] = con.execute(
+                "select max(finished_at) from reflections").fetchone()[0]
+        except Exception:
+            pass
+    except Exception as e:
+        out["error"] = str(e)
+    return out
+
+
 def count_episodes() -> int:
     try:
         con = sqlite3.connect(f"file:{STORE}?mode=ro", uri=True)
@@ -98,10 +127,14 @@ class Handler(BaseHTTPRequestHandler):
                     "agents": engine(None).list_agents(),
                 })
             if u.path == "/inspect":
+                # THE LAYERS, not just the count. The smithy shows what it is told,
+                # and it was told three fields while the well holds six: a panel that
+                # reads only episodes cannot show that facts and entities exist.
                 return self._json(200, {
                     "store": str(STORE),
                     "episodes": count_episodes(),
                     "agents": engine(None).list_agents(),
+                    **layers(),
                 })
             if u.path == "/recent":
                 limit = int((q.get("limit") or ["60"])[0])

package/bin/mimir-bridge.sh

@@ -18,6 +18,19 @@ fi
 VERSION="1.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
 YMIR_HOME="${YMIR_HOME:-$HOME/Documents/Ymir}"
 BRIDGE="$ROOT/bin/mimir-bridge.py"
 DB="${ENGRAM_DB:-$YMIR_HOME/memory/kaia.engram}"
@@ -75,7 +88,7 @@ if ! "$PY" -c "import engram" 2>/dev/null; then
   printf 'error: engram not installed for %s\nhelp: bin/prereq-ensure.sh engram   (installs it into a compatible Python)\n' "$PY" >&2; exit 1
 fi
 
-mkdir -p "$ROOT/state" "$(dirname "$DB")"
+mkdir -p "$YMIR_STATE_DIR" "$(dirname "$DB")"
 ENGRAM_DB="$DB" MIMIRSBRUNN_PORT="$PORT" nohup "$PY" "$BRIDGE" >"$LOG_FILE" 2>&1 &
 echo $! >"$PID_FILE"
 sleep 3