@delorenj/pjangler 1.2.19 → 1.2.25

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

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())