@delorenj/pjangler 1.1.3

package/templates/hermes-agent/template/.scripts/20-runtime-repo.sh

@@ -0,0 +1,144 @@
+#!/usr/bin/env bash
+# Create the per-agent runtime GitHub repo, init from scaffold, submodule it.
+# shellcheck source=_lib.sh
+source "$(dirname "$0")/_lib.sh"
+load_role_env
+
+already_done 20-runtime-repo && { log "[20] runtime repo already set up — skipping"; exit 0; }
+[[ "${SKIP_RUNTIME_REPO:-0}" == "1" ]] && { log "[20] runtime repo — SKIPPED (SKIP_RUNTIME_REPO=1)"; mark_done 20-runtime-repo; exit 0; }
+
+PROFILE_HOME="$(profile_home)"
+RUNTIME_LOCAL="$ROLE_DIR/runtime"
+GH_OWNER="${RUNTIME_REPO%%/*}"
+GH_NAME="${RUNTIME_REPO##*/}"
+
+log "[20] runtime repo: gh:$RUNTIME_REPO"
+
+# 1. Create the GitHub repo (private) if it doesn't exist
+if gh repo view "$RUNTIME_REPO" >/dev/null 2>&1; then
+  log "    GH repo exists; reusing"
+else
+  log "    creating GH repo (private)"
+  gh repo create "$RUNTIME_REPO" --private \
+    --description "Hermes runtime (HERMES_HOME) for $AGENT_ID — auto-checkpointed memory + state" \
+    --disable-issues --disable-wiki >/dev/null
+fi
+
+REMOTE_URL=$(gh repo view "$RUNTIME_REPO" --json sshUrl -q .sshUrl)
+
+# 2. Check if remote already has commits — if so, skip the scaffold push.
+#    This makes the step idempotent across failed-run retries.
+if git ls-remote --heads "$REMOTE_URL" 2>/dev/null | grep -q refs/heads; then
+  log "    remote already has commits — skipping scaffold push"
+  REMOTE_HAS_CONTENT=1
+else
+  REMOTE_HAS_CONTENT=0
+fi
+
+# 2a. Stage the runtime scaffold into a tmp dir (only if remote is empty)
+TMP=$(mktemp -d)
+log "    populating scaffold in $TMP"
+cp -a "$RUNTIME_SCAFFOLD_DIR/." "$TMP/"
+
+# Render scaffold templates with role-specific values
+python3 - "$TMP" "$AGENT_ID" "$REPO" "$ROLE" "$DISPLAY_NAME" "$PROFILE_NAME" <<'PYEOF'
+import sys, pathlib, re
+root, agent_id, repo, role, display, profile_name = sys.argv[1:7]
+root = pathlib.Path(root)
+mapping = {
+    "{{agent_id}}": agent_id, "{{repo}}": repo, "{{role}}": role,
+    "{{display_name}}": display, "{{profile_name}}": profile_name,
+}
+for p in root.rglob("*"):
+    if p.is_file() and p.suffix in (".md", ".yaml", ".yml", ".sh", ".py", ".gitignore", ".gitattributes"):
+        try:
+            t = p.read_text()
+            for k, v in mapping.items(): t = t.replace(k, v)
+            p.write_text(t)
+        except UnicodeDecodeError:
+            pass
+PYEOF
+
+# 3. Copy the profile's delta config + metadata and the project's SOUL.md as
+# the canonical starting personality. Shared defaults stay in the fleet default
+# profile and are not copied into the runtime repo.
+for f in config.yaml profile.yaml; do
+  [[ -f "$PROFILE_HOME/$f" ]] && cp "$PROFILE_HOME/$f" "$TMP/$f"
+done
+cp "$ROLE_DIR/SOUL.md" "$TMP/SOUL.md"
+
+# 4. Git init + LFS + initial commit + push (skip if remote already has content)
+if [[ "$REMOTE_HAS_CONTENT" == "0" ]]; then
+  (
+    cd "$TMP"
+    git init -b main >/dev/null
+    git lfs install --local >/dev/null 2>&1 || warn "git-lfs not installed; sessions.db will commit as raw binary"
+    git lfs track "*.db" >/dev/null 2>&1 || true
+    git lfs track "*.sqlite" >/dev/null 2>&1 || true
+    git add -A
+    git -c commit.gpgsign=false commit -m "Initial scaffold for $AGENT_ID" >/dev/null
+    git remote add origin "$REMOTE_URL"
+    git push -u origin main 2>&1 | tail -3
+  )
+fi
+
+# 5. Submodule-add into the role dir
+PROJECT_PATH="$(project_repo_path)" || die "no project git root"
+# Compute relative path from the ROLE dir (which exists), then append /runtime
+REL_ROLE_PATH="$(realpath --relative-to="$PROJECT_PATH" "$ROLE_DIR")"
+REL_SUBMODULE_PATH="${REL_ROLE_PATH}/runtime"
+log "    adding submodule at $REL_SUBMODULE_PATH"
+
+# Idempotent: if the submodule is already registered, just update it.
+# This handles re-runs where the .done marker was cleared or copier
+# --overwrite regenerated the scripts.
+SUBMODULE_ALREADY_REGISTERED=0
+if git -C "$PROJECT_PATH" submodule status "$REL_SUBMODULE_PATH" >/dev/null 2>&1; then
+  SUBMODULE_ALREADY_REGISTERED=1
+fi
+
+if [[ "$SUBMODULE_ALREADY_REGISTERED" == "1" ]]; then
+  log "    submodule already registered — updating"
+  (
+    cd "$PROJECT_PATH"
+    # If the local dir is missing (e.g. previous rm -rf), re-init it
+    if [[ ! -d "$REL_SUBMODULE_PATH/.git" ]]; then
+      git submodule update --init "$REL_SUBMODULE_PATH" 2>&1 | tail -3
+    fi
+  )
+else
+  # Clean any leftover untracked directory before adding
+  rm -rf "$RUNTIME_LOCAL"
+  (
+    cd "$PROJECT_PATH"
+    # -f forces the add even if a repo .gitignore matches the runtime path
+    # (e.g. a stray `runtime/` rule). The runtime is a tracked submodule gitlink,
+    # never ignored content, so forcing past .gitignore is always correct here.
+    git submodule add -f "$REMOTE_URL" "$REL_SUBMODULE_PATH" 2>&1 | tail -3
+  )
+fi
+
+# 6. Symlink the runtime back into ~/.hermes/profiles/<name>/ so hermes finds it.
+# Actually we WANT HERMES_HOME = the runtime dir, not the cloned profile.
+# Move the profile contents into runtime, then symlink the profile dir to runtime.
+PROFILE_HOME="$(profile_home)"
+if [[ -d "$PROFILE_HOME" && ! -L "$PROFILE_HOME" ]]; then
+  log "    migrating profile state into the runtime submodule"
+  # Preserve per-runtime config metadata, secrets, SOUL, and local profile
+  # assets from profile creation. OAuth provider credentials are fleet-shared
+  # via HERMES_OAUTH_FILE, so do not clone auth.json/auth.lock into each runtime.
+  for f in .env config.yaml profile.yaml SOUL.md; do
+    [[ -f "$PROFILE_HOME/$f" && ! -e "$RUNTIME_LOCAL/$f" ]] \
+      && cp "$PROFILE_HOME/$f" "$RUNTIME_LOCAL/$f"
+  done
+  for sub in skills plugins hooks cron skins; do
+    [[ -d "$PROFILE_HOME/$sub" && ! -e "$RUNTIME_LOCAL/$sub" ]] \
+      && cp -a "$PROFILE_HOME/$sub" "$RUNTIME_LOCAL/$sub"
+  done
+  rm -rf "$PROFILE_HOME"
+  ln -sfn "$RUNTIME_LOCAL" "$PROFILE_HOME"
+  log "    $PROFILE_HOME -> $RUNTIME_LOCAL"
+fi
+
+rm -rf "$TMP"
+mark_done 20-runtime-repo

package/templates/hermes-agent/template/.scripts/30-telegram.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# Capture a BotFather token and wire it into the runtime profile.
+# shellcheck source=_lib.sh
+source "$(dirname "$0")/_lib.sh"
+load_role_env
+
+already_done 30-telegram && { log "[30] telegram already wired — skipping"; exit 0; }
+
+if [[ "${SKIP_TELEGRAM:-0}" == "1" ]]; then
+  log "[30] telegram — SKIPPED (SKIP_TELEGRAM=1)"
+  mark_done 30-telegram
+  exit 0
+fi
+
+RUNTIME="$(profile_or_runtime_home)"
+
+cat >&2 <<EOF
+
+╭─ BotFather steps for @$BOT_HANDLE ─────────────────────────────────────╮
+│ 1. Open Telegram, message @BotFather                                   │
+│ 2. /newbot                                                             │
+│ 3. Display name:   $DISPLAY_NAME                                       │
+│ 4. Username:       $BOT_HANDLE  (must end in _bot)                     │
+│ 5. Copy the HTTP API token from the reply.                             │
+│ 6. /setjoingroups → Disable                                            │
+│ 7. /setprivacy    → Disable                                            │
+╰────────────────────────────────────────────────────────────────────────╯
+
+EOF
+
+if [[ -z "${TELEGRAM_BOT_TOKEN:-}" ]]; then
+  read -r -s -p "Paste the bot token for @$BOT_HANDLE (or empty to skip): " TELEGRAM_BOT_TOKEN
+  echo >&2
+fi
+
+if [[ -z "${TELEGRAM_BOT_TOKEN:-}" ]]; then
+  warn "    no token provided; Telegram step deferred"
+  warn "    re-run later:  cd $ROLE_DIR && SKIP_TELEGRAM=0 ./.scripts/30-telegram.sh"
+  exit 0
+fi
+
+# Sanity check
+if [[ ! "$TELEGRAM_BOT_TOKEN" =~ ^[0-9]+:.+ ]]; then
+  die "token doesn't look like a Telegram bot token"
+fi
+log "    verifying token..."
+info=$(curl -sS "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getMe")
+echo "$info" | grep -q '"ok":true' || die "Telegram rejected the token: $info"
+bot_username=$(echo "$info" | python3 -c "import sys,json; print(json.load(sys.stdin)['result']['username'])")
+bot_id=$(echo "$info"       | python3 -c "import sys,json; print(json.load(sys.stdin)['result']['id'])")
+log "    verified: @$bot_username (id=$bot_id)"
+
+# Resolve operator's allowed user id
+if [[ -z "${TELEGRAM_ALLOWED_USERS:-}" && -f "$HOME/.hermes/.env" ]]; then
+  TELEGRAM_ALLOWED_USERS=$(grep -E '^[[:space:]]*#?[[:space:]]*TELEGRAM_ALLOWED_USERS=' "$HOME/.hermes/.env" \
+    | tail -1 | sed -E 's/^[[:space:]]*#?[[:space:]]*TELEGRAM_ALLOWED_USERS=//; s/^"//; s/"$//')
+fi
+if [[ -z "${TELEGRAM_ALLOWED_USERS:-}" ]]; then
+  read -r -p "Your Telegram user id (allow-list for this bot): " TELEGRAM_ALLOWED_USERS
+fi
+
+# Write into the profile-local .env (symlinked to runtime on full installs).
+ENVF="$RUNTIME/.env"
+python3 - "$ENVF" "$TELEGRAM_BOT_TOKEN" "$TELEGRAM_ALLOWED_USERS" <<'PYEOF'
+import sys, pathlib, re
+path, token, allowed = sys.argv[1:4]
+p = pathlib.Path(path); p.parent.mkdir(parents=True, exist_ok=True)
+text = p.read_text() if p.exists() else ""
+for var in ("TELEGRAM_BOT_TOKEN","TELEGRAM_ALLOWED_USERS"):
+    text = re.sub(rf"(?m)^\s*#?\s*{var}=.*\n", "", text)
+text = text.rstrip() + "\n" + f'TELEGRAM_BOT_TOKEN="{token}"\nTELEGRAM_ALLOWED_USERS="{allowed}"\n'
+p.write_text(text)
+PYEOF
+chmod 600 "$ENVF"
+
+# Update role.yaml with the real bot username (in case it differs from the slug)
+yaml_set telegram.bot_username "$bot_username"
+
+# Enable telegram toolset for the named profile.
+env HERMES_HOME="$RUNTIME" "$HERMES_BIN" tools enable telegram hermes-telegram 2>/dev/null \
+  || warn "    couldn't auto-enable telegram toolset; run: $ROLE_DIR/hermes tools"
+
+log "    wired @$bot_username (id=$bot_id)"
+mark_done 30-telegram

package/templates/hermes-agent/template/.scripts/40-plane.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Create a Plane project in the configured workspace (one project per agent).
+# Workspace + base URL come from role.yaml / config.toml (see _lib.sh).
+# shellcheck source=_lib.sh
+source "$(dirname "$0")/_lib.sh"
+load_role_env
+
+already_done 40-plane && { log "[40] plane already set up — skipping"; exit 0; }
+[[ "${SKIP_PLANE:-0}" == "1" ]] && { log "[40] plane — SKIPPED"; mark_done 40-plane; exit 0; }
+
+[[ -n "$PLANE_API_KEY" ]] || { warn "[40] PLANE_API_KEY not set; skipping. set PLANE_33GOD_API_KEY and re-run ./.scripts/40-plane.sh"; exit 0; }
+
+# Build the 5-char identifier: <repo[0..2]><role[0..1]> uppercased
+RAW=$(printf '%s%s' "${REPO:0:3}" "${ROLE:0:2}" | tr -cd '[:alnum:]' | tr '[:lower:]' '[:upper:]')
+while (( ${#RAW} < 3 )); do RAW="${RAW}X"; done
+IDENT="${RAW:0:5}"
+
+# Project name = display_name (already smart-cased: "Bloodbank PM", "Hermes-Agent Dev").
+# Plane forbids hyphens in names — substitute spaces.
+NAME="${DISPLAY_NAME//-/ }"
+
+log "[40] creating plane project '$NAME' [$IDENT]"
+
+# Check for existing project with this identifier
+EXISTING=$(curl -sS "$PLANE_BASE/api/v1/workspaces/$PLANE_WORKSPACE/projects/?per_page=200" \
+  -H "X-API-Key: $PLANE_API_KEY" \
+  | python3 -c "
+import sys, json
+d = json.load(sys.stdin)
+ident = '$IDENT'
+for p in d.get('results', []):
+    if (p.get('identifier') or '').upper() == ident:
+        print(p['id']); break")
+
+if [[ -n "$EXISTING" ]]; then
+  log "    plane project $IDENT already exists (id=$EXISTING) — reusing"
+  PROJECT_ID="$EXISTING"
+else
+  RESP=$(curl -sS -X POST "$PLANE_BASE/api/v1/workspaces/$PLANE_WORKSPACE/projects/" \
+    -H "X-API-Key: $PLANE_API_KEY" \
+    -H "Content-Type: application/json" \
+    -d "$(python3 -c "import json,sys; print(json.dumps({'name': sys.argv[1], 'identifier': sys.argv[2], 'description': sys.argv[3]}))" \
+        "$NAME" "$IDENT" "Hermes agent board for $AGENT_ID")")
+  PROJECT_ID=$(echo "$RESP" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('id') or '')")
+  [[ -n "$PROJECT_ID" ]] || die "plane create failed: $RESP"
+  log "    plane project created id=$PROJECT_ID"
+fi
+
+yaml_set plane.identifier "$IDENT"
+echo "$PROJECT_ID" > "$ROLE_DIR/.scripts/.plane-project-id"
+mark_done 40-plane

package/templates/hermes-agent/template/.scripts/42-ticket-provider.sh

@@ -0,0 +1,187 @@
+#!/usr/bin/env bash
+# Bind this agent to the repo's ONE ticket board.
+#
+# Source of truth is the repo-root .project.json `ticket_provider` block
+# (written by the CommonProject base template). The model is:
+#   ONE board per repo — the PM owns it, the Scrum Master sentinel watches it.
+# So we never mint a per-agent, role-suffixed board ("Foo PM" / "Foo Scrum
+# Master"). Instead:
+#   1. If .project.json already names a board  -> BIND to it (no creation).
+#   2. Otherwise (hermes run on a repo with no CommonProject board yet)
+#      -> create ONE repo-named board and write it back into .project.json so
+#         it becomes the SOT for every agent in this repo.
+# Either way we register this agent under .project.json `agents` and mirror the
+# binding into role.yaml for back-compat (80-registry.sh / 99-summary.sh).
+# shellcheck source=_lib.sh
+source "$(dirname "$0")/_lib.sh"
+load_role_env
+# shellcheck source=lib/ticket-provider.sh
+source "$(dirname "$0")/lib/ticket-provider.sh"
+
+already_done 42-ticket-provider && { log "[42] ticket provider already set up — skipping"; exit 0; }
+
+# Locate the repo-root .project.json (the SOT).
+REPO_ROOT="$(project_repo_path 2>/dev/null || true)"
+[ -n "$REPO_ROOT" ] || REPO_ROOT="$(cd "$ROLE_DIR/../../.." 2>/dev/null && pwd)"
+PROJECT_JSON="$REPO_ROOT/.project.json"
+ROLE_DIR_REL="${ROLE_DIR#"$REPO_ROOT"/}"
+
+# pj <dotted.key> — read a string value from .project.json (empty if absent).
+pj() {
+  [ -f "$PROJECT_JSON" ] || { printf ''; return 0; }
+  python3 - "$PROJECT_JSON" "$1" <<'PY'
+import sys, json, pathlib
+try:
+    d = json.loads(pathlib.Path(sys.argv[1]).read_text())
+except Exception:
+    print(""); raise SystemExit(0)
+cur = d
+for k in sys.argv[2].split("."):
+    if isinstance(cur, dict) and k in cur:
+        cur = cur[k]
+    else:
+        print(""); raise SystemExit(0)
+print(cur if isinstance(cur, str) else "")
+PY
+}
+
+# pj_write — merge board binding (optional) + this agent into .project.json.
+# args: set_provider(0|1) provider board_id board_url workspace identifier team
+pj_write() {
+  REPO="$REPO" REPO_ROOT="$REPO_ROOT" AGENT_ID="$AGENT_ID" ROLE="$ROLE" \
+  ROLE_DIR_REL="$ROLE_DIR_REL" PROJECT_DESC="${PROJECT_DESC:-}" \
+  python3 - "$PROJECT_JSON" "$@" <<'PY'
+import sys, os, json, pathlib
+(path, set_provider, provider, board_id, board_url, workspace, identifier, team) = sys.argv[1:9]
+p = pathlib.Path(path)
+try:
+    d = json.loads(p.read_text())
+    if not isinstance(d, dict):
+        d = {}
+except Exception:
+    d = {}
+repo = os.environ.get("REPO", "")
+d.setdefault("project_name", repo)
+d.setdefault("project_slug", repo)
+if not d.get("repo_path"):
+    d["repo_path"] = os.environ.get("REPO_ROOT", "")
+if set_provider == "1":
+    tp = d.setdefault("ticket_provider", {})
+    tp["type"] = provider
+    if workspace:  tp["workspace"] = workspace
+    if identifier: tp["identifier"] = identifier
+    if board_id:   tp["board_id"] = board_id
+    if board_url:  tp["board_url"] = board_url
+    if team:       tp["team"] = team
+ag = d.setdefault("agents", {})
+ag[os.environ["AGENT_ID"]] = {"role": os.environ["ROLE"], "role_dir": os.environ["ROLE_DIR_REL"]}
+p.write_text(json.dumps(d, indent=2) + "\n")
+PY
+  log "    .project.json updated (agent=$AGENT_ID)"
+}
+
+# Mirror the binding into role.yaml so legacy consumers keep working.
+mirror_to_role_yaml() {
+  # mirror_to_role_yaml <provider> <board_id> <board_url> <workspace> <identifier> <team>
+  local provider="$1" bid="$2" burl="$3" ws="$4" ident="$5" team="$6"
+  yaml_set ticket_provider.name "$provider" 2>/dev/null || true
+  [ -n "$bid" ]  && yaml_set ticket_provider.board_id "$bid" 2>/dev/null || true
+  [ -n "$burl" ] && yaml_set ticket_provider.board_url "$burl" 2>/dev/null || true
+  case "$provider" in
+    plane)
+      [ -n "$bid" ] && echo "$bid" > "$ROLE_DIR/.scripts/.plane-project-id"
+      [ -n "$ws" ]    && yaml_set ticket_provider.workspace "$ws" 2>/dev/null || true
+      [ -n "$bid" ]   && yaml_set ticket_provider.project "$bid" 2>/dev/null || true
+      [ -n "$ws" ]    && yaml_set plane.workspace "$ws" 2>/dev/null || true
+      [ -n "$ident" ] && yaml_set plane.identifier "$ident" 2>/dev/null || true
+      ;;
+    trello)
+      [ -n "$bid" ] && yaml_set ticket_provider.board "$bid" 2>/dev/null || true
+      ;;
+    linear)
+      [ -n "$team" ] && yaml_set ticket_provider.team "$team" 2>/dev/null || true
+      ;;
+  esac
+}
+
+# ── Provider resolution ──────────────────────────────────────────────────
+# An existing repo board (in .project.json) wins — every agent binds to it.
+SOT_TYPE="$(pj ticket_provider.type)"
+SOT_BOARD_ID="$(pj ticket_provider.board_id)"
+SOT_URL="$(pj ticket_provider.board_url)"
+SOT_WS="$(pj ticket_provider.workspace)"
+SOT_IDENT="$(pj ticket_provider.identifier)"
+SOT_TEAM="$(pj ticket_provider.team)"
+
+# role.yaml provider comes from copier --data (the operator's pjangler choice).
+ROLE_PROVIDER="$(yaml_get ticket_provider.name)"
+
+if [ -n "$SOT_BOARD_ID" ]; then
+  # ── BIND to the repo's existing board ──────────────────────────────────
+  PROVIDER="${SOT_TYPE:-${ROLE_PROVIDER:-plane}}"
+  if [ -n "$ROLE_PROVIDER" ] && [ "$ROLE_PROVIDER" != "$PROVIDER" ]; then
+    warn "[42] requested provider '$ROLE_PROVIDER' but repo board is '$PROVIDER' (.project.json wins); binding to existing board"
+  fi
+  log "[42] binding $AGENT_ID to existing repo board (provider=$PROVIDER, id=$SOT_BOARD_ID)"
+  mirror_to_role_yaml "$PROVIDER" "$SOT_BOARD_ID" "$SOT_URL" "$SOT_WS" "$SOT_IDENT" "$SOT_TEAM"
+  pj_write 0 "$PROVIDER" "" "" "" "" ""   # register agent only; board already recorded
+  mark_done 42-ticket-provider
+  exit 0
+fi
+
+# ── No repo board yet: create ONE repo-named board (no role suffix) ───────
+PROVIDER="${ROLE_PROVIDER:-${SOT_TYPE:-plane}}"
+log "[42] no board in .project.json — bootstrapping a repo board (provider: $PROVIDER)"
+
+# Repo-based identity, matching CommonProject's scheme (slug[:4] uppercased).
+RAW=$(printf '%s' "$REPO" | tr -cd '[:alnum:]' | tr '[:lower:]' '[:upper:]')
+while [ ${#RAW} -lt 2 ]; do RAW="${RAW}X"; done
+IDENT="${SOT_IDENT:-${RAW:0:4}}"
+# Board NAME = repo name, separators->space, title-cased. NOT display_name —
+# display_name carries the role suffix and must never become the board name.
+NAME="$(printf '%s' "$REPO" | tr '_-' '  ' | python3 -c 'import sys; print(" ".join(w[:1].upper()+w[1:] for w in sys.stdin.read().split()))')"
+DESC="Ticket board for $REPO"
+
+case "$PROVIDER" in
+  linear)
+    if [[ -z "${LINEAR_API_KEY:-}" ]]; then
+      warn "[42] LINEAR_API_KEY not set; set role.yaml/.project.json ticket_provider.team and re-run ./.scripts/42-ticket-provider.sh"
+      pj_write 1 linear "" "" "" "$IDENT" "$SOT_TEAM"
+      mark_done 42-ticket-provider; exit 0
+    fi
+    OUT="$(tp resolve 2>/dev/null || true)"
+    BID="$(printf '%s' "$OUT" | python3 -c 'import sys,json
+try: print(json.load(sys.stdin).get("board_id",""))
+except Exception: print("")')"
+    BURL="$(printf '%s' "$OUT" | python3 -c 'import sys,json
+try: print(json.load(sys.stdin).get("board_url",""))
+except Exception: print("")')"
+    if [ -n "$BID" ]; then
+      mirror_to_role_yaml linear "$BID" "$BURL" "" "$IDENT" "$SOT_TEAM"
+      pj_write 1 linear "$BID" "$BURL" "" "$IDENT" "$SOT_TEAM"
+    else
+      warn "[42] linear resolve returned no board; set ticket_provider.team and re-run"
+      pj_write 1 linear "" "" "" "$IDENT" "$SOT_TEAM"
+    fi
+    ;;
+
+  plane|trello)
+    KEYVAR=PLANE_API_KEY; [ "$PROVIDER" = trello ] && KEYVAR=TRELLO_KEY
+    if [[ -z "${!KEYVAR:-}" ]]; then
+      warn "[42] $KEYVAR not set; skipping board creation. Set creds and re-run ./.scripts/42-ticket-provider.sh"
+      pj_write 1 "$PROVIDER" "" "" "${SOT_WS:-$PLANE_WORKSPACE}" "$IDENT" ""
+      mark_done 42-ticket-provider; exit 0
+    fi
+    OUT="$(tp create_board "$NAME" "$IDENT" "$DESC")" || die "create_board failed for $PROVIDER"
+    BID="$(printf '%s' "$OUT" | python3 -c 'import sys,json; print(json.load(sys.stdin).get("board_id",""))')"
+    BURL="$(printf '%s' "$OUT" | python3 -c 'import sys,json; print(json.load(sys.stdin).get("board_url",""))')"
+    WS="${SOT_WS:-$PLANE_WORKSPACE}"
+    [ "$PROVIDER" = trello ] && WS=""
+    mirror_to_role_yaml "$PROVIDER" "$BID" "$BURL" "$WS" "$IDENT" ""
+    pj_write 1 "$PROVIDER" "$BID" "$BURL" "$WS" "$IDENT" ""
+    ;;
+
+  *) die "unknown ticket provider: $PROVIDER (expected linear|plane|trello)" ;;
+esac
+
+mark_done 42-ticket-provider

package/templates/hermes-agent/template/.scripts/60-bloodbank.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# Install the bloodbank consumer + envelope helper into the runtime submodule.
+# shellcheck source=_lib.sh
+source "$(dirname "$0")/_lib.sh"
+load_role_env
+
+already_done 60-bloodbank && { log "[60] bloodbank already installed — skipping"; exit 0; }
+[[ "${SKIP_BLOODBANK:-0}" == "1" ]] && { log "[60] bloodbank — SKIPPED"; mark_done 60-bloodbank; exit 0; }
+
+RUNTIME="$ROLE_DIR/runtime"
+[[ -d "$RUNTIME" ]] || die "runtime not initialized; run 20-runtime-repo.sh first"
+
+log "[60] installing bloodbank consumer for $AGENT_ID"
+
+# Ensure the runtime consumer exists AND is rendered.
+#
+# Step 20 (20-runtime-repo.sh) only renders into a TMP dir during the
+# initial GH-repo push — the on-disk $RUNTIME_SCAFFOLD_DIR copy that lands
+# in the project repo keeps its `{{agent_id}}`/`{{repo}}`/`{{role}}`
+# placeholders. If $RUNTIME/bloodbank-consumer.py was ever lost (runtime
+# submodule wiped, manual rm, etc.) and then someone restored it by
+# copying from $RUNTIME_SCAFFOLD_DIR, they'd end up with an un-rendered
+# consumer subscribing to literal `bloodbank.evt.v1.repo.{{repo}}.>`.
+# This block handles both failure modes idempotently.
+CONSUMER="$RUNTIME/bloodbank-consumer.py"
+SCAFFOLD_CONSUMER="$RUNTIME_SCAFFOLD_DIR/bloodbank-consumer.py"
+
+needs_restore=0
+if [[ ! -f "$CONSUMER" ]]; then
+  log "    consumer missing in runtime — restoring from scaffold"
+  needs_restore=1
+elif grep -qE '\{\{(agent_id|repo|role|display_name)\}\}' "$CONSUMER"; then
+  warn "    consumer in runtime has un-rendered placeholders — re-rendering"
+  needs_restore=1
+fi
+
+if [[ "$needs_restore" == "1" ]]; then
+  [[ -f "$SCAFFOLD_CONSUMER" ]] || die "scaffold source missing: $SCAFFOLD_CONSUMER"
+  cp "$SCAFFOLD_CONSUMER" "$CONSUMER"
+  # Same placeholder set + values as 20-runtime-repo.sh's render pass.
+  python3 - "$CONSUMER" "$AGENT_ID" "$REPO" "$ROLE" "$DISPLAY_NAME" <<'PYEOF'
+import pathlib, sys
+p = pathlib.Path(sys.argv[1])
+agent_id, repo, role, display = sys.argv[2:6]
+mapping = {
+    "{{agent_id}}": agent_id, "{{repo}}": repo, "{{role}}": role,
+    "{{display_name}}": display,
+}
+t = p.read_text()
+for k, v in mapping.items():
+    t = t.replace(k, v)
+p.write_text(t)
+PYEOF
+fi
+chmod +x "$CONSUMER"
+
+# Health check: is NATS up?
+if (echo > /dev/tcp/$BLOODBANK_NATS_HOST/$BLOODBANK_NATS_PORT) 2>/dev/null; then
+  log "    NATS reachable at $BLOODBANK_NATS_HOST:$BLOODBANK_NATS_PORT"
+else
+  warn "    NATS not reachable; consumer will retry on start"
+  warn "    bring up:  cd $BLOODBANK_COMPOSE_DIR && docker compose -f compose/docker-compose.yml up -d"
+fi
+
+# Ensure nats-py is available in the hermes venv (uv-managed, no pip binary)
+if ! "$HERMES_AGENT_REPO/.venv/bin/python" -c "import nats" 2>/dev/null; then
+  warn "    python nats-py not installed in hermes venv; installing via uv"
+  if command -v uv >/dev/null 2>&1; then
+    (cd "$HERMES_AGENT_REPO" && uv pip install --quiet --python .venv/bin/python nats-py 2>&1 | tail -3) || true
+  else
+    warn "    uv not available either — install nats-py manually: cd $HERMES_AGENT_REPO && uv pip install nats-py"
+  fi
+fi
+
+mark_done 60-bloodbank

package/templates/hermes-agent/template/.scripts/70-systemd.sh

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+# Install systemd --user units: gateway, consumer, and hourly checkpoint timer.
+# shellcheck source=_lib.sh
+source "$(dirname "$0")/_lib.sh"
+load_role_env
+
+already_done 70-systemd && { log "[70] systemd already installed — skipping"; exit 0; }
+[[ "${SKIP_SYSTEMD:-0}" == "1" ]] && { log "[70] systemd — SKIPPED"; mark_done 70-systemd; exit 0; }
+
+RUNTIME="$ROLE_DIR/runtime"
+PROFILE_HOME="$(profile_or_runtime_home)"
+SYS_DIR="$HOME/.config/systemd/user"
+mkdir -p "$SYS_DIR"
+
+# Resolve absolute path to the runtime checkpoint helper
+CHECKPOINT_BIN="$ROLE_DIR/.scripts/checkpoint.sh"
+cp "$(dirname "$0")/checkpoint.sh" "$CHECKPOINT_BIN" 2>/dev/null || cat > "$CHECKPOINT_BIN" <<'CKPT'
+#!/usr/bin/env bash
+set -euo pipefail
+RUNTIME_DIR="$(cd "$(dirname "$0")/../runtime" && pwd)"
+cd "$RUNTIME_DIR"
+git add -A
+if git diff --cached --quiet; then exit 0; fi
+git -c commit.gpgsign=false commit -m "checkpoint $(date -Iseconds)" >/dev/null
+git push origin HEAD 2>&1 | tail -1 || true
+CKPT
+chmod +x "$CHECKPOINT_BIN"
+
+# Gateway unit
+GW_UNIT="hermes-${AGENT_ID}-gateway.service"
+cat > "$SYS_DIR/$GW_UNIT" <<UNIT
+[Unit]
+Description=Hermes Gateway — $DISPLAY_NAME
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+Environment=HERMES_HOME=$PROFILE_HOME
+Environment=HERMES_OAUTH_FILE=$HERMES_OAUTH_FILE
+Environment=CODEX_HOME=$CODEX_HOME
+EnvironmentFile=-$PROFILE_HOME/.env
+ExecStart=$HERMES_BIN gateway run --replace
+Restart=on-failure
+RestartSec=10
+StandardOutput=append:$PROFILE_HOME/logs/gateway.systemd.log
+StandardError=append:$PROFILE_HOME/logs/gateway.systemd.log
+
+[Install]
+WantedBy=default.target
+UNIT
+
+# Consumer unit
+CSM_UNIT="hermes-${AGENT_ID}-consumer.service"
+cat > "$SYS_DIR/$CSM_UNIT" <<UNIT
+[Unit]
+Description=Bloodbank Consumer — $DISPLAY_NAME
+After=network-online.target $GW_UNIT
+Wants=network-online.target
+
+[Service]
+Type=simple
+WorkingDirectory=$PROFILE_HOME
+Environment=HERMES_HOME=$PROFILE_HOME
+Environment=HERMES_OAUTH_FILE=$HERMES_OAUTH_FILE
+Environment=CODEX_HOME=$CODEX_HOME
+EnvironmentFile=-$PROFILE_HOME/.env
+ExecStart=$HERMES_AGENT_REPO/.venv/bin/python $PROFILE_HOME/bloodbank-consumer.py
+Restart=on-failure
+RestartSec=5
+StandardOutput=append:$PROFILE_HOME/logs/consumer.log
+StandardError=append:$PROFILE_HOME/logs/consumer.log
+
+[Install]
+WantedBy=default.target
+UNIT
+
+# Hourly checkpoint timer
+CKPT_SVC="hermes-${AGENT_ID}-checkpoint.service"
+CKPT_TIMER="hermes-${AGENT_ID}-checkpoint.timer"
+cat > "$SYS_DIR/$CKPT_SVC" <<UNIT
+[Unit]
+Description=Hermes Runtime Checkpoint — $DISPLAY_NAME
+
+[Service]
+Type=oneshot
+ExecStart=$CHECKPOINT_BIN
+StandardOutput=append:$RUNTIME/logs/checkpoint.log
+StandardError=append:$RUNTIME/logs/checkpoint.log
+UNIT
+cat > "$SYS_DIR/$CKPT_TIMER" <<UNIT
+[Unit]
+Description=Hourly checkpoint for $AGENT_ID
+
+[Timer]
+OnBootSec=15min
+OnUnitActiveSec=1h
+Unit=$CKPT_SVC
+Persistent=true
+
+[Install]
+WantedBy=timers.target
+UNIT
+
+mkdir -p "$RUNTIME/logs"
+mkdir -p "$PROFILE_HOME/logs"
+
+if systemd_user_available; then
+  systemctl --user daemon-reload
+  # `enable --now` both enables (persist across login) AND starts the unit now, so a
+  # freshly provisioned agent comes up live instead of dormant. Units with missing
+  # creds (e.g. a gateway with no Telegram token yet) fail softly via Restart=on-failure.
+  for u in "$GW_UNIT" "$CSM_UNIT" "$CKPT_TIMER"; do
+    systemctl --user enable --now "$u" >/dev/null 2>&1 && log "    enabled + started: $u" || warn "    failed to enable/start: $u"
+  done
+else
+  warn "    systemd --user not available; units installed at $SYS_DIR but not enabled"
+fi
+
+mark_done 70-systemd