@delorenj/pjangler 1.1.5 → 1.2.2

package/templates/hermes-agent/scripts/unify-pm.sh

@@ -0,0 +1,148 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# unify-pm — Phase C (safe subset): move every deployed PM toward the unified
+# single-PM model WITHOUT disrupting running services.
+#
+# Per PM (driven off registry role=pm, so specialized non-pm profiles are
+# naturally skipped):
+#   1. refresh .scripts/checkpoint.sh — applies the secret-scan gate to the live
+#      hourly checkpoint (the existing checkpoint.service ExecStarts this file).
+#   2. refresh the <role_dir>/hermes launcher to the runtime-only template
+#      (drops the stale profile-fallback; used for interactive `hermes chat`,
+#      never by the systemd units).
+#   3. ensure ~/.hermes/profiles/<profile_name> symlinks to ./runtime. This is
+#      LOAD-BEARING — hermes resolves `--profile <name>` through it (and recreates
+#      it as a fresh standalone dir if missing, disconnecting the agent from its
+#      runtime), so it is repaired/created, NEVER dropped.
+#
+# Does NOT touch gateway/consumer/checkpoint units, the registry, or runtimes.
+# The checkpoint→heartbeat unit rename + sentinel install is a separate pass.
+#
+# DRY-RUN by default; --apply performs; --agent <id>... scopes; pjangler-pm first.
+#
+# Usage: unify-pm.sh [--apply] [--agent <pm-id>]...
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+TEMPLATE_DIR="$SCRIPT_DIR/../template"
+CHECKPOINT_SRC="$TEMPLATE_DIR/.scripts/checkpoint.sh"
+WRAPPER_TEMPLATE="$TEMPLATE_DIR/hermes.jinja"
+
+HERMES_TEMPLATE_CONFIG="${HERMES_TEMPLATE_CONFIG:-${XDG_CONFIG_HOME:-$HOME/.config}/hermes-agent-template/config.toml}"
+cfg() {
+  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
+}
+
+REGISTRY_FILE="${HERMES_FLEET_REGISTRY_FILE:-$(cfg fleet.registry_file "$HOME/.hermes/agents-registry.yaml")}"
+PROFILES_DIR="${HERMES_FLEET_HOME:-$HOME/.hermes}/profiles"
+SYS_DIR="$HOME/.config/systemd/user"
+
+APPLY=0
+declare -a ONLY=()
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --apply) APPLY=1 ;;
+    --agent) shift; ONLY+=("$1") ;;
+    -h|--help) sed -n '3,30p' "$0"; exit 0 ;;
+    *) echo "unify-pm: unknown flag $1" >&2; exit 2 ;;
+  esac
+  shift
+done
+
+[[ -f "$REGISTRY_FILE" ]] || { echo "unify-pm: registry not found: $REGISTRY_FILE" >&2; exit 2; }
+[[ -f "$CHECKPOINT_SRC" ]] || { echo "unify-pm: template checkpoint.sh not found: $CHECKPOINT_SRC" >&2; exit 2; }
+[[ -f "$WRAPPER_TEMPLATE" ]] || { echo "unify-pm: wrapper template not found: $WRAPPER_TEMPLATE" >&2; exit 2; }
+
+MODE="DRY-RUN"; [[ $APPLY -eq 1 ]] && MODE="APPLY"
+echo "unify-pm — mode: $MODE   registry: $REGISTRY_FILE"
+echo "================================================================"
+
+# PM rows (pjangler first), TSV: agent_id, role_dir, profile_name
+read_pm() {
+  python3 - "$REGISTRY_FILE" <<'PYEOF'
+import sys, yaml
+d = yaml.safe_load(open(sys.argv[1], encoding="utf-8")) or {}
+rows = [(aid, str(a.get("role_dir") or ""), str(a.get("profile_name") or aid))
+        for aid, a in (d.get("agents") or {}).items()
+        if isinstance(a, dict) and a.get("role") == "pm"]
+rows.sort(key=lambda r: (r[0] != "pjangler-pm", r[0]))
+for r in rows:
+    print("\t".join(r))
+PYEOF
+}
+
+wanted() { [[ ${#ONLY[@]} -eq 0 ]] && return 0; local a; for a in "${ONLY[@]}"; do [[ "$a" == "$1" ]] && return 0; done; return 1; }
+
+CK=0; WR=0; SL=0; SKIP=0
+while IFS=$'\t' read -r aid role_dir profile_name; do
+  wanted "$aid" || continue
+  echo
+  echo ">>> $aid"
+  if [[ -z "$role_dir" || ! -d "$role_dir" ]]; then
+    echo "    role_dir missing: ${role_dir:-<unset>} — skipping"; SKIP=$((SKIP+1)); continue
+  fi
+  runtime="$role_dir/runtime"
+
+  # 1. checkpoint.sh secret-gate refresh.
+  dst="$role_dir/.scripts/checkpoint.sh"
+  if [[ ! -f "$dst" ]] || ! diff -q "$CHECKPOINT_SRC" "$dst" >/dev/null 2>&1; then
+    if [[ $APPLY -eq 1 ]]; then
+      mkdir -p "$role_dir/.scripts"; cp "$CHECKPOINT_SRC" "$dst"; chmod +x "$dst"
+      echo "    [do]  checkpoint.sh refreshed (secret-gate)"; CK=$((CK+1))
+    else
+      echo "    [dry] checkpoint.sh would be refreshed (secret-gate)"; CK=$((CK+1))
+    fi
+  else
+    echo "    checkpoint.sh already current"
+  fi
+
+  # 2. launcher → runtime-only template.
+  expected_wrapper="$(sed "s/{{ agent_id }}/$aid/g" "$WRAPPER_TEMPLATE")"
+  if [[ ! -f "$role_dir/hermes" ]] || ! diff -q <(printf '%s\n' "$expected_wrapper") "$role_dir/hermes" >/dev/null 2>&1; then
+    if [[ $APPLY -eq 1 ]]; then
+      printf '%s\n' "$expected_wrapper" > "$role_dir/hermes"; chmod +x "$role_dir/hermes"
+      echo "    [do]  launcher regenerated (runtime-only)"; WR=$((WR+1))
+    else
+      echo "    [dry] launcher would be regenerated (runtime-only)"; WR=$((WR+1))
+    fi
+  else
+    echo "    launcher already current"
+  fi
+
+  # 3. ensure the profile symlink points at the runtime (load-bearing; never drop).
+  link="$PROFILES_DIR/$profile_name"
+  if [[ -L "$link" && "$(readlink -f "$link")" == "$(readlink -f "$runtime")" ]]; then
+    echo "    profile symlink ok -> runtime"
+  elif [[ -e "$link" && ! -L "$link" ]]; then
+    echo "    profile entry is a REAL dir (MANUAL merge): $link — left untouched"; SKIP=$((SKIP+1))
+  else
+    if [[ $APPLY -eq 1 ]]; then
+      mkdir -p "$PROFILES_DIR"; ln -sfn "$runtime" "$link"; echo "    [do]  profile symlink set -> runtime"; SL=$((SL+1))
+    else
+      echo "    [dry] profile symlink would be set -> runtime"; SL=$((SL+1))
+    fi
+  fi
+done < <(read_pm)
+
+echo
+echo "================================================================"
+echo "unify-pm: checkpoint=$CK launcher=$WR symlink-repair=$SL skipped=$SKIP  ($MODE)"

package/templates/hermes-agent/template/.runtime-scaffold/README.md

@@ -1,16 +1,14 @@
 # {{agent_id}} — runtime
 
-This is the durable runtime for the **{{display_name}}** agent. The named
-Hermes profile `{{profile_name}}` points here from `~/.hermes/profiles/{{profile_name}}`,
-so Hermes sees an ordinary profile while this repo stays git-tracked and
-recoverable across machines.
+This is the HERMES_HOME for the **{{display_name}}** agent. It is git-tracked
+so memory, SOUL evolution, and conversation history are durable across machines
+and recoverable on failure.
 
 ## What's in here
 
 | Path | Tracked? | Purpose |
 | --- | --- | --- |
-| `profile.yaml` | yes | Opts this profile into inheriting config from default |
-| `config.yaml` | yes | Local config overrides only; shared defaults come from the fleet default |
+| `config.yaml` | yes | Inference + skill config (cloned from global at provision time) |
 | `SOUL.md` | yes | The agent's personality, evolves over time |
 | `memories/MEMORY.md` | yes | The condensed mental-model summary loaded each session |
 | `memories/USER.md` | yes | The operator's persona (Jarad DeLorenzo, ...) |
@@ -25,11 +23,14 @@ recoverable across machines.
 
 ## Checkpoint cadence
 
-- Hourly: systemd `--user` timer `hermes-{{agent_id}}-checkpoint.timer`
+- Heartbeat: systemd `--user` timer `hermes-{{agent_id}}-heartbeat.timer`. Each
+  tick reconciles the ticket board (the PM's sentinel pass) and then, gated to
+  at most once an hour, checkpoints this runtime.
 - On session end: hermes Stop hook (TODO: hook script in `~/.hermes/hooks/`)
 
-The checkpoint script lives in the parent's `.scripts/checkpoint.sh`. It
-`git add -A`, commits only if dirty, and pushes to `origin`.
+The heartbeat runner lives in the parent's `.scripts/heartbeat.sh`; it calls
+`.scripts/checkpoint.sh` internally, which `git add -A`, commits only if dirty,
+and pushes to `origin`.
 
 ## Restoring on a new machine
 

package/templates/hermes-agent/template/.scripts/01-config.sh

@@ -21,9 +21,8 @@ else
     cat > "$CONFIG" <<'TOML'
 # hermes-agent-template config — edit for your environment.
 [fleet]
-home = "~/.hermes"
-hermes_bin = "/home/delorenj/code/hermes-agent/.venv/bin/hermes"
-hermes_repo = "/home/delorenj/code/hermes-agent"
+hermes_bin = "~/.hermes/hermes-agent/.venv/bin/hermes"
+hermes_repo = "~/.hermes/hermes-agent"
 fleet_env = "~/.hermes/fleet.env"
 registry_file = "~/.hermes/agents-registry.yaml"
 canonical_skills_dir = "/home/delorenj/.agents/skills"

package/templates/hermes-agent/template/.scripts/05-fleet-env.sh

@@ -15,7 +15,6 @@ if [[ ! -f "$FLEET_ENV" ]]; then
 # All generated wrappers and provisioning scripts read this file.
 HERMES_FLEET_BIN=${HERMES_BIN}
 HERMES_FLEET_REPO=${HERMES_AGENT_REPO}
-HERMES_FLEET_HOME=${FLEET_HOME}
 HERMES_FLEET_REGISTRY_FILE=${REGISTRY_FILE}
 HERMES_FLEET_OAUTH_FILE=${HERMES_OAUTH_FILE}
 HERMES_FLEET_CODEX_HOME=${CODEX_HOME}
@@ -46,7 +45,6 @@ path.write_text("\n".join(lines) + "\n")
 PYEOF
 }
 
-upsert_fleet_env HERMES_FLEET_HOME "$FLEET_HOME"
 upsert_fleet_env HERMES_FLEET_OAUTH_FILE "$HERMES_OAUTH_FILE"
 upsert_fleet_env HERMES_FLEET_CODEX_HOME "$CODEX_HOME"
 chmod 600 "$FLEET_ENV"

package/templates/hermes-agent/template/.scripts/10-hermes-profile.sh

@@ -1,6 +1,10 @@
 #!/usr/bin/env bash
-# Create the per-agent Hermes profile. Config inherits explicitly from the
-# default fleet profile; secrets and runtime state stay profile-local.
+# Stage the per-agent runtime config/secrets via a TRANSIENT Hermes profile.
+# HERMES_HOME is the ./runtime submodule; this profile dir is a staging area
+# (cred-stripped .env + SOUL) that 20-runtime-repo.sh folds into the runtime and
+# then replaces with a symlink ~/.hermes/profiles/<name> -> ./runtime. That
+# symlink is load-bearing: hermes resolves `--profile <name>` invocations
+# through it (recreating it wrongly if it goes missing).
 # shellcheck source=_lib.sh
 source "$(dirname "$0")/_lib.sh"
 load_role_env
@@ -8,7 +12,7 @@ load_role_env
 already_done 10-hermes-profile && { log "[10] profile already created — skipping"; exit 0; }
 
 log "[10] creating hermes profile: $PROFILE_NAME"
-PROFILE_HOME="$(profile_home)"
+PROFILE_HOME="$HOME/.hermes/profiles/$PROFILE_NAME"
 
 # Set repo path to directory where .git is
 REPO_PATH="$(cd "$ROLE_DIR" && git rev-parse --show-toplevel 2>/dev/null || echo "$ROLE_DIR")"
@@ -16,21 +20,18 @@ REPO_PATH="$(cd "$ROLE_DIR" && git rev-parse --show-toplevel 2>/dev/null || echo
 if [[ -d "$PROFILE_HOME" ]]; then
   log "    profile dir already exists; reusing"
 else
-  env HERMES_HOME="$FLEET_HOME" "$HERMES_BIN" profile create \
-    "$PROFILE_NAME" --inherit-config --no-alias
+  # --clone (NOT --clone-all): copies config.yaml, .env, SOUL.md only.
+  # --clone-all has a recursion bug — it copies the entire ~/.hermes tree,
+  #   including profiles/ itself, producing nested profiles/<name>/profiles/<name>/...
+  # We do explicit skill + plugin + hooks copies below to avoid that.
+  "$HERMES_BIN" profile create "$PROFILE_NAME" --clone --no-alias
 fi
 
-# Existing profiles from older template runs may not have the inheritance
-# metadata yet. Make the operation idempotent and preserve unrelated
-# profile.yaml metadata such as descriptions.
-env HERMES_HOME="$FLEET_HOME" "$HERMES_BIN" profile config-inherit \
-  "$PROFILE_NAME" --from default
-
-# Copy local profile assets from the default profile without copying config or
-# credentials. Only config.yaml inherits; these directories remain local state.
-log "    mirroring local skills, plugins, hooks from default profile"
+# Manually copy the inheritable bits that --clone doesn't get.
+# These are content-only dirs; safe to mirror without recursion risk.
+log "    mirroring skills, plugins, hooks from default profile"
 for sub in skills plugins hooks cron skins; do
-  src="$FLEET_HOME/$sub"
+  src="$HOME/.hermes/$sub"
   dst="$PROFILE_HOME/$sub"
   if [[ -d "$src" && "$src" != "$PROFILE_HOME"* ]]; then
     mkdir -p "$dst"
@@ -45,10 +46,15 @@ rm -f "$PROFILE_HOME/gateway.pid" "$PROFILE_HOME/gateway_state.json" \
 # Belt-and-suspenders: if a profiles/ dir somehow exists, remove it
 [[ -d "$PROFILE_HOME/profiles" ]] && rm -rf "$PROFILE_HOME/profiles"
 
-# Strip messaging-platform credentials from any existing .env left by an older
-# clone-based profile. New inherited profiles do not copy default .env at all.
-# A sub-agent must establish its OWN identity via the Wire steps
-# (30-telegram etc), never borrow the operator's default profile token.
+# Strip inherited messaging-platform credentials from the cloned .env.
+# `profile create --clone` copies the DEFAULT profile's .env verbatim — and the
+# default profile is an operator's own agent (e.g. Condaleeza on Slack). Without
+# this, every sub-agent inherits the parent's bot token and would (a) hijack the
+# parent's Slack/Telegram socket if it ever connects, and (b) crash-loop: the
+# gateway treats an inherited-but-unusable platform as "configured", fails to
+# connect it, and exits non-fatal only when ZERO platforms are configured. A
+# sub-agent must establish its OWN identity via the Wire steps (30-telegram etc),
+# never borrow the parent's.
 PROFILE_ENV="$PROFILE_HOME/.env"
 if [[ -f "$PROFILE_ENV" ]]; then
   log "    stripping inherited platform credentials from profile .env"
@@ -73,6 +79,28 @@ PYEOF
   chmod 600 "$PROFILE_ENV"
 fi
 
+if [[ "$ROLE" == "pm" ]]; then
+  VOX_URL_VALUE="${VOX_URL:-$(config_get fleet.vox_url 'https://vox.delo.sh')}"
+  if [[ -n "$VOX_URL_VALUE" ]]; then
+    log "    ensuring VOX_URL is present for PM voice mode"
+    python3 - "$PROFILE_ENV" "$VOX_URL_VALUE" <<'PYEOF'
+import pathlib, sys
+
+path = pathlib.Path(sys.argv[1])
+vox_url = sys.argv[2]
+lines = path.read_text().splitlines() if path.exists() else []
+for idx, line in enumerate(lines):
+    if line.startswith("VOX_URL="):
+        lines[idx] = f'VOX_URL="{vox_url}"'
+        break
+else:
+    lines.append(f'VOX_URL="{vox_url}"')
+path.write_text("\n".join(lines) + "\n")
+PYEOF
+    chmod 600 "$PROFILE_ENV"
+  fi
+fi
+
 # Apply role-specific config overrides.
 log "    setting terminal.cwd = $REPO_PATH"
 env HERMES_HOME="$PROFILE_HOME" "$HERMES_BIN" config set terminal.cwd "$REPO_PATH"

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

@@ -7,7 +7,7 @@ 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)"
+PROFILE_HOME="$HOME/.hermes/profiles/$PROFILE_NAME"
 RUNTIME_LOCAL="$ROLE_DIR/runtime"
 GH_OWNER="${RUNTIME_REPO%%/*}"
 GH_NAME="${RUNTIME_REPO##*/}"
@@ -41,13 +41,13 @@ 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'
+python3 - "$TMP" "$AGENT_ID" "$REPO" "$ROLE" "$DISPLAY_NAME" <<'PYEOF'
 import sys, pathlib, re
-root, agent_id, repo, role, display, profile_name = sys.argv[1:7]
+root, agent_id, repo, role, display = sys.argv[1:6]
 root = pathlib.Path(root)
 mapping = {
     "{{agent_id}}": agent_id, "{{repo}}": repo, "{{role}}": role,
-    "{{display_name}}": display, "{{profile_name}}": profile_name,
+    "{{display_name}}": display,
 }
 for p in root.rglob("*"):
     if p.is_file() and p.suffix in (".md", ".yaml", ".yml", ".sh", ".py", ".gitignore", ".gitattributes"):
@@ -59,12 +59,16 @@ for p in root.rglob("*"):
             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
+# 3. Seed the runtime config from the canonical PM config — the fleet's single
+#    config source of truth (defaults to the global ~/.hermes/config.yaml). This
+#    is a provision-time snapshot; Hermes loads $HERMES_HOME/config.yaml directly
+#    (there is no live profile inheritance). Override via config.toml
+#    [fleet].canonical_pm_config to share one curated PM config across all repos.
+CANONICAL_PM_CONFIG="$(config_get fleet.canonical_pm_config "$HOME/.hermes/config.yaml")"
+if [[ -f "$CANONICAL_PM_CONFIG" ]]; then
+  cp "$CANONICAL_PM_CONFIG" "$TMP/config.yaml"
+fi
+# Copy the project's SOUL.md as the canonical starting personality.
 cp "$ROLE_DIR/SOUL.md" "$TMP/SOUL.md"
 
 # 4. Git init + LFS + initial commit + push (skip if remote already has content)
@@ -118,26 +122,66 @@ else
   )
 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)"
+# 6. Fold the staging profile state into the runtime, then symlink the profile
+# name AT the runtime. HERMES_HOME is the runtime submodule, but the profile
+# symlink is LOAD-BEARING: hermes resolves agents launched as
+# `hermes --profile <name>` through ~/.hermes/profiles/<name> (and recreates it
+# as a fresh standalone dir if it's missing, disconnecting the agent from its
+# runtime), so that name MUST resolve to the runtime.
+PROFILE_HOME="$HOME/.hermes/profiles/$PROFILE_NAME"
 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"
+  log "    migrating staging profile state into the runtime submodule"
+  # 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; do
+    [[ -f "$PROFILE_HOME/$f" && ! -e "$RUNTIME_LOCAL/$f" ]] && cp "$PROFILE_HOME/$f" "$RUNTIME_LOCAL/$f"
   done
   rm -rf "$PROFILE_HOME"
-  ln -sfn "$RUNTIME_LOCAL" "$PROFILE_HOME"
-  log "    $PROFILE_HOME -> $RUNTIME_LOCAL"
+fi
+ln -sfn "$RUNTIME_LOCAL" "$PROFILE_HOME"
+log "    profile symlink $PROFILE_HOME -> $RUNTIME_LOCAL"
+
+# Apply the one genuine per-repo config delta directly to the runtime config.
+env HERMES_HOME="$RUNTIME_LOCAL" "$HERMES_BIN" config set terminal.cwd "$PROJECT_PATH" >/dev/null 2>&1 || true
+
+if [[ "$ROLE" == "pm" ]]; then
+  VOXXY_PLUGIN_DIR="${VOXXY_PLUGIN_DIR:-$(config_get fleet.voxxy_plugin_dir "$HOME/code/voxxy/plugins/tts/voxxy")}"
+  if [[ -d "$VOXXY_PLUGIN_DIR" ]]; then
+    mkdir -p "$RUNTIME_LOCAL/plugins/tts"
+    ln -sfn "$VOXXY_PLUGIN_DIR" "$RUNTIME_LOCAL/plugins/tts/voxxy"
+    log "    linked Voxxy plugin into runtime"
+  else
+    warn "    Voxxy plugin dir missing: $VOXXY_PLUGIN_DIR"
+  fi
+
+  if [[ -x "$HERMES_BIN" ]]; then
+    env HERMES_HOME="$RUNTIME_LOCAL" "$HERMES_BIN" config set plugins.enabled.0 tts/voxxy >/dev/null 2>&1 || true
+    env HERMES_HOME="$RUNTIME_LOCAL" "$HERMES_BIN" config set tts.provider voxxy >/dev/null 2>&1 || true
+    env HERMES_HOME="$RUNTIME_LOCAL" "$HERMES_BIN" config set tts.voice rick >/dev/null 2>&1 || true
+    log "    set PM runtime TTS provider -> voxxy"
+  else
+    warn "    Hermes bin missing; skipped PM Voxxy config"
+  fi
+fi
+
+if [[ "$ROLE" == "pm" ]]; then
+  VOXXY_PLUGIN_DIR="${VOXXY_PLUGIN_DIR:-$(config_get fleet.voxxy_plugin_dir "$HOME/code/voxxy/plugins/tts/voxxy")}"
+  if [[ -d "$VOXXY_PLUGIN_DIR" ]]; then
+    mkdir -p "$RUNTIME_LOCAL/plugins/tts"
+    ln -sfn "$VOXXY_PLUGIN_DIR" "$RUNTIME_LOCAL/plugins/tts/voxxy"
+    log "    linked Voxxy plugin into runtime"
+  else
+    warn "    Voxxy plugin dir missing: $VOXXY_PLUGIN_DIR"
+  fi
+
+  if [[ -x "$HERMES_BIN" ]]; then
+    env HERMES_HOME="$RUNTIME_LOCAL" "$HERMES_BIN" config set plugins.enabled.0 tts/voxxy >/dev/null 2>&1 || true
+    env HERMES_HOME="$RUNTIME_LOCAL" "$HERMES_BIN" config set tts.provider voxxy >/dev/null 2>&1 || true
+    env HERMES_HOME="$RUNTIME_LOCAL" "$HERMES_BIN" config set tts.voice rick >/dev/null 2>&1 || true
+    log "    set PM runtime TTS provider -> voxxy"
+  else
+    warn "    Hermes bin missing; skipped PM Voxxy config"
+  fi
 fi
 
 rm -rf "$TMP"

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

@@ -12,7 +12,7 @@ if [[ "${SKIP_TELEGRAM:-0}" == "1" ]]; then
   exit 0
 fi
 
-RUNTIME="$(profile_or_runtime_home)"
+RUNTIME="$ROLE_DIR/runtime"
 
 cat >&2 <<EOF
 
@@ -59,7 +59,7 @@ 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).
+# Write into runtime/.env (this is HERMES_HOME for the agent)
 ENVF="$RUNTIME/.env"
 python3 - "$ENVF" "$TELEGRAM_BOT_TOKEN" "$TELEGRAM_ALLOWED_USERS" <<'PYEOF'
 import sys, pathlib, re
@@ -76,7 +76,7 @@ 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.
+# Enable telegram toolset for the 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"
 

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

@@ -3,9 +3,9 @@
 #
 # 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:
+#   ONE board per repo — the PM owns it, and its heartbeat reconciliation pass
+# watches it. So we never mint a per-agent, role-suffixed board ("Foo PM" /
+# "Foo Sentinel"). 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

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

@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
-# Install systemd --user units: gateway, consumer, and hourly checkpoint timer.
+# Install systemd --user units: gateway, consumer, and a fused heartbeat timer
+# (board-reconciliation sentinel pass + gated runtime checkpoint, one tick).
 # shellcheck source=_lib.sh
 source "$(dirname "$0")/_lib.sh"
 load_role_env
@@ -8,23 +9,15 @@ already_done 70-systemd && { log "[70] systemd already installed — skipping";
 [[ "${SKIP_SYSTEMD:-0}" == "1" ]] && { log "[70] systemd — SKIPPED"; mark_done 70-systemd; exit 0; }
 
 RUNTIME="$ROLE_DIR/runtime"
-PROFILE_HOME="$(profile_or_runtime_home)"
+REPO_ROOT="$(project_repo_path)" || REPO_ROOT="$ROLE_DIR"
 SYS_DIR="$HOME/.config/systemd/user"
-mkdir -p "$SYS_DIR"
+mkdir -p "$SYS_DIR" "$RUNTIME/logs"
 
-# 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"
+# The heartbeat runner (board-reconciliation sentinel pass + gated checkpoint)
+# and the checkpoint helper both render into the role dir; just ensure they are
+# executable. heartbeat.sh calls checkpoint.sh internally.
+HEARTBEAT_BIN="$ROLE_DIR/.scripts/heartbeat.sh"
+chmod +x "$HEARTBEAT_BIN" "$ROLE_DIR/.scripts/checkpoint.sh" 2>/dev/null || true
 
 # Gateway unit
 GW_UNIT="hermes-${AGENT_ID}-gateway.service"
@@ -36,15 +29,15 @@ Wants=network-online.target
 
 [Service]
 Type=simple
-Environment=HERMES_HOME=$PROFILE_HOME
+Environment=HERMES_HOME=$RUNTIME
 Environment=HERMES_OAUTH_FILE=$HERMES_OAUTH_FILE
 Environment=CODEX_HOME=$CODEX_HOME
-EnvironmentFile=-$PROFILE_HOME/.env
+EnvironmentFile=-$RUNTIME/.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
+StandardOutput=append:$RUNTIME/logs/gateway.systemd.log
+StandardError=append:$RUNTIME/logs/gateway.systemd.log
 
 [Install]
 WantedBy=default.target
@@ -60,57 +53,69 @@ Wants=network-online.target
 
 [Service]
 Type=simple
-WorkingDirectory=$PROFILE_HOME
-Environment=HERMES_HOME=$PROFILE_HOME
+WorkingDirectory=$RUNTIME
+Environment=HERMES_HOME=$RUNTIME
 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
+EnvironmentFile=-$RUNTIME/.env
+ExecStart=$HERMES_AGENT_REPO/.venv/bin/python $RUNTIME/bloodbank-consumer.py
 Restart=on-failure
 RestartSec=5
-StandardOutput=append:$PROFILE_HOME/logs/consumer.log
-StandardError=append:$PROFILE_HOME/logs/consumer.log
+StandardOutput=append:$RUNTIME/logs/consumer.log
+StandardError=append:$RUNTIME/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
+# Fused heartbeat: board-reconciliation sentinel pass + gated runtime checkpoint.
+# Frequent ticks (1 min); heartbeat.sh's own cooldown/lock logic rate-limits the
+# full Hermes pass, and the checkpoint is gated to ~hourly inside the runner.
+# The per-agent EnvironmentFiles load ticket-provider creds for the sentinel pass.
+HB_SVC="hermes-${AGENT_ID}-heartbeat.service"
+HB_TIMER="hermes-${AGENT_ID}-heartbeat.timer"
+cat > "$SYS_DIR/$HB_SVC" <<UNIT
 [Unit]
-Description=Hermes Runtime Checkpoint — $DISPLAY_NAME
+Description=Hermes Heartbeat (reconcile + checkpoint) — $DISPLAY_NAME
+After=network-online.target
+Wants=network-online.target
 
 [Service]
 Type=oneshot
-ExecStart=$CHECKPOINT_BIN
-StandardOutput=append:$RUNTIME/logs/checkpoint.log
-StandardError=append:$RUNTIME/logs/checkpoint.log
+WorkingDirectory=$REPO_ROOT
+Environment=HERMES_HOME=$RUNTIME
+Environment=HERMES_OAUTH_FILE=$HERMES_OAUTH_FILE
+Environment=CODEX_HOME=$CODEX_HOME
+EnvironmentFile=-%h/.config/hermes-agent/env
+EnvironmentFile=-%h/.hermes/env
+EnvironmentFile=-%h/.hermes/hermes-agent.env
+EnvironmentFile=-%h/.hermes/${AGENT_ID}.env
+EnvironmentFile=-$RUNTIME/.env
+ExecStart=$HEARTBEAT_BIN
+TimeoutStartSec=45min
+StandardOutput=append:$RUNTIME/logs/heartbeat.log
+StandardError=append:$RUNTIME/logs/heartbeat.log
 UNIT
-cat > "$SYS_DIR/$CKPT_TIMER" <<UNIT
+cat > "$SYS_DIR/$HB_TIMER" <<UNIT
 [Unit]
-Description=Hourly checkpoint for $AGENT_ID
+Description=Heartbeat (reconcile + checkpoint) for $AGENT_ID
 
 [Timer]
-OnBootSec=15min
-OnUnitActiveSec=1h
-Unit=$CKPT_SVC
+OnBootSec=1min
+OnUnitInactiveSec=1min
+Unit=$HB_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
+  for u in "$GW_UNIT" "$CSM_UNIT" "$HB_TIMER"; do
     systemctl --user enable --now "$u" >/dev/null 2>&1 && log "    enabled + started: $u" || warn "    failed to enable/start: $u"
   done
 else