@delorenj/pjangler 1.2.21 → 1.2.25

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

@@ -10,7 +10,7 @@ set -euo pipefail
 #   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
+#   services  stale per-profile Bloodbank consumers retired; gateways restarted
 #
 # 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.
@@ -74,7 +74,7 @@ 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
+# Registry -> TSV: agent_id, role_dir, profile_name, gateway_unit, legacy_consumer_unit
 read_registry() {
   python3 - "$REGISTRY_FILE" <<'PYEOF'
 import sys
@@ -91,7 +91,7 @@ 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([
+    print("\x1f".join([
         agent_id,
         str(a.get("role_dir") or ""),
         str(a.get("profile_name") or agent_id),
@@ -111,12 +111,113 @@ 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)"
+CONTESTED_DIRS="$(read_registry | cut -d $'\x1f' -f2 | sort | uniq -d)"
 
 note() {  # note <agent> <status> <message>
   printf '%-34s %-7s %s\n' "$1" "$2" "$3"
 }
 
+systemctl_user_unit_state() {  # systemctl_user_unit_state <is-active|is-enabled> <unit>
+  local query="$1" unit="$2" output rc first_line
+  command -v systemctl >/dev/null 2>&1 \
+    || { printf 'error|systemctl unavailable'; return 0; }
+  set +e
+  output="$(LC_ALL=C systemctl --user "$query" "$unit" 2>&1)"
+  rc=$?
+  set -e
+  first_line="${output%%$'\n'*}"
+  first_line="${first_line//$'\t'/ }"
+  first_line="${first_line//|/}"
+  case "$query:$rc:$first_line" in
+    is-active:0:active|is-active:0:reloading|is-active:0:activating|is-active:0:deactivating)
+      printf 'ok|%s' "$first_line" ;;
+    is-active:3:inactive|is-active:3:failed)
+      printf 'ok|%s' "$first_line" ;;
+    is-active:4:inactive)
+      printf 'ok|not-found' ;;
+    is-enabled:0:enabled|is-enabled:0:enabled-runtime|is-enabled:0:linked|is-enabled:0:linked-runtime|is-enabled:0:alias|is-enabled:0:static|is-enabled:0:indirect|is-enabled:0:generated|is-enabled:0:transient)
+      printf 'ok|%s' "$first_line" ;;
+    is-enabled:1:disabled|is-enabled:1:masked|is-enabled:1:masked-runtime)
+      printf 'ok|%s' "$first_line" ;;
+    is-enabled:4:not-found)
+      printf 'ok|not-found' ;;
+    *)
+      [[ -n "$first_line" ]] || first_line="exit $rc with no state"
+      printf 'error|%s' "$first_line" ;;
+  esac
+}
+
+retire_registry_consumer_metadata() {  # retire_registry_consumer_metadata <agent_id>
+  local target_agent="$1" lock_file="${REGISTRY_FILE}.lock" registry_lock_fd=""
+  command -v flock >/dev/null 2>&1 \
+    || { echo "fleet-sync: flock is required for registry updates" >&2; return 1; }
+  [[ ! -L "$lock_file" ]] \
+    || { echo "fleet-sync: refusing registry lock symlink: $lock_file" >&2; return 1; }
+  exec {registry_lock_fd}>"$lock_file"
+  chmod 600 "$lock_file"
+  flock -w 30 "$registry_lock_fd" \
+    || { echo "fleet-sync: timed out waiting for registry lock" >&2; return 1; }
+  python3 - "$REGISTRY_FILE" "$target_agent" <<'PYEOF'
+import errno
+import os
+import pathlib
+import sys
+import tempfile
+
+try:
+    import yaml
+except ImportError:
+    raise SystemExit("fleet-sync: python3-yaml is required")
+
+path = pathlib.Path(sys.argv[1])
+agent_id = sys.argv[2]
+if path.is_symlink():
+    raise SystemExit(f"fleet-sync: refusing registry symlink: {path}")
+data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+entry = (data.get("agents") or {}).get(agent_id)
+if isinstance(entry, dict) and isinstance(entry.get("systemd"), dict):
+    entry["systemd"].pop("consumer_unit", None)
+rendered = yaml.safe_dump(data, sort_keys=False)
+
+def fsync_parent(target):
+    unsupported = {errno.EINVAL, getattr(errno, "ENOTSUP", errno.EINVAL), errno.ENOSYS}
+    flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0)
+    try:
+        directory_fd = os.open(target.parent, flags)
+    except OSError as exc:
+        if exc.errno in unsupported:
+            return
+        raise
+    try:
+        try:
+            os.fsync(directory_fd)
+        except OSError as exc:
+            if exc.errno not in unsupported:
+                raise
+    finally:
+        os.close(directory_fd)
+
+fd, temporary = tempfile.mkstemp(prefix=f".{path.name}.fleet-sync-", dir=path.parent)
+try:
+    os.fchmod(fd, 0o600)
+    with os.fdopen(fd, "w", encoding="utf-8") as handle:
+        handle.write(rendered)
+        handle.flush()
+        os.fsync(handle.fileno())
+    os.replace(temporary, path)
+    os.chmod(path, 0o600)
+    fsync_parent(path)
+except BaseException:
+    try:
+        os.unlink(temporary)
+    except FileNotFoundError:
+        pass
+    raise
+PYEOF
+  flock -u "$registry_lock_fd"
+  eval "exec ${registry_lock_fd}>&-"
+}
+
 ensure_env_key() {  # ensure_env_key <path> <key> <value>
   python3 - "$1" "$2" "$3" <<'PYEOF'
 import pathlib, sys
@@ -143,7 +244,7 @@ wanted_agent() {
   return 1
 }
 
-while IFS=$'\t' read -r agent_id role_dir profile_name gateway_unit consumer_unit; do
+while IFS=$'\x1f' 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)"
@@ -158,6 +259,63 @@ while IFS=$'\t' read -r agent_id role_dir profile_name gateway_unit consumer_uni
   runtime="$role_dir/runtime"
   changed=0
 
+  # Legacy per-profile Bloodbank consumers are unhealthy until fully retired.
+  legacy_consumer_unit="${consumer_unit:-hermes-${agent_id}-consumer.service}"
+  if [[ ! "$legacy_consumer_unit" =~ ^hermes-[A-Za-z0-9._-]+-consumer\.service$ ]]; then
+    note "$agent_id" DRIFT "unsafe legacy consumer unit name in registry: $legacy_consumer_unit (MANUAL: fix registry)"
+    DRIFT=$((DRIFT + 1))
+  else
+    legacy_consumer_path="$HOME/.config/systemd/user/$legacy_consumer_unit"
+    legacy_consumer_present=0
+    [[ -n "$consumer_unit" || -e "$legacy_consumer_path" || -L "$legacy_consumer_path" ]] \
+      && legacy_consumer_present=1
+    if command -v systemctl >/dev/null 2>&1; then
+      legacy_active_result="$(systemctl_user_unit_state is-active "$legacy_consumer_unit")"
+      legacy_enabled_result="$(systemctl_user_unit_state is-enabled "$legacy_consumer_unit")"
+      if [[ "$legacy_active_result" == error\|* || "$legacy_enabled_result" == error\|* ]]; then
+        note "$agent_id" DRIFT "legacy consumer state query failed; unit and metadata preserved"
+        DRIFT=$((DRIFT + 1))
+        legacy_consumer_query_failed=1
+      else
+        legacy_consumer_query_failed=0
+        legacy_active_state="${legacy_active_result#*|}"
+        legacy_enabled_state="${legacy_enabled_result#*|}"
+        [[ "$legacy_active_state" == "not-found" && "$legacy_enabled_state" == "not-found" ]] \
+          || legacy_consumer_present=1
+      fi
+    elif [[ $legacy_consumer_present -eq 1 ]]; then
+      note "$agent_id" DRIFT "systemctl unavailable; legacy unit and metadata preserved"
+      DRIFT=$((DRIFT + 1))
+      legacy_consumer_query_failed=1
+    else
+      legacy_consumer_query_failed=0
+    fi
+    if [[ $legacy_consumer_query_failed -eq 0 && $legacy_consumer_present -eq 1 ]]; then
+      if [[ $APPLY -eq 0 ]]; then
+        note "$agent_id" DRIFT "legacy per-profile Bloodbank consumer remains: $legacy_consumer_unit"
+        DRIFT=$((DRIFT + 1))
+      else
+        if ! systemctl --user disable --now "$legacy_consumer_unit" >/dev/null 2>&1; then
+          note "$agent_id" DRIFT "legacy consumer disable failed; unit and metadata preserved"
+          DRIFT=$((DRIFT + 1))
+        else
+          legacy_active_result="$(systemctl_user_unit_state is-active "$legacy_consumer_unit")"
+          legacy_enabled_result="$(systemctl_user_unit_state is-enabled "$legacy_consumer_unit")"
+          if [[ "$legacy_active_result" != "ok|inactive" || "$legacy_enabled_result" != "ok|disabled" ]]; then
+            note "$agent_id" DRIFT "legacy consumer is not proven inactive and disabled; unit and metadata preserved"
+            DRIFT=$((DRIFT + 1))
+          else
+            rm -f -- "$legacy_consumer_path"
+            systemctl --user daemon-reload >/dev/null 2>&1 || true
+            retire_registry_consumer_metadata "$agent_id"
+            note "$agent_id" FIXED "legacy per-profile Bloodbank consumer retired"
+            FIXED=$((FIXED + 1))
+          fi
+        fi
+      fi
+    fi
+  fi
+
   # 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
@@ -334,13 +492,12 @@ PYEOF
 
   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)"
+known_names="$(read_registry | cut -d $'\x1f' -f3 | sort -u)"
 if [[ -d "$PROFILES_DIR" ]]; then
   for link in "$PROFILES_DIR"/*; do
     [[ -L "$link" ]] || continue

package/templates/hermes-agent/scripts/hermes-runtime-templatize.py

@@ -0,0 +1,321 @@
+#!/usr/bin/env python3
+"""hermes-runtime-templatize — dedup a runtime's skills onto the shared
+hermes-base pack, at PER-SKILL granularity, with scoped-name overrides.
+
+Why per-skill: 14 of the 18 base dirs are CATEGORY dirs (apple, creative,
+github, …) holding 73 sub-skills total. hermes keys skill identity on each
+SKILL.md's frontmatter `name:` (and the containing dir name), so dedup and
+override must happen at the sub-skill level, not the category-dir level.
+
+Policy (fleet decision, 2026-07-23):
+  * a base sub-skill IDENTICAL to the pack  -> delete the local copy (it then
+    resolves read-only from the pack via config.yaml skills.external_dirs).
+  * a base sub-skill that was OVERWRITTEN   -> SCOPED-NAME override: rename its
+    dir AND its frontmatter `name:` to `<name>-<slug>`, promoting it from a
+    shared-base skill to an unambiguous agent-scoped copy. The pristine base
+    stays in the pack for every other agent; no collision, no data loss.
+  * an agent-ADDED skill (not in the pack)  -> left untouched in the overlay.
+Then the pack is wired into config.yaml (if not already). Empty category dirs
+left after deletions are pruned.
+
+A runtime whose config has no skills.external_dirs (bare-layout agents) is
+BLOCKED (can't resolve deleted skills from the pack) and left untouched.
+
+Dry-run by default; --apply mutates. Idempotent (a second run finds nothing to
+do). `verify` checks a runtime is name-disjoint from the pack.
+
+Usage:
+  hermes-runtime-templatize.py dedup  [--apply] [--root DIR] [--slug S] [--pack DIR]
+  hermes-runtime-templatize.py verify [--root DIR] [--pack DIR]
+"""
+from __future__ import annotations
+import argparse, hashlib, os, re, shutil, sys
+from pathlib import Path
+
+DEFAULT_PACK = Path("/home/delorenj/code/skillex/packs/hermes-base/0.18.2")
+
+# The canonical fleet skills.external_dirs (in precedence order). Every agent
+# should carry exactly these; `provision` normalizes to them (preserving any
+# agent-specific extras).
+MAINLINE_EXTERNAL_DIRS = [
+    "/home/delorenj/code/skillex/skill-sets/global/.system",
+    "/home/delorenj/code/skillex/packs/bmad/6.10.1-next.31",
+    str(DEFAULT_PACK),
+]
+
+# Mirror hermes agent/skill_utils.py: only these dirs are pruned from skill
+# scanning, and a SKILL.md inside a skill's support dir is progressive-
+# disclosure data, not an active skill root. Keeping this identical means we
+# classify EXACTLY the skills hermes treats as active (never .archive, .git, …).
+EXCLUDED_SKILL_DIRS = frozenset((
+    ".archive", ".git", ".github", ".hub", ".mypy_cache", ".nox", ".pytest_cache",
+    ".ruff_cache", ".tox", ".venv", "__pycache__", "node_modules", "site-packages", "venv",
+))
+SKILL_SUPPORT_DIRS = frozenset(("references", "templates", "assets", "scripts"))
+
+
+def iter_skill_roots(skills_dir: Path):
+    """Yield each ACTIVE SKILL.md path (exact copy of hermes iter_skill_index_files)."""
+    matches = []
+    for root, dirs, files in os.walk(str(skills_dir)):
+        has = "SKILL.md" in files
+        dirs[:] = [d for d in dirs if d not in EXCLUDED_SKILL_DIRS and not (has and d in SKILL_SUPPORT_DIRS)]
+        if "SKILL.md" in files:
+            matches.append(os.path.join(root, "SKILL.md"))
+    for p in sorted(matches):
+        yield Path(p)
+
+
+def treehash(d: Path) -> str:
+    lines = []
+    for p in sorted(d.rglob("*")):
+        if p.is_file():
+            lines.append(hashlib.sha256(p.read_bytes()).hexdigest() + "  " + str(p.relative_to(d)))
+    lines.sort()
+    return hashlib.sha256("\n".join(lines).encode()).hexdigest()
+
+
+def frontmatter_name(smd: Path) -> str:
+    try:
+        t = smd.read_text(encoding="utf-8")
+    except Exception:
+        return smd.parent.name
+    m = re.match(r"^---\s*\n(.*?)\n---", t, re.S)
+    if m:
+        mm = re.search(r"^name:\s*(.+?)\s*$", m.group(1), re.M)
+        if mm:
+            return mm.group(1).strip().strip("'\"")
+    return smd.parent.name
+
+
+def set_frontmatter_name(smd: Path, newname: str) -> None:
+    t = smd.read_text(encoding="utf-8")
+    m = re.match(r"^(---\s*\n)(.*?)(\n---)", t, re.S)
+    if m:
+        head, fm, fence = m.group(1), m.group(2), m.group(3)
+        if re.search(r"^name:\s*.+$", fm, re.M):
+            fm = re.sub(r"^name:\s*.+$", f"name: {newname}", fm, count=1, flags=re.M)
+        else:
+            fm = f"name: {newname}\n" + fm
+        smd.write_text(head + fm + fence + t[m.end():], encoding="utf-8")
+    else:
+        smd.write_text(f"---\nname: {newname}\n---\n" + t, encoding="utf-8")
+
+
+def pack_index(pack: Path) -> dict[str, str]:
+    """frontmatter-name -> treehash of the skill's own dir, across the pack."""
+    idx: dict[str, str] = {}
+    for smd in iter_skill_roots(pack):
+        idx[frontmatter_name(smd)] = treehash(smd.parent)
+    return idx
+
+
+def runtimes(root: Path):
+    base = root / "agents" / "hermes"
+    if not base.is_dir():
+        return []
+    return sorted(p for p in base.glob("*/runtime") if p.is_dir())
+
+
+def config_wireable(cfg: Path, pack: Path) -> tuple[bool, bool]:
+    """(wireable, already). wireable=False for a config with no external_dirs."""
+    if not cfg.is_file():
+        return (False, False)
+    txt = cfg.read_text(encoding="utf-8")
+    if str(pack) in txt:
+        return (True, True)
+    return (bool(re.search(r"^\s*external_dirs:", txt, re.M)), False)
+
+
+def wire(cfg: Path, pack: Path, apply: bool) -> bool:
+    ok, already = config_wireable(cfg, pack)
+    if already:
+        return True
+    if not ok:
+        return False
+    if not apply:
+        return True
+    lines = cfg.read_text(encoding="utf-8").splitlines()
+    out, i, done = [], 0, False
+    while i < len(lines):
+        m = re.match(r"^(\s*)external_dirs:\s*(.*)$", lines[i])
+        if not done and m:
+            indent, inline = m.group(1), m.group(2).strip()
+            if inline == "":                      # block form: keep existing items, append ours
+                out.append(lines[i])
+                j, item_indent = i + 1, None
+                while j < len(lines) and lines[j].strip().startswith("- "):
+                    if item_indent is None:
+                        item_indent = len(lines[j]) - len(lines[j].lstrip())
+                    out.append(lines[j]); j += 1
+                out.append(" " * (item_indent if item_indent is not None else indent) + "- " + str(pack))
+                done, i = True, j
+                continue
+            else:                                 # inline form ([] or [a, b]) -> convert to block
+                inner = inline.strip("[]").strip()
+                items = [x.strip() for x in inner.split(",") if x.strip()] if inner else []
+                out.append(f"{indent}external_dirs:")
+                for it in items:
+                    out.append(f"{indent}- {it}")
+                out.append(f"{indent}- {pack}")
+                done, i = True, i + 1
+                continue
+        out.append(lines[i]); i += 1
+    if not done:
+        return False
+    cfg.write_text("\n".join(out) + "\n", encoding="utf-8")
+    return True
+
+
+def set_external_dirs(cfg: Path, dirs: list[str], apply: bool) -> str:
+    """Normalize skills.external_dirs to `dirs` (canonical order) + preserve any
+    agent-specific extras. Creates skills:/external_dirs: if absent. Idempotent."""
+    if not cfg.is_file():
+        return "no config.yaml"
+    lines = cfg.read_text(encoding="utf-8").splitlines()
+    skills_i = next((i for i, l in enumerate(lines) if re.match(r"^skills:\s*$", l)), None)
+    items = [f"  - {d}" for d in dirs]
+    if skills_i is None:
+        new = lines[:]
+        if new and new[-1].strip() != "":
+            new.append("")
+        new += ["skills:", "  external_dirs:"] + items
+        action = "created skills.external_dirs"
+    else:
+        end = next((j for j in range(skills_i + 1, len(lines)) if lines[j] and not lines[j][0].isspace()), len(lines))
+        ext_i = next((j for j in range(skills_i + 1, end) if re.match(r"^\s*external_dirs:", lines[j])), None)
+        if ext_i is None:
+            new = lines[:skills_i + 1] + ["  external_dirs:"] + items + lines[skills_i + 1:]
+            action = "added external_dirs under skills:"
+        else:
+            m = re.match(r"^(\s*)external_dirs:\s*(.*)$", lines[ext_i])
+            indent, inline = m.group(1), m.group(2).strip()
+            existing, item_end = [], ext_i + 1
+            if inline == "":
+                while item_end < end and lines[item_end].strip().startswith("- "):
+                    existing.append(re.sub(r"^-\s*", "", lines[item_end].strip()))
+                    item_end += 1
+            elif inline != "[]":
+                existing = [x.strip() for x in inline.strip("[]").split(",") if x.strip()]
+            merged = list(dirs) + [x for x in existing if x not in dirs]
+            new = lines[:ext_i] + [f"{indent}external_dirs:"] + [f"{indent}- {d}" for d in merged] + lines[item_end:]
+            action = "normalized external_dirs"
+    if new == lines:
+        return "ok (already mainline)"
+    if apply:
+        cfg.write_text("\n".join(new) + "\n", encoding="utf-8")
+    return action
+
+
+def provision(root: Path, dirs: list[str], apply: bool) -> None:
+    for rt in runtimes(root):
+        print(f"-- {rt}")
+        print("   " + set_external_dirs(rt / "config.yaml", dirs, apply))
+
+
+def prune_empty_categories(sk: Path, apply: bool) -> int:
+    """Remove immediate child dirs of skills/ that hold no SKILL.md anymore."""
+    n = 0
+    for child in sorted(p for p in sk.iterdir() if p.is_dir()):
+        if not any(child.rglob("SKILL.md")):
+            n += 1
+            if apply:
+                shutil.rmtree(child)
+    return n
+
+
+def dedup(root: Path, slug: str, pack: Path, apply: bool) -> None:
+    idx = pack_index(pack)
+    for rt in runtimes(root):
+        sk = rt / "skills"
+        print(f"-- {rt}")
+        if not sk.is_dir():
+            print("   no skills/ — nothing to do"); continue
+        ok, already = config_wireable(rt / "config.yaml", pack)
+        if not ok:
+            print("   BLOCKED: config.yaml has no skills.external_dirs (bare-layout) — provision a skills block first; untouched")
+            continue
+        ident, scoped, adds = [], [], []
+        for smd in iter_skill_roots(sk):
+            d = smd.parent
+            name = frontmatter_name(smd)
+            if name in idx:
+                (ident if treehash(d) == idx[name] else scoped).append((d, name))
+            else:
+                adds.append(name)
+        print(f"   classify (per-skill): base-identical={len(ident)}  overwritten={len(scoped)}  agent-adds={len(adds)}")
+        if not apply:
+            for d, name in scoped:
+                print(f"   [would] scoped-name override: {d.relative_to(sk)} -> name '{name}-{slug}'")
+            for d, name in ident:
+                print(f"   [would] rm {d.relative_to(sk)} (identical → pack)")
+            print(f"   [would] wire pack into config.yaml{' (already)' if already else ''}")
+            continue
+        if not wire(rt / "config.yaml", pack, True):
+            print("   ABORT: wire failed — leaving skills untouched"); continue
+        for d, name in scoped:
+            newdir = d.parent / f"{d.name}-{slug}"
+            if newdir.exists():
+                print(f"   SKIP scoped rename (target exists): {newdir.relative_to(sk)}"); continue
+            set_frontmatter_name(d / "SKILL.md", f"{name}-{slug}")
+            d.rename(newdir)
+        for d, name in ident:
+            shutil.rmtree(d)
+        pruned = prune_empty_categories(sk, True)
+        print(f"   reconciled: {len(ident)} identical removed, {len(scoped)} scoped→*-{slug}, {pruned} empty categories pruned; base resolves from pack")
+
+
+def verify(root: Path, pack: Path) -> int:
+    idx = pack_index(pack)
+    bad = 0
+    for rt in runtimes(root):
+        sk = rt / "skills"
+        if not sk.is_dir():
+            continue
+        for smd in iter_skill_roots(sk):
+            name = frontmatter_name(smd)
+            if name in idx and treehash(smd.parent) != idx[name]:
+                print(f"   NOT DISJOINT: {rt.name}: local '{name}' shares a pack name but differs (scope-rename it)")
+                bad += 1
+            if name in idx and treehash(smd.parent) == idx[name]:
+                print(f"   REDUNDANT: {rt.name}: local '{name}' is an identical copy of the pack (delete it)")
+                bad += 1
+    print("verify:", "CLEAN ✓ (runtime is name-disjoint from the pack)" if bad == 0 else f"{bad} issue(s)")
+    return 1 if bad else 0
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    for name in ("dedup", "verify", "provision"):
+        s = sub.add_parser(name)
+        s.add_argument("--root", default=".")
+        s.add_argument("--pack", default=str(DEFAULT_PACK))
+        if name in ("dedup", "provision"):
+            s.add_argument("--apply", action="store_true")
+        if name == "dedup":
+            s.add_argument("--slug", default=None, help="agent scope token (default: repo dir basename, lowercased)")
+    a = ap.parse_args()
+    root = Path(a.root).resolve()
+    pack = Path(a.pack)
+    if not (pack / "SKILL.md").exists() and not any(pack.rglob("SKILL.md")):
+        print(f"ERROR: no skills under pack {pack}", file=sys.stderr); return 2
+    if a.cmd == "verify":
+        return verify(root, pack)
+    if a.cmd == "provision":
+        mode = "APPLY" if a.apply else "dry-run"
+        print(f"== provision external_dirs ({mode}) :: {root} ==")
+        provision(root, MAINLINE_EXTERNAL_DIRS, a.apply)
+        print("\nRESULT:", "applied." if a.apply else "dry-run. --apply to write the mainline external_dirs.")
+        return 0
+    slug = (a.slug or root.name).lower()
+    mode = "APPLY" if a.apply else "dry-run"
+    print(f"== templatize dedup ({mode}) :: {root} :: slug={slug} :: pack={pack} ==")
+    dedup(root, slug, pack, a.apply)
+    print("\nRESULT:", "applied where safe (BLOCKED runtimes untouched)." if a.apply
+          else "dry-run. --apply to reconcile. Bare-config runtimes are reported BLOCKED.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/templates/hermes-agent/scripts/migrate-profile-scoped-chat-secrets.py

@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+"""Move chat-platform credentials out of a fleet-wide dotenv file safely.
+
+The Hermes fleet shares provider credentials, but polling/socket credentials
+belong to one gateway profile.  This helper performs a dry-run by default and
+moves only named assignments without ever printing their values.
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import os
+import re
+import shutil
+import stat
+import tempfile
+from pathlib import Path
+
+
+DEFAULT_KEYS = ("SLACK_APP_TOKEN", "SLACK_BOT_TOKEN", "SLACK_ALLOWED_USERS")
+ASSIGNMENT = re.compile(r"^(?P<prefix>\s*)(?P<key>[A-Za-z_][A-Za-z0-9_]*)=(?P<value>.*)$")
+
+
+def _read(path: Path) -> list[str]:
+    return path.read_text(encoding="utf-8").splitlines(keepends=True)
+
+
+def _assignments(lines: list[str], keys: set[str]) -> dict[str, tuple[int, str]]:
+    found: dict[str, tuple[int, str]] = {}
+    for index, line in enumerate(lines):
+        match = ASSIGNMENT.match(line.rstrip("\n"))
+        if match and match.group("key") in keys:
+            found[match.group("key")] = (index, line)
+    return found
+
+
+def _same_file(left: Path, right: Path) -> bool:
+    try:
+        return left.resolve(strict=True) == right.resolve(strict=True)
+    except FileNotFoundError:
+        return left.resolve() == right.resolve()
+
+
+def _atomic_write(path: Path, lines: list[str]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, temporary = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.writelines(lines)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.chmod(temporary, stat.S_IRUSR | stat.S_IWUSR)
+        os.replace(temporary, path)
+    finally:
+        if os.path.exists(temporary):
+            os.unlink(temporary)
+
+
+def migrate(central: Path, target: Path, keys: tuple[str, ...], *, apply: bool) -> list[str]:
+    if not central.is_file():
+        raise ValueError(f"central env file does not exist: {central}")
+    if target.is_symlink():
+        raise ValueError(f"target env must be a profile-local file, not a symlink: {target}")
+    if _same_file(central, target):
+        raise ValueError("central and target env resolve to the same file")
+
+    selected = set(keys)
+    central_lines = _read(central)
+    target_lines = _read(target) if target.exists() else []
+    source_values = _assignments(central_lines, selected)
+    target_values = _assignments(target_lines, selected)
+
+    missing = [key for key in keys if key not in source_values]
+    if missing:
+        raise ValueError(f"central env is missing required keys: {', '.join(missing)}")
+
+    conflicts = [
+        key
+        for key in keys
+        if key in target_values and target_values[key][1].rstrip("\n") != source_values[key][1].rstrip("\n")
+    ]
+    if conflicts:
+        raise ValueError(f"target env already has different values for: {', '.join(conflicts)}")
+
+    if not apply:
+        return list(keys)
+
+    timestamp = dt.datetime.now(dt.timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+    central_backup = central.with_name(f"{central.name}.bak-{timestamp}-before-chat-scope")
+    shutil.copy2(central, central_backup)
+    os.chmod(central_backup, stat.S_IRUSR | stat.S_IWUSR)
+    if target.exists():
+        target_backup = target.with_name(f"{target.name}.bak-{timestamp}-before-chat-scope")
+        shutil.copy2(target, target_backup)
+        os.chmod(target_backup, stat.S_IRUSR | stat.S_IWUSR)
+
+    remove_indexes = {source_values[key][0] for key in keys}
+    next_central = [line for index, line in enumerate(central_lines) if index not in remove_indexes]
+    next_target = list(target_lines)
+    if next_target and not next_target[-1].endswith("\n"):
+        next_target[-1] += "\n"
+    if next_target and next_target[-1].strip():
+        next_target.append("\n")
+    next_target.append("# Profile-scoped chat gateway credentials.\n")
+    for key in keys:
+        if key not in target_values:
+            line = source_values[key][1]
+            next_target.append(line if line.endswith("\n") else f"{line}\n")
+
+    _atomic_write(target, next_target)
+    _atomic_write(central, next_central)
+    return list(keys)
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--central-env", type=Path, default=Path.home() / ".hermes" / ".env")
+    parser.add_argument("--target-env", type=Path, required=True)
+    parser.add_argument("--keys", nargs="+", default=list(DEFAULT_KEYS))
+    parser.add_argument("--apply", action="store_true", help="write the migration; default is dry-run")
+    return parser
+
+
+def main() -> int:
+    args = _parser().parse_args()
+    moved = migrate(args.central_env.expanduser(), args.target_env.expanduser(), tuple(args.keys), apply=args.apply)
+    action = "moved" if args.apply else "would move"
+    print(f"{action} {', '.join(moved)} from {args.central_env} to {args.target_env}")
+    if not args.apply:
+        print("dry-run only; rerun with --apply after reviewing the target paths")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())