@delorenj/pjangler 1.1.3

package/templates/hermes-agent/runtime-scaffold/memories/MEMORY.md

@@ -0,0 +1,47 @@
+# MEMORY.md — {{agent_id}}
+
+This file is loaded by the gateway at the start of every session. Keep it
+short and high-signal — anything that should ALWAYS be in context.
+
+## Identity
+
+You are **{{display_name}}**, the `{{role}}` agent for the `{{repo}}` repo.
+Your scope is the repo at the project root. You communicate via Telegram
+(`@{{repo}}_{{role}}_bot`) and Bloodbank events on the
+`bloodbank.evt.v1.repo.{{repo}}.*` lane.
+
+## Operator
+
+Jarad DeLorenzo. One-man dev team. Pivots hard and fast — when documentation
+disagrees with reality, trust reality (the codebase, `git log`, `llr`/`find`
+sorted by mtime). Prefers direct, decision-forward communication. Never
+re-explains what the diff already shows. Hates "I'll help you with that"
+preambles.
+
+## DeloNet conventions you respect at all times
+
+- LAN: `192.168.1.0/24`. Host machine `big-chungus` = `192.168.1.12`.
+  Tailscale IP `100.66.29.76`. **Never hardcode `10.0.0.x`** — that's stale
+  Xfinity-era data.
+- External access: `*.delo.sh` via Cloudflare Tunnel
+  (`6dfd95af-6e2a-4833-84b8-e0a1fda5da4a`). Container-to-container uses
+  Docker service names.
+- Secrets: `op://DeLoSecrets/<item>/<field>`, `~/.config/zshyzsh/secrets.zsh`
+  (exported), or project-local `.env`. Default creds:
+  `$DEFAULT_USERNAME` / `$DEFAULT_PASSWORD`.
+- Hindsight memory: durable cross-session facts go in
+  `hindsight memory retain {{repo}} "..." --context <category>`. This file
+  is the runtime/session-start summary; Hindsight is the long-term store.
+
+## Bloodbank events you emit
+
+Always emit envelope-shaped events with `actor.agent_id = {{agent_id}}` and
+`producer = hermes-agent:{{agent_id}}` for every consequential action.
+Event type format: `bloodbank.v1.<domain>.<entity>.<action>` (5 tokens,
+lowercase, past-tense action for events). Naming spec lives at
+`~/code/33GOD/bloodbank/docs/event-naming.md`.
+
+## Recent context
+
+(This section gets updated by the agent itself as work progresses.
+Treat the bottom-most entry as the most relevant.)

package/templates/hermes-agent/runtime-scaffold/memories/USER.md

@@ -0,0 +1,51 @@
+# USER.md — Jarad DeLorenzo
+
+The operator behind this agent. Loaded into context at session start so the
+agent doesn't have to re-discover who it's working with.
+
+## Identity
+
+- Name: Jarad DeLorenzo
+- Email: jaradd@gmail.com (personal), jarad@automaticai.io (business)
+- GitHub: `delorenj`
+- Telegram: see `TELEGRAM_ALLOWED_USERS` in this agent's `.env`
+- Role: One-man dev team running the 33GOD ecosystem and delonet homelab
+
+## How Jarad works
+
+- Pivots fast — instructions and architecture choices can flip between
+  sessions. Trust *current* code and `git log` over older documentation.
+- Prefers terse responses, decision-forward. No throat-clearing. No
+  "I'll help you with that". When unsure, asks one specific question, not
+  three vague ones.
+- Wants agents to act, then report. Not act, then ask if it was OK.
+- Uses Hindsight for durable memory. Expects agents to retain useful learnings
+  themselves rather than waiting to be asked.
+- Tracks confidence with `llr` (= `fdfind --type f --hidden --exclude .git -X
+  ls -lt --time=ctime -r`). Newer mtime = more authoritative.
+
+## Tooling he ships with
+
+- Copier (`gh:delorenj/CommonProject`) for new project bootstrap
+- BMAD method (`_bmad/`, `_bmad_output/`) for spec-driven work
+- Plane (`plane.delo.sh`) for ticket tracking — workspaces: 33god,
+  lasertoast, intelliforia
+- Bloodbank for cross-agent event flow
+- Hindsight for shared memory (banks: per-repo, `infra`, `33GOD`)
+- 1Password CLI (`op`) for all secrets
+- mise for env management
+
+## What he hates
+
+- Stale documentation that contradicts current state
+- Manual setup steps that should be scripted
+- Backwards-compatibility shims for code that just shipped
+- Long preambles before the actual answer
+- Hardcoded paths/IPs that break on the next machine
+
+## What he loves
+
+- Single source of truth (Holyfields-style schema registries)
+- Reproducible bootstrap (Copier + provision scripts)
+- Auto-checkpointed state (this very runtime repo!)
+- Agents that emit Bloodbank events so the rest of the system can react

package/templates/hermes-agent/scripts/backfill-fleet-sot.sh

@@ -0,0 +1,279 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Distributable config — same source of truth the template's _lib.sh reads.
+HERMES_TEMPLATE_CONFIG="${HERMES_TEMPLATE_CONFIG:-${XDG_CONFIG_HOME:-$HOME/.config}/hermes-agent-template/config.toml}"
+cfg() {  # cfg <dotted.key> <default>  — read a value from config.toml (always exits 0)
+  local key="$1" def="$2"
+  { [[ -f "$HERMES_TEMPLATE_CONFIG" ]] && command -v python3 >/dev/null 2>&1; } || { printf '%s' "$def"; return 0; }
+  python3 - "$HERMES_TEMPLATE_CONFIG" "$key" "$def" <<'PYEOF' || printf '%s' "$def"
+import sys, os
+try:
+    import tomllib
+except ModuleNotFoundError:
+    print(sys.argv[3], end=""); sys.exit(0)
+try:
+    cur = tomllib.load(open(sys.argv[1], "rb"))
+except Exception:
+    print(sys.argv[3], end=""); sys.exit(0)
+for p in sys.argv[2].split("."):
+    if isinstance(cur, dict) and p in cur:
+        cur = cur[p]
+    else:
+        print(sys.argv[3], end=""); sys.exit(0)
+print(os.path.expanduser(str(cur)), end="")
+PYEOF
+  return 0
+}
+
+FLEET_ENV="${HERMES_FLEET_ENV:-$(cfg fleet.fleet_env "$HOME/.hermes/fleet.env")}"
+REGISTRY_FILE="${HERMES_FLEET_REGISTRY_FILE:-$(cfg fleet.registry_file "$HOME/.hermes/agents-registry.yaml")}"
+DEFAULT_BIN="${HERMES_FLEET_BIN:-$(cfg fleet.hermes_bin /home/delorenj/code/hermes-agent/.venv/bin/hermes)}"
+DEFAULT_REPO="${HERMES_FLEET_REPO:-$(cfg fleet.hermes_repo /home/delorenj/code/hermes-agent)}"
+DEFAULT_OAUTH_FILE="${HERMES_FLEET_OAUTH_FILE:-$(cfg fleet.oauth_file "$HOME/.hermes/auth.json")}"
+DEFAULT_CODEX_HOME="${HERMES_FLEET_CODEX_HOME:-$(cfg fleet.codex_home "$HOME/.codex")}"
+SCAFFOLD_SRC="$(cd "$(dirname "$0")/../template/.runtime-scaffold" && pwd)"
+
+mkdir -p "$(dirname "$FLEET_ENV")"
+if [[ ! -f "$FLEET_ENV" ]]; then
+  cat > "$FLEET_ENV" <<EOF
+# Hermes fleet source of truth.
+HERMES_FLEET_BIN=${DEFAULT_BIN}
+HERMES_FLEET_REPO=${DEFAULT_REPO}
+HERMES_FLEET_REGISTRY_FILE=${REGISTRY_FILE}
+HERMES_FLEET_OAUTH_FILE=${DEFAULT_OAUTH_FILE}
+HERMES_FLEET_CODEX_HOME=${DEFAULT_CODEX_HOME}
+EOF
+  chmod 600 "$FLEET_ENV"
+fi
+
+upsert_fleet_env() {
+  local key="$1" value="$2"
+  python3 - "$FLEET_ENV" "$key" "$value" <<'PYEOF'
+import pathlib
+import sys
+
+path = pathlib.Path(sys.argv[1])
+key = sys.argv[2]
+value = sys.argv[3]
+line = f"{key}={value}"
+lines = path.read_text().splitlines() if path.exists() else []
+for idx, existing in enumerate(lines):
+    if existing.startswith(f"{key}="):
+        lines[idx] = line
+        break
+else:
+    lines.append(line)
+path.write_text("\n".join(lines) + "\n")
+PYEOF
+}
+
+upsert_fleet_env HERMES_FLEET_OAUTH_FILE "$DEFAULT_OAUTH_FILE"
+upsert_fleet_env HERMES_FLEET_CODEX_HOME "$DEFAULT_CODEX_HOME"
+chmod 600 "$FLEET_ENV"
+
+# shellcheck disable=SC1090
+source "$FLEET_ENV"
+
+HERMES_FLEET_BIN="${HERMES_FLEET_BIN:-$DEFAULT_BIN}"
+HERMES_FLEET_REPO="${HERMES_FLEET_REPO:-$DEFAULT_REPO}"
+HERMES_FLEET_OAUTH_FILE="${HERMES_FLEET_OAUTH_FILE:-$DEFAULT_OAUTH_FILE}"
+HERMES_FLEET_CODEX_HOME="${HERMES_FLEET_CODEX_HOME:-$DEFAULT_CODEX_HOME}"
+
+python3 - "$REGISTRY_FILE" "$HERMES_FLEET_BIN" "$HERMES_FLEET_REPO" "$FLEET_ENV" "$SCAFFOLD_SRC" "$HERMES_FLEET_OAUTH_FILE" "$HERMES_FLEET_CODEX_HOME" <<'PYEOF'
+import os
+import stat
+import sys
+import shutil
+import pathlib
+
+try:
+    import yaml  # type: ignore
+except ImportError:
+    raise SystemExit("PyYAML required (pip install pyyaml)")
+
+registry_path = pathlib.Path(sys.argv[1])
+hermes_bin = sys.argv[2]
+hermes_repo = sys.argv[3]
+fleet_env = sys.argv[4]
+scaffold_src = pathlib.Path(sys.argv[5])
+oauth_file = sys.argv[6]
+codex_home = sys.argv[7]
+
+if not registry_path.exists():
+    raise SystemExit(f"Registry not found: {registry_path}")
+
+data = yaml.safe_load(registry_path.read_text()) or {}
+agents = data.get("agents") or {}
+
+wrapper_count = 0
+meta_count = 0
+scaffold_count = 0
+lib_count = 0
+systemd_count = 0
+
+
+def patch_systemd_unit(unit_path: pathlib.Path) -> bool:
+    if not unit_path.exists():
+        return False
+    original = unit_path.read_text()
+    lines = original.splitlines()
+    rendered = []
+    for line in lines:
+        if line.startswith("Environment=HERMES_OAUTH_FILE="):
+            continue
+        if line.startswith("Environment=CODEX_HOME="):
+            continue
+        rendered.append(line)
+        if line.startswith("Environment=HERMES_HOME="):
+            rendered.append(f"Environment=HERMES_OAUTH_FILE={oauth_file}")
+            rendered.append(f"Environment=CODEX_HOME={codex_home}")
+    new_text = "\n".join(rendered) + ("\n" if original.endswith("\n") else "")
+    if new_text == original:
+        return False
+    unit_path.write_text(new_text)
+    return True
+
+for agent_id, cfg in agents.items():
+    cfg["hermes"] = {
+        "bin": hermes_bin,
+        "repo": hermes_repo,
+        "fleet_env": fleet_env,
+        "oauth_file": oauth_file,
+        "codex_home": codex_home,
+    }
+    meta_count += 1
+
+    systemd_dir = pathlib.Path.home() / ".config" / "systemd" / "user"
+    for suffix in ("gateway", "consumer"):
+        unit = systemd_dir / f"hermes-{agent_id}-{suffix}.service"
+        if patch_systemd_unit(unit):
+            systemd_count += 1
+
+    role_dir = cfg.get("role_dir")
+    if not role_dir:
+        continue
+
+    role_path = pathlib.Path(role_dir)
+    if not role_path.exists():
+        continue
+
+    project_path = pathlib.Path(cfg.get("project_path") or "")
+    role_name = cfg.get("role") or "pm"
+    profile_name = cfg.get("profile_name") or agent_id
+    alt_role_path = project_path / "_agents" / "hermes" / role_name
+    if not (role_path / "hermes").exists() and (alt_role_path / "hermes").exists():
+        role_path = alt_role_path
+        cfg["role_dir"] = str(alt_role_path)
+
+    target_scaffold = role_path / ".runtime-scaffold"
+    shutil.copytree(scaffold_src, target_scaffold, dirs_exist_ok=True)
+    scaffold_count += 1
+
+    lib_path = role_path / ".scripts" / "_lib.sh"
+    if lib_path.exists():
+        lib_text = lib_path.read_text()
+        old_block = (
+            "# Tools we expect on the host\n"
+            "HERMES_BIN=\"${HERMES_BIN:-/home/delorenj/code/hermes-agent/.venv/bin/hermes}\"\n"
+            "HERMES_AGENT_REPO=\"${HERMES_AGENT_REPO:-/home/delorenj/code/hermes-agent}\"\n"
+            "RUNTIME_SCAFFOLD_DIR=\"${RUNTIME_SCAFFOLD_DIR:-/home/delorenj/code/hermes-agent-template/runtime-scaffold}\"\n"
+            "REGISTRY_FILE=\"${REGISTRY_FILE:-$HOME/.hermes/agents-registry.yaml}\"\n"
+        )
+        new_block = (
+            "# Fleet source-of-truth (shared across all wrappers/provisioners)\n"
+            "FLEET_ENV=\"${HERMES_FLEET_ENV:-$HOME/.hermes/fleet.env}\"\n"
+            "if [[ -f \"$FLEET_ENV\" ]]; then\n"
+            "  # shellcheck disable=SC1090\n"
+            "  source \"$FLEET_ENV\"\n"
+            "fi\n\n"
+            "# Tools we expect on the host\n"
+            "HERMES_BIN=\"${HERMES_BIN:-${HERMES_FLEET_BIN:-/home/delorenj/code/hermes-agent/.venv/bin/hermes}}\"\n"
+            "HERMES_AGENT_REPO=\"${HERMES_AGENT_REPO:-${HERMES_FLEET_REPO:-/home/delorenj/code/hermes-agent}}\"\n"
+            "HERMES_OAUTH_FILE=\"${HERMES_OAUTH_FILE:-${HERMES_FLEET_OAUTH_FILE:-$HOME/.hermes/auth.json}}\"\n"
+            "CODEX_HOME=\"${CODEX_HOME:-${HERMES_FLEET_CODEX_HOME:-$HOME/.codex}}\"\n"
+            "# Prefer a scaffold vendored into this agent directory; fall back to legacy template path.\n"
+            "RUNTIME_SCAFFOLD_DIR=\"${RUNTIME_SCAFFOLD_DIR:-$ROLE_DIR/.runtime-scaffold}\"\n"
+            "if [[ ! -d \"$RUNTIME_SCAFFOLD_DIR\" ]]; then\n"
+            "  RUNTIME_SCAFFOLD_DIR=\"${HERMES_TEMPLATE_RUNTIME_SCAFFOLD:-/home/delorenj/code/hermes-agent-template/runtime-scaffold}\"\n"
+            "fi\n"
+            "REGISTRY_FILE=\"${REGISTRY_FILE:-${HERMES_FLEET_REGISTRY_FILE:-$HOME/.hermes/agents-registry.yaml}}\"\n"
+        )
+        if old_block in lib_text:
+            lib_text = lib_text.replace(old_block, new_block)
+        if "HERMES_OAUTH_FILE=" not in lib_text:
+            lib_text = lib_text.replace(
+                "HERMES_AGENT_REPO=\"${HERMES_AGENT_REPO:-${HERMES_FLEET_REPO:-/home/delorenj/code/hermes-agent}}\"\n",
+                "HERMES_AGENT_REPO=\"${HERMES_AGENT_REPO:-${HERMES_FLEET_REPO:-/home/delorenj/code/hermes-agent}}\"\n"
+                "HERMES_OAUTH_FILE=\"${HERMES_OAUTH_FILE:-${HERMES_FLEET_OAUTH_FILE:-$HOME/.hermes/auth.json}}\"\n"
+                "CODEX_HOME=\"${CODEX_HOME:-${HERMES_FLEET_CODEX_HOME:-$HOME/.codex}}\"\n",
+            )
+        lib_text = lib_text.replace(
+            "export HERMES_BIN HERMES_AGENT_REPO RUNTIME_SCAFFOLD_DIR REGISTRY_FILE \\\n       BLOODBANK_NATS_HOST BLOODBANK_NATS_PORT \\\n       PLANE_BASE PLANE_API_KEY \\\n       CF_API CF_ZONE_DELO_SH CF_ACCOUNT_ID\n",
+            "export FLEET_ENV HERMES_BIN HERMES_AGENT_REPO RUNTIME_SCAFFOLD_DIR REGISTRY_FILE \\\n       BLOODBANK_NATS_HOST BLOODBANK_NATS_PORT \\\n       PLANE_BASE PLANE_API_KEY \\\n       CF_API CF_ZONE_DELO_SH CF_ACCOUNT_ID\n",
+        )
+        lib_text = lib_text.replace(
+            "export FLEET_ENV HERMES_BIN HERMES_AGENT_REPO RUNTIME_SCAFFOLD_DIR REGISTRY_FILE",
+            "export FLEET_ENV HERMES_BIN HERMES_AGENT_REPO HERMES_OAUTH_FILE CODEX_HOME RUNTIME_SCAFFOLD_DIR REGISTRY_FILE",
+        )
+        if lib_text != lib_path.read_text():
+            lib_path.write_text(lib_text)
+            lib_count += 1
+
+    wrapper = role_path / "hermes"
+    if not wrapper.exists():
+        continue
+
+    wrapper.write_text(
+        "#!/usr/bin/env bash\n"
+        f"# Launcher for {agent_id}. Resolves HERMES_HOME through the fleet profile when available.\n"
+        "set -euo pipefail\n\n"
+        "ROLE_DIR=\"$(cd \"$(dirname \"$0\")\" && pwd)\"\n"
+        "RUNTIME_HOME=\"$ROLE_DIR/runtime\"\n\n"
+        "FLEET_ENV=\"${HERMES_FLEET_ENV:-$HOME/.hermes/fleet.env}\"\n"
+        "if [[ -f \"$FLEET_ENV\" ]]; then\n"
+        "  # shellcheck disable=SC1090\n"
+        "  source \"$FLEET_ENV\"\n"
+        "fi\n\n"
+        "HERMES_BIN=\"${HERMES_BIN:-${HERMES_FLEET_BIN:-/home/delorenj/code/hermes-agent/.venv/bin/hermes}}\"\n\n"
+        "HERMES_OAUTH_FILE=\"${HERMES_OAUTH_FILE:-${HERMES_FLEET_OAUTH_FILE:-$HOME/.hermes/auth.json}}\"\n"
+        "CODEX_HOME=\"${CODEX_HOME:-${HERMES_FLEET_CODEX_HOME:-$HOME/.codex}}\"\n\n"
+        "FLEET_HOME=\"${HERMES_FLEET_HOME:-$HOME/.hermes}\"\n"
+        f"PROFILE_NAME=\"${{HERMES_PROFILE_NAME:-{profile_name}}}\"\n"
+        "PROFILE_HOME=\"$FLEET_HOME/profiles/$PROFILE_NAME\"\n"
+        "if [[ -d \"$PROFILE_HOME\" ]]; then\n"
+        "  HERMES_HOME=\"$PROFILE_HOME\"\n"
+        "else\n"
+        "  HERMES_HOME=\"$RUNTIME_HOME\"\n"
+        "fi\n\n"
+        "if [[ ! -d \"$RUNTIME_HOME\" ]]; then\n"
+        "  echo \"hermes: runtime submodule not initialized at $RUNTIME_HOME\" >&2\n"
+        "  echo \"  fix: git submodule update --init --recursive\" >&2\n"
+        "  exit 1\n"
+        "fi\n\n"
+        "if [[ ! -x \"$HERMES_BIN\" ]]; then\n"
+        "  echo \"hermes: binary not executable at $HERMES_BIN\" >&2\n"
+        "  echo \"  set HERMES_BIN or HERMES_FLEET_BIN (in $FLEET_ENV) to the shared Hermes binary.\" >&2\n"
+        "  exit 1\n"
+        "fi\n\n"
+        "exec env HERMES_HOME=\"$HERMES_HOME\" HERMES_FLEET_ENV=\"$FLEET_ENV\" "
+        "HERMES_OAUTH_FILE=\"$HERMES_OAUTH_FILE\" CODEX_HOME=\"$CODEX_HOME\" \"$HERMES_BIN\" \"$@\"\n"
+    )
+
+    mode = wrapper.stat().st_mode
+    wrapper.chmod(mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+    wrapper_count += 1
+
+registry_path.write_text(yaml.safe_dump(data, sort_keys=False))
+print(f"updated wrappers: {wrapper_count}")
+print(f"updated registry entries: {meta_count}")
+print(f"copied role-local scaffolds: {scaffold_count}")
+print(f"patched role _lib.sh files: {lib_count}")
+print(f"patched systemd units: {systemd_count}")
+print(f"registry: {registry_path}")
+print(f"fleet env: {fleet_env}")
+print(f"shared bin: {hermes_bin}")
+print(f"shared repo: {hermes_repo}")
+print(f"shared oauth file: {oauth_file}")
+print(f"shared codex home: {codex_home}")
+PYEOF

package/templates/hermes-agent/scripts/repair-runtime-checkpoint.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+# Repair a failing runtime-checkpoint service caused by an UNPOPULATED runtime
+# submodule (`git add -A` -> "fatal: in unpopulated submodule" -> exit 128).
+#
+# Dry-run by default (diagnose + print plan). Pass --apply to mutate. The mutate
+# path only ever runs `git init` / `fetch` / `reset --mixed` / `.gitignore` edits
+# / `rm --cached` — it NEVER rewrites working-tree files, so live runtime state
+# (incl. a large state.db) is preserved. It does NOT commit or push; run the
+# role's checkpoint.sh afterward.
+#
+# Docs: docs/runbooks/runtime-checkpoint-repair.md
+# Usage: repair-runtime-checkpoint.sh [--apply] <runtime-dir>
+set -euo pipefail
+
+APPLY=0; RT=""
+for a in "$@"; do
+  case "$a" in
+    --apply) APPLY=1 ;;
+    -h|--help) sed -n '2,12p' "$0"; exit 0 ;;
+    *) RT="$a" ;;
+  esac
+done
+
+die(){ printf 'ERROR: %s\n' "$*" >&2; exit 1; }
+note(){ printf '  %s\n' "$*"; }
+
+[ -n "$RT" ] || die "usage: $0 [--apply] <runtime-dir>  (e.g. agents/hermes/pm/runtime)"
+[ -d "$RT" ] || die "no such directory: $RT"
+
+PARENT="$(git -C "$RT" rev-parse --show-superproject-working-tree 2>/dev/null || true)"
+[ -n "$PARENT" ] || PARENT="$(git -C "$RT" rev-parse --show-toplevel 2>/dev/null || true)"
+[ -n "$PARENT" ] || die "$RT is not inside a git repository"
+RTABS="$(cd "$RT" && pwd)"
+RELPATH="${RTABS#"$PARENT"/}"
+
+MODE="dry-run"; [ "$APPLY" -eq 1 ] && MODE="APPLY"
+printf '== runtime-checkpoint repair (%s) ==\n' "$MODE"
+note "runtime: $RTABS"
+note "parent:  $PARENT"
+note "subpath: $RELPATH"
+
+if git -C "$RTABS" rev-parse --git-dir >/dev/null 2>&1 && [ -e "$RTABS/.git" ]; then
+  POPULATED=1; note "state:   runtime already has its own .git (re-attach not needed)"
+else
+  POPULATED=0; note "state:   UNPOPULATED submodule (no .git) — re-attach required"
+fi
+
+URL="$(git -C "$PARENT" config -f "$PARENT/.gitmodules" --get "submodule.$RELPATH.url" 2>/dev/null || true)"
+[ -n "$URL" ] || die "no .gitmodules url for submodule '$RELPATH'"
+note "remote:  $URL"
+GIT_SSH_COMMAND='ssh -o BatchMode=yes -o ConnectTimeout=15' git ls-remote "$URL" >/dev/null 2>&1 \
+  || die "remote not reachable (check SSH/network): $URL"
+note "remote reachable: yes"
+
+IGNORE_MARK='NOT part of the durable brain backup'
+IGNORE_BLOCK='# Runtime working state — NOT part of the durable brain backup.
+*.db
+*.db-wal
+*.db-shm
+*.sqlite
+*.sqlite3
+*.lock
+.update_check
+lsp/
+checkpoints/
+sessions/
+cron/
+*_cache.json'
+
+if [ "$APPLY" -eq 0 ]; then
+  cat <<EOF
+
+PLAN (dry-run; re-run with --apply):
+  cd $RELPATH
+  $( [ "$POPULATED" -eq 0 ] && echo "git init -q; git symbolic-ref HEAD refs/heads/main; git remote add origin <url>; git fetch origin; git reset --mixed origin/main" || echo "(already populated — skip re-init)" )
+  git lfs install --local
+  git checkout origin/main -- .gitattributes README.md   # restore tracked config
+  ensure runtime/.gitignore has the volatile-state block
+  git rm -r --cached --ignore-unmatch state.db state.db-wal state.db-shm cron
+  # safety gate: git add -A --dry-run must show no >1MB blobs / secrets / volatile paths
+  then: run the role's checkpoint.sh and (re)start the systemd checkpoint unit.
+EOF
+  exit 0
+fi
+
+cd "$RTABS"
+if [ "$POPULATED" -eq 0 ]; then
+  git init -q
+  git symbolic-ref HEAD refs/heads/main
+  git remote add origin "$URL" 2>/dev/null || git remote set-url origin "$URL"
+  GIT_SSH_COMMAND='ssh -o BatchMode=yes -o ConnectTimeout=20' git fetch -q origin
+  git reset --mixed -q origin/main
+  git branch --set-upstream-to=origin/main main >/dev/null 2>&1 || true
+  note "re-attached HEAD -> $(git rev-parse --short HEAD) on $(git rev-parse --abbrev-ref HEAD)"
+fi
+git lfs install --local >/dev/null 2>&1 || true
+git checkout origin/main -- .gitattributes README.md 2>/dev/null || true
+
+touch .gitignore
+if grep -q "$IGNORE_MARK" .gitignore 2>/dev/null; then
+  note ".gitignore already has the volatile-state block"
+else
+  printf '\n%s\n' "$IGNORE_BLOCK" >> .gitignore
+  note "appended volatile-state ignore block to .gitignore"
+fi
+git rm -r --cached --quiet --ignore-unmatch state.db state.db-wal state.db-shm cron 2>/dev/null || true
+
+# ---- mandatory safety gate ----
+staged(){ git add -A --dry-run 2>/dev/null | sed -E "s/^[a-z]+ '?//; s/'?$//"; }
+BIG="$(staged | while read -r f; do [ -f "$f" ] && s=$(stat -c%s "$f" 2>/dev/null) && [ "${s:-0}" -gt 1048576 ] && printf '%s (%sMB)\n' "$f" "$((s/1048576))"; done)"
+SECRETS="$(staged | grep -iE '(^|/)(\.env|\.env\.|auth\.json|auth\.lock)([./]|$)|\.(pem|key)$' || true)"
+VOL="$(staged | grep -E '(^|/)(state\.db|lsp|sessions|checkpoints)(/|$)' || true)"
+if [ -n "$BIG$SECRETS$VOL" ]; then
+  printf 'SAFETY GATE FAILED — fix .gitignore before committing.\n' >&2
+  [ -n "$BIG" ]     && printf '  >1MB blobs:\n%s\n' "$BIG" >&2
+  [ -n "$SECRETS" ] && printf '  secrets:\n%s\n' "$SECRETS" >&2
+  [ -n "$VOL" ]     && printf '  volatile state:\n%s\n' "$VOL" >&2
+  exit 2
+fi
+note "safety gate passed: staged set is brain-only."
+note "DONE. Now run the role's checkpoint.sh, then:"
+note "  systemctl --user reset-failed <checkpoint-service> && systemctl --user start <checkpoint-service>"

package/templates/hermes-agent/scripts/retrofit-70-envfile.sh

@@ -0,0 +1,129 @@
+#!/usr/bin/env bash
+# Retrofit existing fleet systemd unit files to load runtime/.env.
+#
+# Companion to the fix in commit 3b7d2e5 (template/.scripts/70-systemd.sh).
+# Future agents pick the fix up automatically via pjangler; existing agents
+# already have unit files installed at ~/.config/systemd/user/ that won't
+# change until we rewrite them in place.
+#
+# What this does:
+#   - Finds every hermes-<agent>-{gateway,consumer}.service unit
+#   - Inserts `EnvironmentFile=-<runtime>/.env` after `Environment=HERMES_HOME=...`
+#     if not already present
+#   - daemon-reloads once
+#   - restarts each unit it modified (skippable with --no-restart)
+#
+# Idempotent: re-running is a no-op if the directive is already present.
+# Dry-run by default; pass --apply to actually write/restart.
+#
+# Usage:
+#   scripts/retrofit-70-envfile.sh             # dry-run: show what would change
+#   scripts/retrofit-70-envfile.sh --apply     # write + daemon-reload + restart
+#   scripts/retrofit-70-envfile.sh --apply --no-restart
+#
+set -euo pipefail
+
+APPLY=0
+RESTART=1
+for arg in "$@"; do
+  case "$arg" in
+    --apply)      APPLY=1 ;;
+    --no-restart) RESTART=0 ;;
+    -h|--help)
+      sed -n '2,/^set -euo/p' "$0" | sed 's/^# \{0,1\}//;/^set -euo/d'
+      exit 0
+      ;;
+    *) echo "unknown arg: $arg" >&2; exit 2 ;;
+  esac
+done
+
+SYS_DIR="$HOME/.config/systemd/user"
+DIRECTIVE_PREFIX="EnvironmentFile=-"
+
+shopt -s nullglob
+UNITS=( "$SYS_DIR"/hermes-*-gateway.service "$SYS_DIR"/hermes-*-consumer.service )
+shopt -u nullglob
+
+if [[ ${#UNITS[@]} -eq 0 ]]; then
+  echo "no hermes-*-{gateway,consumer}.service units found under $SYS_DIR"
+  exit 0
+fi
+
+mode="DRY-RUN"; [[ "$APPLY" == "1" ]] && mode="APPLY"
+echo "[$mode] scanning ${#UNITS[@]} unit(s) under $SYS_DIR"
+
+MODIFIED=()
+SKIPPED_OK=()
+SKIPPED_BAD=()
+
+for unit in "${UNITS[@]}"; do
+  base="$(basename "$unit")"
+
+  # Parse the runtime path from the Environment=HERMES_HOME= line.
+  runtime="$(grep -E '^Environment=HERMES_HOME=' "$unit" | head -1 | cut -d= -f3-)"
+  if [[ -z "$runtime" ]]; then
+    echo "  SKIP  $base — no Environment=HERMES_HOME= line; not a template-generated unit"
+    SKIPPED_BAD+=( "$base" )
+    continue
+  fi
+
+  expected="${DIRECTIVE_PREFIX}${runtime}/.env"
+
+  if grep -qxF "$expected" "$unit"; then
+    echo "  OK    $base — already has $expected"
+    SKIPPED_OK+=( "$base" )
+    continue
+  fi
+
+  echo "  PATCH $base"
+  echo "          + $expected"
+
+  if [[ "$APPLY" == "1" ]]; then
+    # Insert the directive on the line AFTER the Environment=HERMES_HOME= line.
+    # Use a tmp file + atomic replace to avoid half-written units.
+    tmp="$(mktemp "$unit.XXXXXX")"
+    awk -v ins="$expected" '
+      { print }
+      /^Environment=HERMES_HOME=/ && !done { print ins; done=1 }
+    ' "$unit" > "$tmp"
+    chmod --reference="$unit" "$tmp"
+    mv "$tmp" "$unit"
+  fi
+  MODIFIED+=( "$base" )
+done
+
+echo
+echo "summary:"
+echo "  ${#MODIFIED[@]} patched, ${#SKIPPED_OK[@]} already correct, ${#SKIPPED_BAD[@]} skipped (non-template)"
+
+if [[ "$APPLY" != "1" ]]; then
+  echo
+  echo "dry-run only. re-run with --apply to write the changes."
+  exit 0
+fi
+
+if [[ ${#MODIFIED[@]} -eq 0 ]]; then
+  echo "nothing to reload."
+  exit 0
+fi
+
+echo
+echo "systemctl --user daemon-reload"
+systemctl --user daemon-reload
+
+if [[ "$RESTART" != "1" ]]; then
+  echo "skipping restarts (--no-restart). reload only."
+  exit 0
+fi
+
+echo
+echo "restarting ${#MODIFIED[@]} modified unit(s)..."
+for unit in "${MODIFIED[@]}"; do
+  echo "  systemctl --user restart $unit"
+  if ! systemctl --user restart "$unit"; then
+    echo "    WARN: restart failed for $unit (status below)" >&2
+    systemctl --user --no-pager status "$unit" | head -10 >&2 || true
+  fi
+done
+
+echo "done."

package/templates/hermes-agent/template/.gitignore.jinja

@@ -0,0 +1,6 @@
+# Per-role ignores in agents/hermes/{{ role }}/
+
+# The runtime submodule manages its own ignores (.env, auth.json, etc.).
+# We just ignore the provisioning log so it doesn't end up in the project repo.
+.scripts/.provision.log
+.scripts/.last-run

package/templates/hermes-agent/template/.runtime-scaffold/.gitattributes

@@ -0,0 +1,10 @@
+# Route binary state through git-lfs so the checkpoint repo doesn't bloat.
+*.db          filter=lfs diff=lfs merge=lfs -text
+*.sqlite      filter=lfs diff=lfs merge=lfs -text
+*.sqlite3     filter=lfs diff=lfs merge=lfs -text
+*.png         filter=lfs diff=lfs merge=lfs -text
+*.jpg         filter=lfs diff=lfs merge=lfs -text
+*.jpeg        filter=lfs diff=lfs merge=lfs -text
+*.wav         filter=lfs diff=lfs merge=lfs -text
+*.mp3         filter=lfs diff=lfs merge=lfs -text
+*.mp4         filter=lfs diff=lfs merge=lfs -text