@delorenj/pjangler 1.2.21 → 1.2.25

package/templates/hermes-agent/docs/sentinel/development.md

@@ -127,8 +127,8 @@ The script:
 5. binds the PM to the existing board (it never creates one — it scrubs the
    provider key from Copier's environment so `42-ticket-provider.sh` skips board
    creation),
-6. installs the PM's heartbeat timer (board-reconciliation sentinel pass + gated
-   runtime checkpoint) as a `launchd` agent on macOS or a `systemd` timer on
+6. installs the PM's board-reconciliation heartbeat timer as a `launchd` agent
+   on macOS or a `systemd` timer on
    Linux,
 7. smoke-tests the board connection through the adapter.
 
@@ -160,7 +160,8 @@ order. Several of them reach outside the repository.
 <!-- prettier-ignore -->
 > [!CAUTION]
 > Full provisioning is outward-facing and partly interactive.
-> `20-runtime-repo.sh` creates a private GitHub repo with `gh repo create`,
+> `20-runtime-repo.sh` populates the ignored local runtime and links its profile;
+> it creates no GitHub storage,
 > `30-telegram.sh` prompts for a BotFather token and blocks waiting for input,
 > and `42-ticket-provider.sh` can create a Plane project. Don't run full
 > provisioning unattended.
@@ -171,10 +172,10 @@ script checks its flag and skips cleanly.
 | Flag | Skips |
 | --- | --- |
 | `SKIP_TELEGRAM` | The interactive BotFather token step. |
-| `SKIP_RUNTIME_REPO` | Creating the GitHub runtime repo. |
+| `SKIP_RUNTIME_REPO` | Legacy flag name: skip local runtime population/profile linking. No remote storage is created. |
 | `SKIP_PLANE` | Creating a Plane project. |
-| `SKIP_BLOODBANK` | Installing the BloodBank consumer. |
-| `SKIP_SYSTEMD` | Installing `systemd` units (gateway, consumer, heartbeat timer). |
+| `SKIP_BLOODBANK` | Compatibility no-op; Bloodbank ingress is fleet-shared. |
+| `SKIP_SYSTEMD` | Installing `systemd` units (profile gateway and heartbeat timer). |
 
 For example, a local install that creates no cloud resources:
 
@@ -191,9 +192,8 @@ on Linux through a `systemd` `EnvironmentFile` (for example
 `~/.hermes/<agent_id>.env`); on macOS the `launchd` agent sources that same
 per-agent env file, so write the key there.
 
-`SKIP_SYSTEMD` gates the gateway, consumer, and the fused `heartbeat` timer in
-`70-systemd.sh`. The heartbeat timer is what drives the sentinel pass and the
-gated checkpoint, so a local install that wants the sentinel running must leave
+`SKIP_SYSTEMD` gates the profile gateway and `heartbeat` timer in
+`70-systemd.sh`. A local install that wants the sentinel running must leave
 `SKIP_SYSTEMD` unset (or install the timer afterward).
 
 ## Propagating changes
@@ -219,12 +219,9 @@ The sentinel began as a bespoke loop on the `pm` role, was briefly extracted int
 a standalone `scrum-master` role with its own `continuous-ticket-sentinel` timer,
 and has now been folded back into the unified PM. Today there is exactly one
 role (`pm`), one engine (under `.scripts/sentinel/`), and one timer
-(`hermes-<agent>-heartbeat.timer`) that fuses the board-reconciliation sentinel
-pass with a gated runtime checkpoint. The old per-agent
-`hermes-<agent>-continuous-ticket-sentinel.timer` and the separate
-`hermes-<agent>-checkpoint.timer` are gone; both are replaced by the single
-`heartbeat` timer. The earlier standalone-role design is recoverable from Git
-history if you ever need to compare.
+(`hermes-<agent>-heartbeat.timer`) for board reconciliation. The earlier
+standalone-role design is recoverable from Git history if you ever need to
+compare.
 
 ## Known gotchas
 

package/templates/hermes-agent/docs/sentinel.md

@@ -2,7 +2,7 @@
 
 The PM runs a provider-agnostic ticket sentinel out-of-band on its heartbeat
 timer: a board-reconciliation pass with an autonomous adversarial review (act,
-do not wait), fused with a gated runtime checkpoint into a single timer tick.
+do not wait). Pure-local runtime persistence is outside the heartbeat contract.
 The full documentation lives in a dedicated handoff guide.
 
 This page is kept as a stable pointer so existing links keep working.

package/templates/hermes-agent/install-local.sh

@@ -21,6 +21,12 @@
 #   Provider creds: LINEAR_API_KEY | PLANE_API_KEY+PLANE_BASE | TRELLO_KEY+TRELLO_TOKEN
 set -eu
 
+# Fleet runtime publication. These values intentionally identify the reviewed
+# fork commit; clean installs must never fall back to NousResearch/main.
+HERMES_RUNTIME_GIT_URL="https://github.com/delorenj/hermes-agent.git"
+HERMES_RUNTIME_GIT_REF="feature/PJAN-19-routing-publication"
+HERMES_RUNTIME_GIT_SHA="113e1b182b6d72a7dd02a191f134a41668ceaf0e"
+
 say()  { printf '\033[36m%s\033[0m\n' "$*"; }
 warn() { printf '\033[33m%s\033[0m\n' "$*" >&2; }
 die()  { printf '\033[31m%s\033[0m\n' "$*" >&2; exit 1; }
@@ -53,7 +59,38 @@ if command -v hermes >/dev/null 2>&1; then
   say "1. hermes: found ($(command -v hermes))"
 else
   say "1. hermes: not found — installing"
-  run "curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash"
+  HERMES_INSTALL_DIR="${HERMES_INSTALL_DIR:-$HOME/.hermes/hermes-agent}"
+  if [ "${HAT_DRY_RUN:-0}" = "1" ]; then
+    say "  [dry-run] clone $HERMES_RUNTIME_GIT_URL@$HERMES_RUNTIME_GIT_REF"
+    say "  [dry-run] verify and install commit $HERMES_RUNTIME_GIT_SHA"
+  else
+    command -v git >/dev/null 2>&1 || die "git is required to install the pinned Hermes runtime"
+    if [ -d "$HERMES_INSTALL_DIR/.git" ]; then
+      _origin="$(git -C "$HERMES_INSTALL_DIR" remote get-url origin 2>/dev/null || true)"
+      [ "$_origin" = "$HERMES_RUNTIME_GIT_URL" ] \
+        || die "existing Hermes checkout origin is not the reviewed fleet fork: $HERMES_INSTALL_DIR"
+      git -C "$HERMES_INSTALL_DIR" fetch origin "$HERMES_RUNTIME_GIT_REF"
+    elif [ -e "$HERMES_INSTALL_DIR" ]; then
+      die "Hermes install path exists but is not the reviewed fork checkout: $HERMES_INSTALL_DIR"
+    else
+      mkdir -p "$(dirname "$HERMES_INSTALL_DIR")"
+      git clone --branch "$HERMES_RUNTIME_GIT_REF" --single-branch \
+        "$HERMES_RUNTIME_GIT_URL" "$HERMES_INSTALL_DIR"
+    fi
+    git -C "$HERMES_INSTALL_DIR" cat-file -e "$HERMES_RUNTIME_GIT_SHA^{commit}" \
+      || die "pinned Hermes commit is unavailable from the reviewed fork"
+    git -C "$HERMES_INSTALL_DIR" merge-base --is-ancestor \
+      "$HERMES_RUNTIME_GIT_SHA" "origin/$HERMES_RUNTIME_GIT_REF" \
+      || die "pinned Hermes commit is not on the reviewed publication ref"
+    bash "$HERMES_INSTALL_DIR/scripts/install.sh" \
+      --dir "$HERMES_INSTALL_DIR" \
+      --branch "$HERMES_RUNTIME_GIT_REF" \
+      --commit "$HERMES_RUNTIME_GIT_SHA" \
+      --skip-setup
+    _installed_sha="$(git -C "$HERMES_INSTALL_DIR" rev-parse HEAD)"
+    [ "$_installed_sha" = "$HERMES_RUNTIME_GIT_SHA" ] \
+      || die "Hermes installer did not retain pinned commit $HERMES_RUNTIME_GIT_SHA"
+  fi
   command -v hermes >/dev/null 2>&1 || die "hermes install did not put 'hermes' on PATH. Open a new shell and re-run."
 fi
 HERMES_BIN="$(command -v hermes)"
@@ -82,6 +119,9 @@ else
 [fleet]
 hermes_bin = "$HERMES_BIN"
 hermes_repo = "$HOME/.hermes/hermes-agent"
+hermes_git_url = "$HERMES_RUNTIME_GIT_URL"
+hermes_git_ref = "$HERMES_RUNTIME_GIT_REF"
+hermes_git_sha = "$HERMES_RUNTIME_GIT_SHA"
 fleet_env = "~/.hermes/fleet.env"
 registry_file = "~/.hermes/agents-registry.yaml"
 
@@ -92,9 +132,6 @@ runtime_repo_owner = ""
 base = "${PLANE_BASE:-}"
 workspace = ""
 
-[bloodbank]
-nats_host = "127.0.0.1"
-nats_port = 4222
 TOML
   fi
 fi

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

@@ -13,13 +13,15 @@ and recoverable on failure.
 | `memories/MEMORY.md` | yes | The condensed mental-model summary loaded each session |
 | `memories/USER.md` | yes | The operator's persona (Jarad DeLorenzo, ...) |
 | `sessions/sessions.db` | yes (LFS) | SQLite store of every conversation |
-| `bloodbank-consumer.py` | yes | NATS subscriber using canonical subjects plus envelope routing data |
 | `decisions/` | yes | Agent-emitted decisions, one file per important call |
 | `.env` | **no** | API keys + Telegram bot token (per-machine secret) |
 | `auth.json` | **no** | Deprecated local OAuth store; fleet auth defaults to `HERMES_OAUTH_FILE=~/.hermes/auth.json` |
 | `audio_cache/`, `image_cache/` | **no** | Regenerable caches |
 | `sandboxes/` | **no** | Per-session ephemeral execution dirs |
-| `bloodbank-inbox/` | **no** | Inbox queue for incoming bloodbank events |
+
+Bloodbank ingress is fleet-shared. The fleet gateway discovers this profile
+through `~/.hermes/agents-registry.yaml` and routes commands by
+`data.target_agent_id`; this runtime has no consumer process or inbox bridge.
 
 ## Checkpoint cadence
 

package/templates/hermes-agent/scripts/degit-runtime.sh

@@ -0,0 +1,192 @@
+#!/usr/bin/env bash
+# degit-runtime — make a repo's Hermes agent runtime(s) PURE LOCAL state.
+#
+# Run from (or point --root at) the ROOT of a project repo. Discovers every
+# agents/hermes/*/runtime under it and, in one shot, removes it from git and
+# gitignores it so it never re-enters version control.
+#
+# Policy = pure-local (fleet decision D2, 2026-07-21): the runtime is no longer
+# a git-tracked submodule NOR its own checkpoint repo. Per-agent memory
+# durability moves to the per-repo Hindsight bank. The
+# github.com/delorenj/agent-hm-*-pm remotes are left intact (recoverable) but
+# are no longer pushed to. This is the INVERSE of repair-runtime-checkpoint.sh,
+# which keeps the checkpoint repo alive.
+#
+# Per runtime:
+#   Layer A (project repo, if one exists):
+#     - gitlink submodule   -> git rm --cached <rel>
+#                              + drop [submodule "<rel>"] from .gitmodules
+#                              + rm -rf .git/modules/<rel>
+#     - plain tracked files -> git rm -r --cached <rel>
+#     - ensure .gitignore ignores agents/hermes/*/runtime/
+#   Layer B (the runtime itself):
+#     - if it has unpushed commits, push once (best-effort) unless --force
+#     - rm -rf <runtime>/.git            (retire the checkpoint repo)
+#     - write <runtime>/.gitignore = "*\n!.gitignore"   (pure-local marker)
+#
+# REPORTED but not touched here (fleet-level; handled by fleet-prune-debris.sh):
+#   ~/.hermes/profiles/<profile> symlink, agents-registry.yaml runtime_repo,
+#   and the now-dead -checkpoint.service/.timer units.
+#
+# Dry-run by default (prints the plan). --apply mutates. Idempotent: every step
+# checks state first, so a second run is a clean no-op.
+#
+# Usage: degit-runtime.sh [--apply] [--force] [--root DIR]
+set -euo pipefail
+
+APPLY=0; FORCE=0; ROOT=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --apply) APPLY=1 ;;
+    --force) FORCE=1 ;;
+    --root)  shift; ROOT="${1:-}" ;;
+    -h|--help) sed -n '2,37p' "$0"; exit 0 ;;
+    *) printf 'degit-runtime: unknown arg: %s\n' "$1" >&2; exit 2 ;;
+  esac
+  shift
+done
+
+die(){ printf 'ERROR: %s\n' "$*" >&2; exit 1; }
+note(){ printf '  %s\n' "$*"; }
+# run CMD... — execute on --apply, otherwise print the plan line.
+run(){ if [ "$APPLY" -eq 1 ]; then "$@"; else printf '  [would] %s\n' "$*"; fi; }
+
+ROOT="${ROOT:-$PWD}"
+[ -d "$ROOT" ] || die "no such directory: $ROOT"
+ROOT="$(cd "$ROOT" && pwd)"
+[ -d "$ROOT/agents/hermes" ] || die "no agents/hermes under $ROOT — run from a project repo root (or pass --root)"
+
+MODE="dry-run"; [ "$APPLY" -eq 1 ] && MODE="APPLY"
+printf '== degit-runtime (%s) :: %s ==\n' "$MODE" "$ROOT"
+
+# Project repo root (the superproject). Empty when the project has no git at all
+# (e.g. DeLoDocs, pjangler) — Layer A is then skipped.
+PROJ="$(git -C "$ROOT" rev-parse --show-toplevel 2>/dev/null || true)"
+if [ -n "$PROJ" ]; then note "project repo: $PROJ"; else note "project repo: (none — Layer A skipped)"; fi
+
+# Discover runtimes: agents/hermes/<role>/runtime (depth 2 under agents/hermes).
+mapfile -t RUNTIMES < <(find "$ROOT/agents/hermes" -mindepth 2 -maxdepth 2 -type d -name runtime 2>/dev/null | sort)
+[ "${#RUNTIMES[@]}" -gt 0 ] || die "no agents/hermes/*/runtime found under $ROOT"
+note "runtimes: ${#RUNTIMES[@]}"
+
+CHANGED=0
+
+ensure_project_ignore(){ # $1 = relpath of runtime from project root
+  local rel="$1" gi="$PROJ/.gitignore"
+  # Prefer a broad, role-agnostic rule; fall back to the exact path.
+  if git -C "$PROJ" check-ignore -q "$rel" 2>/dev/null; then
+    note ".gitignore already ignores $rel"; return 0
+  fi
+  local rule="agents/hermes/*/runtime/"
+  if [ -f "$gi" ] && grep -qxF "$rule" "$gi" 2>/dev/null; then
+    note ".gitignore already has rule: $rule"; return 0
+  fi
+  if [ "$APPLY" -eq 1 ]; then
+    printf '\n# Hermes agent runtime — pure-local state, never tracked (degit-runtime).\n%s\n' "$rule" >> "$gi"
+    note "appended ignore rule to .gitignore: $rule"
+  else
+    printf '  [would] append %s to %s\n' "$rule" "$gi"
+  fi
+  CHANGED=1
+}
+
+layer_a(){ # $1 = absolute runtime dir
+  local rt="$1" rel
+  [ -n "$PROJ" ] || return 0
+  rel="${rt#"$PROJ"/}"
+  # Is it a gitlink submodule (mode 160000) in the index?
+  if git -C "$PROJ" ls-files --stage -- "$rel" 2>/dev/null | grep -q '^160000 '; then
+    note "Layer A: '$rel' is a gitlink submodule -> de-submodule"
+    # -f: the gitlink may be staged with a pointer differing from HEAD (e.g. a
+    # freshly-added, not-yet-committed submodule). --cached is index-only and
+    # never touches the working tree, so forcing is safe.
+    run git -C "$PROJ" rm --cached -f -q -- "$rel"
+    if [ -f "$PROJ/.gitmodules" ] && git -C "$PROJ" config -f "$PROJ/.gitmodules" --get "submodule.$rel.url" >/dev/null 2>&1; then
+      run git -C "$PROJ" config -f "$PROJ/.gitmodules" --remove-section "submodule.$rel"
+      # Drop .gitmodules entirely once no [submodule] sections remain.
+      # (In dry-run the section is still present, so this stays conservative.)
+      if [ ! -f "$PROJ/.gitmodules" ] || ! grep -q '^\[submodule' "$PROJ/.gitmodules" 2>/dev/null; then
+        run rm -f "$PROJ/.gitmodules"
+        run git -C "$PROJ" rm --cached -q --ignore-unmatch -- .gitmodules
+      fi
+    fi
+    # The real gitdir (runtime layer already removed the runtime/.git pointer).
+    [ -e "$PROJ/.git/modules/$rel" ] && run rm -rf "$PROJ/.git/modules/$rel"
+    CHANGED=1
+  elif git -C "$PROJ" ls-files --error-unmatch -- "$rel" >/dev/null 2>&1; then
+    note "Layer A: '$rel' is tracked as plain content -> unstage"
+    run git -C "$PROJ" rm -r --cached -q -- "$rel"
+    CHANGED=1
+  else
+    note "Layer A: '$rel' is not tracked in the project repo (good)"
+  fi
+  ensure_project_ignore "$rel"
+}
+
+layer_b(){ # $1 = absolute runtime dir
+  local rt="$1"
+  # hard guard before any rm -rf
+  case "$rt" in */runtime) : ;; *) die "refusing: '$rt' does not end in /runtime" ;; esac
+  [ -d "$rt" ] || die "refusing: runtime dir vanished: $rt"
+
+  if [ -e "$rt/.git" ]; then
+    # Guard unpushed local commits: push once (best-effort) unless --force.
+    local ahead=0
+    if git -C "$rt" rev-parse --abbrev-ref --symbolic-full-name '@{u}' >/dev/null 2>&1; then
+      ahead="$(git -C "$rt" rev-list --count '@{u}..HEAD' 2>/dev/null || echo 0)"
+    else
+      ahead="unknown(no-upstream)"
+    fi
+    note "Layer B: runtime has .git (unpushed ahead: $ahead)"
+    if [ "$ahead" != "0" ]; then
+      if [ "$FORCE" -eq 1 ]; then
+        note "  --force: discarding local .git without pushing ($ahead ahead)"
+      else
+        note "  attempting one final push before retiring .git (--force to skip)"
+        if [ "$APPLY" -eq 1 ]; then
+          if GIT_SSH_COMMAND='ssh -o BatchMode=yes -o ConnectTimeout=20' \
+               timeout 45 git -C "$rt" push 2>/dev/null; then
+            note "  final push OK"
+          else
+            note "  MANUAL: final push FAILED and commits are unpushed — skipping .git removal for this runtime (re-run with --force to discard, or push by hand)"
+            return 0
+          fi
+        else
+          printf '  [would] git -C %s push   (final backup)\n' "$rt"
+        fi
+      fi
+    fi
+    run rm -rf "$rt/.git"
+    CHANGED=1
+  else
+    note "Layer B: runtime already has no .git (good)"
+  fi
+
+  # Pure-local marker: ignore everything except the marker itself.
+  local gi="$rt/.gitignore" want=$'*\n!.gitignore'
+  if [ -f "$gi" ] && [ "$(cat "$gi" 2>/dev/null)" = "$want" ]; then
+    note "Layer B: runtime/.gitignore already pure-local"
+  else
+    if [ "$APPLY" -eq 1 ]; then printf '%s\n' "$want" > "$gi"; note "wrote pure-local runtime/.gitignore"
+    else printf '  [would] write pure-local %s\n' "$gi"; fi
+    CHANGED=1
+  fi
+}
+
+for rt in "${RUNTIMES[@]}"; do
+  printf -- '-- %s\n' "$rt"
+  # Runtime layer FIRST: any final push needs the gitdir, which the project
+  # layer's `rm -rf .git/modules/<rel>` would otherwise remove.
+  layer_b "$rt"
+  layer_a "$rt"
+done
+
+echo
+if [ "$CHANGED" -eq 0 ]; then
+  printf 'RESULT: already pure-local — nothing to do.\n'
+elif [ "$APPLY" -eq 1 ]; then
+  printf 'RESULT: applied. Commit the project-repo changes (.gitignore / .gitmodules / unstaged runtime) when ready.\n'
+  printf '        Fleet-level cleanup (dead -checkpoint units, profile symlink) -> fleet-prune-debris.sh\n'
+else
+  printf 'RESULT: dry-run only. Re-run with --apply to mutate.\n'
+fi

package/templates/hermes-agent/scripts/fleet-prune-debris.sh

@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+# fleet-prune-debris — remove evolutionary debris from the Hermes fleet's
+# systemd USER units, and retire now-dead runtime-checkpoint units for agents
+# whose runtime is already pure-local (see degit-runtime.sh, fleet decision D2).
+#
+# Conservative by design. It only AUTO-removes things that are unambiguously
+# dead:
+#   - a hardcoded allowlist of DISABLED stale units (old singleton gateways,
+#     the delodocs per-agent dashboard) — and only while they are NOT active;
+#   - *.bak-* backup copies of hermes unit files;
+#   - hermes-<id>-pm-checkpoint.{service,timer} whose runtime has NO .git
+#     (already pure-local -> the checkpoint unit can never do anything again).
+# Everything ambiguous (active/enabled redundant units, the carrie persona, the
+# delonet-company-reporter archetype, FAILED units still git-backed) is REPORTED
+# as MANUAL and never touched.
+#
+# Dry-run by default. --apply performs the removals + one daemon-reload.
+#
+# Usage: fleet-prune-debris.sh [--apply]
+set -euo pipefail
+
+APPLY=0
+for a in "$@"; do
+  case "$a" in
+    --apply) APPLY=1 ;;
+    -h|--help) sed -n '2,26p' "$0"; exit 0 ;;
+    *) printf 'fleet-prune-debris: unknown arg: %s\n' "$a" >&2; exit 2 ;;
+  esac
+done
+
+SD="${XDG_CONFIG_HOME:-$HOME/.config}/systemd/user"
+[ -d "$SD" ] || { printf 'ERROR: no systemd user dir at %s\n' "$SD" >&2; exit 1; }
+
+MODE="dry-run"; [ "$APPLY" -eq 1 ] && MODE="APPLY"
+printf '== fleet-prune-debris (%s) :: %s ==\n' "$MODE" "$SD"
+note(){ printf '  %s\n' "$*"; }
+uc(){ systemctl --user "$@" 2>/dev/null; }         # user systemctl, quiet
+is_active(){ uc is-active "$1" >/dev/null; }
+exists(){ [ -e "$SD/$1" ]; }
+DID=0
+
+# remove_unit BASENAME... — disable+stop (if loaded) then rm the file(s).
+remove_unit(){
+  local u
+  for u in "$@"; do
+    exists "$u" || { note "absent (ok): $u"; continue; }
+    if [ "$APPLY" -eq 1 ]; then
+      uc disable --now "$u" || true
+      rm -f "$SD/$u"
+      note "removed: $u"
+    else
+      note "[would] disable --now + rm: $u"
+    fi
+    DID=1
+  done
+}
+
+printf '\n[1] disabled stale units (old singleton gateways / stale dashboard)\n'
+# From recon: these are DISABLED + superseded. Auto-remove only if not active.
+for u in hermes-gateway.service hermes-gateway-de01182b.service hermes-dashboard-delodocs-pm.service; do
+  if exists "$u"; then
+    if is_active "$u"; then note "MANUAL: $u is ACTIVE — expected disabled; confirm before removing";
+    else remove_unit "$u"; fi
+  else note "absent (ok): $u"; fi
+done
+
+printf '\n[2] *.bak-* backup copies of hermes unit files\n'
+shopt -s nullglob
+BAKS=("$SD"/hermes-*.bak-*)   # matches *.service.bak-* / *.timer.bak-* too (glob * spans dots)
+shopt -u nullglob
+if [ "${#BAKS[@]}" -eq 0 ]; then note "none"; else
+  for f in "${BAKS[@]}"; do
+    if [ "$APPLY" -eq 1 ]; then rm -f "$f"; note "removed: $(basename "$f")"; else note "[would] rm: $(basename "$f")"; fi
+    DID=1
+  done
+fi
+
+printf '\n[3] dead checkpoint units for pure-local runtimes\n'
+shopt -s nullglob
+CKPTS=("$SD"/hermes-*-pm-checkpoint.service)
+shopt -u nullglob
+if [ "${#CKPTS[@]}" -eq 0 ]; then note "none"; else
+  for svc in "${CKPTS[@]}"; do
+    base="$(basename "$svc")"
+    # Derive the runtime from ExecStart=<role_dir>/.scripts/checkpoint.sh
+    exec_line="$(grep -m1 '^ExecStart=' "$svc" 2>/dev/null | sed 's/^ExecStart=//')"
+    script="${exec_line%% *}"                    # strip any args
+    role_dir="$(dirname "$(dirname "$script")")" # .../pm/.scripts/x.sh -> .../pm
+    runtime="$role_dir/runtime"
+    if [ ! -d "$runtime" ]; then
+      note "MANUAL: $base -> runtime not found ($runtime); leaving"
+      continue
+    fi
+    if [ -e "$runtime/.git" ]; then
+      note "SKIP: $base -> runtime still git-backed (degit-runtime.sh first): $runtime"
+    else
+      note "pure-local -> retiring: $base (+ .timer)"
+      remove_unit "$base" "${base%.service}.timer"
+    fi
+  done
+fi
+
+printf '\n[4] MANUAL review (not auto-touched)\n'
+# Running-redundant / ambiguous units surfaced for a human decision.
+for u in hermes-gateway-intelliforia-voice-agent.service hermes-carrie-backend.service hermes-carrie-telegram-gateway.service; do
+  exists "$u" && note "MANUAL: $u ($(uc is-active "$u" || true)/$(uc is-enabled "$u" || true)) — redundant/legacy persona; decide keep vs retire"
+done
+# delonet-company-reporter is a different archetype (not a PM).
+shopt -s nullglob
+for u in "$SD"/hermes-delonet-company-reporter-*.service; do
+  b="$(basename "$u")"; note "MANUAL: $b ($(uc is-active "$b" || true)) — non-PM reporter archetype; repair or remove as a unit"
+done
+shopt -u nullglob
+# Any remaining failed hermes units.
+FAILED="$(uc --plain --no-legend list-units --state=failed 'hermes-*' | awk '{print $1}')"
+if [ -n "$FAILED" ]; then
+  printf '%s\n' "$FAILED" | while read -r f; do [ -n "$f" ] && note "FAILED: $f — investigate (degit fixes git-push failures; missing-script units are orphans to remove)"; done
+else note "no failed hermes units"; fi
+
+echo
+if [ "$APPLY" -eq 1 ]; then
+  uc daemon-reload || true
+  printf 'RESULT: applied + daemon-reload. Re-run to confirm idempotent (should be all "absent/none/SKIP").\n'
+elif [ "$DID" -eq 1 ]; then
+  printf 'RESULT: dry-run. Re-run with --apply to remove the [would] items above.\n'
+else
+  printf 'RESULT: nothing to prune (already clean) — only MANUAL items remain.\n'
+fi