@delorenj/pjangler 1.1.5 → 1.2.2

package/templates/hermes-agent/scripts/fleet-sync.sh

@@ -0,0 +1,369 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# fleet-sync — reconcile every deployed Hermes agent with the current
+# template and fleet contract. The registry (~/.hermes/agents-registry.yaml)
+# is the iteration source; the vendored template is the content source.
+#
+# Per agent:
+#   wrapper   <role_dir>/hermes regenerated from template/hermes.jinja
+#   contract  runtime/profile.yaml opts into config.inherit_from: default
+#   registry  ~/.hermes/profiles/<profile_name> -> <role_dir>/runtime
+#   role      <role_dir>/role.yaml profile: <profile_name>
+#   services  systemd gateway/consumer units restarted when something changed
+#
+# Default is a DRY-RUN drift report (exit 1 when drift exists, 0 when clean).
+# --apply writes the fixes and restarts the changed agents' services.
+# Anything that would require destroying or merging existing data (a real
+# directory where a symlink belongs, a profile.yaml with foreign content)
+# is reported as MANUAL and never touched.
+#
+# Usage: fleet-sync.sh [--apply] [--no-restart] [--agent <id>]...
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+WRAPPER_TEMPLATE="$SCRIPT_DIR/../template/hermes.jinja"
+
+HERMES_TEMPLATE_CONFIG="${HERMES_TEMPLATE_CONFIG:-${XDG_CONFIG_HOME:-$HOME/.config}/hermes-agent-template/config.toml}"
+cfg() {  # cfg <dotted.key> <default>
+  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")}"
+if [[ -f "$FLEET_ENV" ]]; then
+  # shellcheck disable=SC1090
+  source "$FLEET_ENV"
+fi
+REGISTRY_FILE="${HERMES_FLEET_REGISTRY_FILE:-$(cfg fleet.registry_file "$HOME/.hermes/agents-registry.yaml")}"
+PROFILES_DIR="${HERMES_FLEET_HOME:-$HOME/.hermes}/profiles"
+VOXXY_PLUGIN_DIR="${VOXXY_PLUGIN_DIR:-$(cfg fleet.voxxy_plugin_dir "$HOME/code/voxxy/plugins/tts/voxxy")}"
+VOX_URL_VALUE="${VOX_URL:-$(cfg fleet.vox_url 'https://vox.delo.sh')}"
+
+APPLY=0
+RESTART=1
+declare -a ONLY_AGENTS=()
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --apply) APPLY=1 ;;
+    --no-restart) RESTART=0 ;;
+    --agent) shift; ONLY_AGENTS+=("$1") ;;
+    -h|--help) sed -n '3,21p' "$0"; exit 0 ;;
+    *) echo "fleet-sync: unknown flag $1" >&2; exit 2 ;;
+  esac
+  shift
+done
+
+[[ -f "$REGISTRY_FILE" ]] || { echo "fleet-sync: registry not found: $REGISTRY_FILE" >&2; exit 2; }
+[[ -f "$WRAPPER_TEMPLATE" ]] || { echo "fleet-sync: wrapper template not found: $WRAPPER_TEMPLATE" >&2; exit 2; }
+
+# Registry -> TSV: agent_id, role_dir, profile_name, gateway_unit, consumer_unit
+read_registry() {
+  python3 - "$REGISTRY_FILE" <<'PYEOF'
+import sys
+
+try:
+    import yaml
+    with open(sys.argv[1], encoding="utf-8") as f:
+        data = yaml.safe_load(f) or {}
+except ModuleNotFoundError:
+    sys.stderr.write("fleet-sync: python3-yaml is required to read the registry\n")
+    sys.exit(2)
+
+for agent_id, a in sorted((data.get("agents") or {}).items()):
+    if not isinstance(a, dict):
+        continue
+    systemd = a.get("systemd") or {}
+    print("\t".join([
+        agent_id,
+        str(a.get("role_dir") or ""),
+        str(a.get("profile_name") or agent_id),
+        str(systemd.get("gateway_unit") or ""),
+        str(systemd.get("consumer_unit") or ""),
+    ]))
+PYEOF
+}
+
+render_wrapper() {  # render_wrapper <agent_id>
+  sed "s/{{ agent_id }}/$1/g" "$WRAPPER_TEMPLATE"
+}
+
+DRIFT=0
+FIXED=0
+declare -a RESTART_UNITS=()
+
+# Registry agents sharing a role_dir would overwrite each other's wrapper
+# and role.yaml on --apply; refuse to write into contested dirs.
+CONTESTED_DIRS="$(read_registry | cut -f2 | sort | uniq -d)"
+
+note() {  # note <agent> <status> <message>
+  printf '%-34s %-7s %s\n' "$1" "$2" "$3"
+}
+
+ensure_env_key() {  # ensure_env_key <path> <key> <value>
+  python3 - "$1" "$2" "$3" <<'PYEOF'
+import pathlib, sys
+
+path = pathlib.Path(sys.argv[1])
+key = sys.argv[2]
+value = sys.argv[3]
+lines = path.read_text().splitlines() if path.exists() else []
+needle = f"{key}="
+for idx, line in enumerate(lines):
+    if line.startswith(needle):
+        lines[idx] = f'{key}="{value}"'
+        break
+else:
+    lines.append(f'{key}="{value}"')
+path.write_text("\n".join(lines) + "\n")
+PYEOF
+}
+
+wanted_agent() {
+  [[ ${#ONLY_AGENTS[@]} -eq 0 ]] && return 0
+  local a
+  for a in "${ONLY_AGENTS[@]}"; do [[ "$a" == "$1" ]] && return 0; done
+  return 1
+}
+
+while IFS=$'\t' read -r agent_id role_dir profile_name gateway_unit consumer_unit; do
+  wanted_agent "$agent_id" || continue
+  if [[ -z "$role_dir" || ! -d "$role_dir" ]]; then
+    note "$agent_id" DRIFT "role_dir missing: ${role_dir:-<unset>} (MANUAL: deprovision or fix registry)"
+    DRIFT=$((DRIFT + 1))
+    continue
+  fi
+  if [[ -n "$CONTESTED_DIRS" ]] && grep -qx "$role_dir" <<<"$CONTESTED_DIRS"; then
+    note "$agent_id" DRIFT "role_dir claimed by multiple registry agents: $role_dir (MANUAL: fix registry)"
+    DRIFT=$((DRIFT + 1))
+    continue
+  fi
+  runtime="$role_dir/runtime"
+  changed=0
+
+  # 1. Launcher wrapper regenerated from the current template.
+  expected_wrapper="$(render_wrapper "$agent_id")"
+  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"
+      note "$agent_id" FIXED "wrapper regenerated from template"
+      changed=1; FIXED=$((FIXED + 1))
+    else
+      note "$agent_id" DRIFT "wrapper differs from template"
+      DRIFT=$((DRIFT + 1))
+    fi
+  fi
+
+  # 2. Inherited-config contract in runtime/profile.yaml.
+  profile_yaml="$runtime/profile.yaml"
+  if [[ ! -d "$runtime" ]]; then
+    note "$agent_id" DRIFT "runtime dir missing: $runtime (MANUAL: re-provision)"
+    DRIFT=$((DRIFT + 1))
+  elif [[ ! -f "$profile_yaml" ]]; then
+    if [[ $APPLY -eq 1 ]]; then
+      printf 'config:\n  inherit_from: default\n  save_mode: delta\n' > "$profile_yaml"
+      note "$agent_id" FIXED "profile.yaml written (inherit_from: default)"
+      changed=1; FIXED=$((FIXED + 1))
+    else
+      note "$agent_id" DRIFT "profile.yaml missing (no inherited config)"
+      DRIFT=$((DRIFT + 1))
+    fi
+  elif ! grep -q 'inherit_from: default' "$profile_yaml"; then
+    note "$agent_id" DRIFT "profile.yaml lacks inherit_from: default (MANUAL: merge contract)"
+    DRIFT=$((DRIFT + 1))
+  fi
+
+  # 3. Profile symlink ~/.hermes/profiles/<profile_name> -> runtime.
+  # LOAD-BEARING: hermes resolves agents launched as `hermes --profile <name>`
+  # through this path (and recreates it as a fresh standalone dir if missing,
+  # disconnecting the agent from its runtime) — so it MUST point at the runtime.
+  link="$PROFILES_DIR/$profile_name"
+  if [[ -L "$link" ]]; then
+    if [[ "$(readlink -f "$link")" != "$(readlink -f "$runtime")" ]]; then
+      if [[ $APPLY -eq 1 ]]; then
+        ln -sfn "$runtime" "$link"
+        note "$agent_id" FIXED "profile symlink repointed -> $runtime"
+        changed=1; FIXED=$((FIXED + 1))
+      else
+        note "$agent_id" DRIFT "profile symlink points at $(readlink "$link")"
+        DRIFT=$((DRIFT + 1))
+      fi
+    fi
+  elif [[ -e "$link" ]]; then
+    note "$agent_id" DRIFT "$link is a real directory, expected symlink (MANUAL: merge state)"
+    DRIFT=$((DRIFT + 1))
+  else
+    if [[ $APPLY -eq 1 ]]; then
+      mkdir -p "$PROFILES_DIR"
+      ln -sfn "$runtime" "$link"
+      note "$agent_id" FIXED "profile symlink created -> $runtime"
+      changed=1; FIXED=$((FIXED + 1))
+    else
+      note "$agent_id" DRIFT "profile symlink missing"
+      DRIFT=$((DRIFT + 1))
+    fi
+  fi
+
+  # 4. role.yaml binds the registry profile name.
+  role_yaml="$role_dir/role.yaml"
+  if [[ -f "$role_yaml" ]] && ! grep -q "^profile: $profile_name$" "$role_yaml"; then
+    if [[ $APPLY -eq 1 ]] && grep -q '^profile: ' "$role_yaml"; then
+      sed -i "s/^profile: .*/profile: $profile_name/" "$role_yaml"
+      note "$agent_id" FIXED "role.yaml profile -> $profile_name"
+      changed=1; FIXED=$((FIXED + 1))
+    else
+      note "$agent_id" DRIFT "role.yaml profile != $profile_name"
+      DRIFT=$((DRIFT + 1))
+    fi
+  fi
+
+  # 5. PM fleet voice contract: runtime plugin symlink + Voxxy config + VOX_URL.
+  role_name="$(basename "$role_dir")"
+  if [[ "$role_name" == "pm" && -d "$runtime" ]]; then
+    plugin_link="$runtime/plugins/tts/voxxy"
+    if [[ -d "$VOXXY_PLUGIN_DIR" ]]; then
+      if [[ -L "$plugin_link" ]]; then
+        if [[ "$(readlink -f "$plugin_link")" != "$(readlink -f "$VOXXY_PLUGIN_DIR")" ]]; then
+          if [[ $APPLY -eq 1 ]]; then
+            mkdir -p "$runtime/plugins/tts"
+            ln -sfn "$VOXXY_PLUGIN_DIR" "$plugin_link"
+            note "$agent_id" FIXED "runtime Voxxy plugin relinked"
+            changed=1; FIXED=$((FIXED + 1))
+          else
+            note "$agent_id" DRIFT "runtime Voxxy plugin points at $(readlink "$plugin_link")"
+            DRIFT=$((DRIFT + 1))
+          fi
+        fi
+      elif [[ -e "$plugin_link" ]]; then
+        note "$agent_id" DRIFT "$plugin_link exists and is not a symlink (MANUAL: merge runtime plugin state)"
+        DRIFT=$((DRIFT + 1))
+      else
+        if [[ $APPLY -eq 1 ]]; then
+          mkdir -p "$runtime/plugins/tts"
+          ln -sfn "$VOXXY_PLUGIN_DIR" "$plugin_link"
+          note "$agent_id" FIXED "runtime Voxxy plugin linked"
+          changed=1; FIXED=$((FIXED + 1))
+        else
+          note "$agent_id" DRIFT "runtime Voxxy plugin missing"
+          DRIFT=$((DRIFT + 1))
+        fi
+      fi
+    else
+      note "$agent_id" DRIFT "configured Voxxy plugin dir missing: $VOXXY_PLUGIN_DIR (MANUAL: install voxxy repo)"
+      DRIFT=$((DRIFT + 1))
+    fi
+
+    runtime_env="$runtime/.env"
+    if [[ -n "$VOX_URL_VALUE" ]]; then
+      vox_env_status="$(python3 - "$runtime_env" "$VOX_URL_VALUE" <<'PYEOF'
+import pathlib, sys
+path = pathlib.Path(sys.argv[1])
+expected = sys.argv[2]
+if not path.exists():
+    print('missing-file')
+    raise SystemExit(0)
+for line in path.read_text().splitlines():
+    if line.startswith('VOX_URL='):
+        current = line.split('=', 1)[1].strip().strip('"').strip("'")
+        print('ok' if current == expected else 'mismatch')
+        raise SystemExit(0)
+print('missing-key')
+PYEOF
+)"
+      case "$vox_env_status" in
+        ok) ;;
+        *)
+          if [[ $APPLY -eq 1 ]]; then
+            ensure_env_key "$runtime_env" VOX_URL "$VOX_URL_VALUE"
+            chmod 600 "$runtime_env" 2>/dev/null || true
+            note "$agent_id" FIXED "runtime .env VOX_URL -> $VOX_URL_VALUE"
+            changed=1; FIXED=$((FIXED + 1))
+          else
+            note "$agent_id" DRIFT "runtime .env missing/incorrect VOX_URL"
+            DRIFT=$((DRIFT + 1))
+          fi
+          ;;
+      esac
+    fi
+
+    config_status="$(python3 - "$runtime/config.yaml" <<'PYEOF'
+import pathlib, sys
+
+path = pathlib.Path(sys.argv[1])
+if not path.exists():
+    print('missing')
+    raise SystemExit(0)
+text = path.read_text()
+provider = 'voxxy' if 'provider: voxxy' in text else 'other'
+plugin = 'yes' if 'tts/voxxy' in text else 'no'
+voice = 'rick' if 'voice: rick' in text else 'other'
+print(f'{provider}|{plugin}|{voice}')
+PYEOF
+)"
+    if [[ "$config_status" != "voxxy|yes|rick" ]]; then
+      if [[ "$APPLY" -eq 1 ]]; then
+        HERMES_HOME="$runtime" "${HERMES_FLEET_BIN:-$(cfg fleet.hermes_bin "$HOME/.hermes/hermes-agent/.venv/bin/hermes")}" config set plugins.enabled.0 tts/voxxy >/dev/null 2>&1 || true
+        HERMES_HOME="$runtime" "${HERMES_FLEET_BIN:-$(cfg fleet.hermes_bin "$HOME/.hermes/hermes-agent/.venv/bin/hermes")}" config set tts.provider voxxy >/dev/null 2>&1 || true
+        HERMES_HOME="$runtime" "${HERMES_FLEET_BIN:-$(cfg fleet.hermes_bin "$HOME/.hermes/hermes-agent/.venv/bin/hermes")}" config set tts.voice rick >/dev/null 2>&1 || true
+        note "$agent_id" FIXED "runtime TTS config enforced -> voxxy/rick"
+        changed=1; FIXED=$((FIXED + 1))
+      else
+        note "$agent_id" DRIFT "runtime Voxxy config missing from config.yaml"
+        DRIFT=$((DRIFT + 1))
+      fi
+    fi
+  fi
+
+  if [[ $changed -eq 1 && $RESTART -eq 1 ]]; then
+    [[ -n "$gateway_unit" ]] && RESTART_UNITS+=("$gateway_unit")
+    [[ -n "$consumer_unit" ]] && RESTART_UNITS+=("$consumer_unit")
+  fi
+done < <(read_registry)
+
+# 5. Stale registry symlinks: entries pointing into fleet runtimes under a
+# name the registry does not know. Reported only — removal is a human call.
+known_names="$(read_registry | cut -f3 | sort -u)"
+if [[ -d "$PROFILES_DIR" ]]; then
+  for link in "$PROFILES_DIR"/*; do
+    [[ -L "$link" ]] || continue
+    name="$(basename "$link")"
+    grep -qx "$name" <<<"$known_names" && continue
+    target="$(readlink "$link")"
+    if [[ "$target" == */agents/hermes/* ]]; then
+      note "$name" STALE "registry symlink not in agents-registry -> $target (MANUAL: remove or register)"
+      DRIFT=$((DRIFT + 1))
+    fi
+  done
+fi
+
+if [[ ${#RESTART_UNITS[@]} -gt 0 ]]; then
+  echo
+  echo "Restarting: ${RESTART_UNITS[*]}"
+  systemctl --user try-restart "${RESTART_UNITS[@]}" || true
+fi
+
+echo
+if [[ $APPLY -eq 1 ]]; then
+  echo "fleet-sync: $FIXED fixed, $DRIFT unresolved (manual)"
+else
+  echo "fleet-sync: $DRIFT drift item(s). Re-run with --apply to fix."
+fi
+[[ $DRIFT -eq 0 ]] || exit 1

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

@@ -0,0 +1,252 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# migrate-unify — one-time fleet migration to the unified single-PM model.
+#
+# Decommissions the legacy `scrum-master` agents, collapsing each repo from a
+# PM + scrum-master pair down to a single PM. The PM keeps running untouched;
+# its checkpoint→heartbeat refresh is a separate uniform pass (and with
+# reconcile disabled by default the PM heartbeat is checkpoint-only, so removing
+# the scrum-master is behavior-complete for the collapse).
+#
+# Drives ENTIRELY off the registry's role=scrum-master entries
+# (role_dir / project_path / runtime_repo) — NEVER name-derived paths, because
+# keepy-money lives at ~/code/tiller, zshyzsh at ~/.config/zshyzsh, and
+# delocontainers at ~/docker.
+#
+# Safety model:
+#   * DRY-RUN by default — prints exactly what it WOULD do, touches nothing.
+#   * --apply performs the REVERSIBLE local teardown:
+#       - stop + disable + remove the scrum-master's systemd --user units
+#       - `git submodule deinit` + `git rm` the scrum-master role dir + clean
+#         .gitmodules / .git/modules  (STAGED only — never commits or pushes)
+#       - remove the ~/.hermes/profiles/<sm-id> symlink
+#       - drop the scrum-master entry from the fleet registry (.bak first)
+#   * The IRREVERSIBLE `gh repo delete` of each scrum-master runtime repo is held
+#     behind BOTH --decommission-sm-remotes AND --yes-i-mean-it, and runs only
+#     after all local teardown has succeeded.
+#
+# It never commits or pushes any project repo — staged submodule removals are
+# left for you to review and commit (some live in sensitive repos: ~/docker,
+# ~/.config/zshyzsh).
+#
+# Usage:
+#   migrate-unify.sh                      # dry-run report (all scrum-masters)
+#   migrate-unify.sh --apply              # reversible local teardown
+#   migrate-unify.sh --apply --decommission-sm-remotes --yes-i-mean-it
+#                                         # + delete the runtime repos on GitHub
+#   migrate-unify.sh --agent pjangler-scrum-master [--apply ...]   # one only
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+HERMES_TEMPLATE_CONFIG="${HERMES_TEMPLATE_CONFIG:-${XDG_CONFIG_HOME:-$HOME/.config}/hermes-agent-template/config.toml}"
+cfg() {  # cfg <dotted.key> <default>
+  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")}"
+[[ -f "$FLEET_ENV" ]] && { # shellcheck disable=SC1090
+  source "$FLEET_ENV"; }
+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
+DELETE_REMOTES=0
+CONFIRM=0
+declare -a ONLY_AGENTS=()
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --apply) APPLY=1 ;;
+    --decommission-sm-remotes) DELETE_REMOTES=1 ;;
+    --yes-i-mean-it) CONFIRM=1 ;;
+    --all) : ;;  # accepted for symmetry; default is already all scrum-masters
+    --agent) shift; ONLY_AGENTS+=("$1") ;;
+    -h|--help) sed -n '3,55p' "$0"; exit 0 ;;
+    *) echo "migrate-unify: unknown flag $1" >&2; exit 2 ;;
+  esac
+  shift
+done
+
+[[ -f "$REGISTRY_FILE" ]] || { echo "migrate-unify: registry not found: $REGISTRY_FILE" >&2; exit 2; }
+command -v python3 >/dev/null || { echo "migrate-unify: python3 required" >&2; exit 2; }
+
+MODE="DRY-RUN"; [[ $APPLY -eq 1 ]] && MODE="APPLY"
+echo "migrate-unify — mode: $MODE   registry: $REGISTRY_FILE"
+echo "================================================================"
+
+# Emit scrum-master rows (pjangler first), TSV: agent_id, repo, role_dir, project_path, runtime_repo, profile_name
+read_sm() {
+  python3 - "$REGISTRY_FILE" <<'PYEOF'
+import sys, yaml
+data = yaml.safe_load(open(sys.argv[1], encoding="utf-8")) or {}
+rows = []
+for aid, a in (data.get("agents") or {}).items():
+    if not isinstance(a, dict) or a.get("role") != "scrum-master":
+        continue
+    rows.append((aid, str(a.get("repo") or ""), str(a.get("role_dir") or ""),
+                 str(a.get("project_path") or ""), str(a.get("runtime_repo") or ""),
+                 str(a.get("profile_name") or aid)))
+# pjangler first (the reference repo / canary), then alphabetical.
+rows.sort(key=lambda r: (r[1] != "pjangler", r[0]))
+for r in rows:
+    print("\t".join(r))
+PYEOF
+}
+
+wanted() {
+  [[ ${#ONLY_AGENTS[@]} -eq 0 ]] && return 0
+  local a; for a in "${ONLY_AGENTS[@]}"; do [[ "$a" == "$1" ]] && return 0; done; return 1
+}
+
+run() {  # run <human-description> -- <cmd...>   (prints always; executes only on --apply)
+  local desc="$1"; shift
+  [[ "${1:-}" == "--" ]] && shift
+  if [[ $APPLY -eq 1 ]]; then
+    printf '    [do]   %s\n' "$desc"
+    local rc=0
+    "$@" >/dev/null 2>&1 || rc=$?
+    if [[ $rc -ne 0 ]]; then printf '      (non-fatal: returned %s)\n' "$rc"; fi
+  else
+    printf '    [dry]  %s\n' "$desc"
+  fi
+}
+
+declare -a REMOVE_IDS=()       # registry ids to drop (batched)
+declare -a DELETE_REPOS=()     # runtime repos to delete (gated, last)
+declare -a STAGED_REPOS=()     # project repos left with staged submodule removals
+PROCESSED=0
+
+while IFS=$'\t' read -r sm_id repo role_dir project_path runtime_repo profile_name; do
+  wanted "$sm_id" || continue
+  PROCESSED=$((PROCESSED + 1))
+  echo
+  echo ">>> $sm_id   (repo=$repo)"
+  echo "    role_dir     : $role_dir"
+  echo "    project_path : $project_path"
+  echo "    runtime_repo : $runtime_repo"
+
+  # 1. systemd --user units: stop + disable + remove every hermes-<sm_id>-* unit.
+  shopt -s nullglob
+  units=("$SYS_DIR/hermes-${sm_id}-"*)
+  shopt -u nullglob
+  if [[ ${#units[@]} -eq 0 ]]; then
+    echo "    units        : (none found on disk)"
+  else
+    for uf in "${units[@]}"; do
+      u="$(basename "$uf")"
+      run "stop+disable $u" -- systemctl --user disable --now "$u"
+      run "rm unit file $u" -- rm -f "$uf"
+    done
+    if [[ $APPLY -eq 1 ]]; then
+      systemctl --user daemon-reload 2>/dev/null || true
+      systemctl --user reset-failed 2>/dev/null || true
+    fi
+  fi
+
+  # 2. scrum-master runtime submodule + role dir (STAGED removal, never committed).
+  if [[ -n "$project_path" && ( -d "$project_path/.git" || -f "$project_path/.git" ) ]]; then
+    sm_rel="agents/hermes/scrum-master"
+    if [[ -e "$project_path/$sm_rel" ]]; then
+      run "git submodule deinit -f $sm_rel/runtime" -- git -C "$project_path" submodule deinit -f "$sm_rel/runtime"
+      run "git rm -rf $sm_rel (staged)" -- git -C "$project_path" rm -rf "$sm_rel"
+      run "rm .git/modules/$sm_rel residue" -- rm -rf "$project_path/.git/modules/$sm_rel"
+      run "scrub .gitmodules section" -- git -C "$project_path" config -f "$project_path/.gitmodules" --remove-section "submodule.$sm_rel/runtime"
+      if [[ $APPLY -eq 1 ]]; then STAGED_REPOS+=("$project_path"); fi
+    else
+      echo "    role dir     : already absent at $project_path/$sm_rel"
+    fi
+  else
+    echo "    submodule    : project_path is not a git repo, skipping submodule teardown: $project_path"
+  fi
+
+  # 3. profile symlink ~/.hermes/profiles/<sm_id>.
+  link="$PROFILES_DIR/$profile_name"
+  if [[ -L "$link" ]]; then
+    run "rm profile symlink $link" -- rm -f "$link"
+  elif [[ -e "$link" ]]; then
+    echo "    profile      : $link is a real dir, NOT a symlink — left untouched (MANUAL)"
+  else
+    echo "    profile      : no symlink at $link"
+  fi
+
+  # 4. registry entry (batched; rewritten once at the end with a .bak).
+  REMOVE_IDS+=("$sm_id")
+  echo "    registry     : will drop agents.$sm_id"
+
+  # 5. runtime repo delete (gated, deferred to the very end).
+  [[ -n "$runtime_repo" ]] && DELETE_REPOS+=("$runtime_repo")
+done < <(read_sm)
+
+if [[ $PROCESSED -eq 0 ]]; then
+  echo; echo "migrate-unify: no scrum-master agents matched. Nothing to do."
+  exit 0
+fi
+
+# --- Registry rewrite (batched) ---
+echo
+if [[ ${#REMOVE_IDS[@]} -gt 0 ]]; then
+  if [[ $APPLY -eq 1 ]]; then
+    python3 - "$REGISTRY_FILE" "${REMOVE_IDS[@]}" <<'PYEOF'
+import sys, shutil, datetime, yaml
+path = sys.argv[1]; ids = sys.argv[2:]
+shutil.copy(path, path + ".bak-" + datetime.datetime.now().strftime("%Y%m%d%H%M%S"))
+data = yaml.safe_load(open(path, encoding="utf-8")) or {}
+agents = data.get("agents") or {}
+removed = [i for i in ids if agents.pop(i, None) is not None]
+data["agents"] = agents
+with open(path, "w", encoding="utf-8") as f:
+    f.write(yaml.safe_dump(data, sort_keys=False))
+print("    registry: removed " + ", ".join(removed) + " (backup written)")
+PYEOF
+  else
+    echo "    [dry]  would drop registry entries: ${REMOVE_IDS[*]} (after .bak)"
+  fi
+fi
+
+# --- Irreversible remote deletes (double-gated, last) ---
+echo
+echo "Runtime repos to delete on GitHub:"
+printf '    %s\n' "${DELETE_REPOS[@]}"
+if [[ ${#DELETE_REPOS[@]} -gt 0 ]]; then
+  if [[ $APPLY -eq 1 && $DELETE_REMOTES -eq 1 && $CONFIRM -eq 1 ]]; then
+    if command -v gh >/dev/null 2>&1; then
+      for r in "${DELETE_REPOS[@]}"; do
+        printf '    [do]   gh repo delete %s --yes\n' "$r"
+        gh repo delete "$r" --yes 2>&1 | tail -1 || echo "      (delete failed or already gone: $r)"
+      done
+    else
+      echo "    gh not on PATH — cannot delete remotes."
+    fi
+  else
+    echo "    [HELD] add --apply --decommission-sm-remotes --yes-i-mean-it to delete these (IRREVERSIBLE)."
+  fi
+fi
+
+echo
+echo "================================================================"
+echo "migrate-unify: processed $PROCESSED scrum-master agent(s) in $MODE mode."
+if [[ $APPLY -eq 1 && ${#STAGED_REPOS[@]} -gt 0 ]]; then
+  echo
+  echo "Review + commit the staged scrum-master removals in these repos (NOT auto-committed):"
+  printf '%s\n' "${STAGED_REPOS[@]}" | sort -u | sed 's/^/    git -C /; s/$/ status/'
+fi