@delorenj/pjangler 1.2.21 → 1.2.25

package/templates/hermes-agent/scripts/momo-unify-agent.py

@@ -0,0 +1,224 @@
+#!/usr/bin/env python3
+"""momo-unify-agent — apply the Momo/Hermes unification to a DEPLOYED agent.
+
+Per role dir (agents/hermes/<role>) it:
+  1. renders SOUL.md from momo/spec/momo-agent.spec.yaml × the agent's role.yaml
+     identity (charter, tone, prime directives + WIP lease, memory hygiene, doctrine),
+  2. honcho-neutralizes runtime/config.yaml (memory.provider='', disabled_toolsets
+     += memory) so memory is the shared Hindsight bank only,
+  3. installs the shared WIP=1 lease: copies .scripts/momo-wip-lock.py and wires
+     .scripts/heartbeat.sh (if present) to acquire/release it around the reconcile pass.
+
+Idempotent; dry-run by default (--apply mutates). This is the existing-fleet
+counterpart to the copier template (future agents get the same via provisioning).
+Needs PyYAML — run with ~/.hermes/hermes-agent/.venv/bin/python.
+
+Usage: momo-unify-agent.py --role-dir <agents/hermes/pm> [--apply] [--spec P]
+"""
+from __future__ import annotations
+import argparse, sys
+from pathlib import Path
+try:
+    import yaml
+except ImportError:
+    sys.exit("needs PyYAML — run with ~/.hermes/hermes-agent/.venv/bin/python")
+
+SPEC_DEFAULT = Path("~/code/33GOD/momo/spec/momo-agent.spec.yaml").expanduser()
+LOCK_SRC = Path("~/code/33GOD/momo/skill/scripts/momo-wip-lock.py").expanduser()
+
+SOUL_TMPL = """# {display_name}
+
+You are **{display_name}** — the Momo PM/EM orchestrator for the `{repo}`
+repository, running as its autonomous **Hermes carrier**. You are the autonomous
+twin of the human-drivable Momo; you share ONE board and ONE Hindsight bank with
+it, so stay attributable and never split-brain the state.
+
+<!-- Rendered from momo/spec/momo-agent.spec.yaml (role: {role}) × this repo's identity.
+     Regenerate via momo-unify-agent.py / the Hermes adapter, not by hand. -->
+
+## Identity
+
+| | |
+| --- | --- |
+| Agent ID | `{agent_id}` |
+| Repo | `{repo}` |
+| Role | `{role}` |
+| Telegram | {telegram} |
+| Purpose | {purpose} |
+
+## Scope
+
+You operate only within the working directory of `{repo}`. Your HERMES_HOME is the
+local runtime at `./runtime/`; Hermes loads its `config.yaml` directly.
+
+## Tone
+
+{tone}
+
+## Role-specific behavior
+
+{charter}
+
+Prime directives (non-negotiable):
+
+- **Never mutate code.** Every code change flows through a delegated worker.
+- **WIP = 1**, shared with the human-drivable Momo via the driver lease
+  (`.scripts/momo-wip-lock.py` → `runtime/wip-driver.lock`) — acquire before driving,
+  back off if Momo holds it fresh; never double-drive one board.
+- **Reviewer ≠ implementer** — independent adversarial review is the normal path.
+- **Evidence over status** — a board column is a claim; repo evidence is proof.
+- **Everything is an event** — record consequential calls as Bloodbank decision events.
+- **Anti-stall** — never park a pass on operator sign-off.
+
+Default execution: {default_execution}.
+
+## Memory hygiene
+
+Your durable memory is the shared **Hindsight bank `{repo}`** — one bank per PROJECT,
+shared with the human-drivable Momo twin. Honcho and the per-agent `runtime/memories/`
+store are **neutralized**: do not rely on `MEMORY.md`/`USER.md`. Retain with
+`hindsight memory retain {repo} "…" --context <cat>`; recall with
+`hindsight memory recall {repo} "…"`.
+
+## Doctrine
+
+Decide on the operator's behalf using **`~/code/33GOD/momo/PILLARS.md`** (canonical,
+priority-ordered). This soul **references** that file; it does not copy it. Cite the
+pillar(s) that drove a consequential call in its decision event.
+"""
+
+LEASE_BLOCK = '''# Coexistence WIP=1 lease (momo E2/S2.3): don't full-drive if the human-drivable
+# Momo holds it. A crashed holder's lease expires (ttl) so the board is never wedged.
+WIP_LOCK="$RUNTIME/wip-driver.lock"
+if ! python3 "$ROLE_DIR/.scripts/momo-wip-lock.py" acquire "$WIP_LOCK" "hermes:$AGENT_ID" --ttl 3600 >/dev/null 2>&1; then
+  printf '[heartbeat] WIP lease held by Momo — skipping full reconcile pass this tick\\n'
+  maybe_checkpoint
+  exit 0
+fi
+trap 'python3 "$ROLE_DIR/.scripts/momo-wip-lock.py" release "$WIP_LOCK" "hermes:$AGENT_ID" >/dev/null 2>&1 || true' EXIT
+
+'''
+
+SPAWN_ANCHOR = 'prompt="$(<"$PROMPT_FILE")"'
+
+
+def load_role(role_dir: Path):
+    """role.yaml at the role dir, else inside runtime/."""
+    for p in (role_dir / "role.yaml", role_dir / "runtime" / "role.yaml"):
+        if p.is_file():
+            return yaml.safe_load(p.read_text()) or {}
+    return None
+
+
+def identity(r: dict, spec: dict) -> dict:
+    repo = r.get("repo", "?"); role = r.get("role", "pm")
+    agent_id = r.get("agent_id", f"{repo}-{role}")
+    disp = r.get("display_name") or f"{repo.title()} {role.upper() if len(role) <= 3 else role.title()}"
+    tel = (r.get("telegram") or {}).get("bot_username", "") if isinstance(r.get("telegram"), dict) else ""
+    tone_key = r.get("soul_tone") or spec["personality"]["default_tone"]
+    rs = spec["roles"].get(role, spec["roles"]["pm"])
+    return {
+        "repo": repo, "role": role, "agent_id": agent_id, "display_name": disp,
+        "telegram": f"@{tel}" if tel else "—",
+        "purpose": rs["purpose_template"].format(repo=repo),
+        "tone": spec["personality"]["tones"].get(tone_key, spec["personality"]["tones"]["direct"]),
+        "charter": rs.get("charter", "").strip(),
+        "default_execution": rs.get("default_execution", "subagent-driven-development (WIP=1, spec + quality gates)"),
+    }
+
+
+def neutralize_config(cfg: Path, apply: bool) -> str:
+    if not cfg.exists():
+        return "no config.yaml (skip honcho)"
+    base = yaml.safe_load(cfg.read_text()) or {}
+    already = (isinstance(base.get("memory"), dict) and base["memory"].get("provider") == ""
+               and "memory" in (base.get("agent", {}) or {}).get("disabled_toolsets", []))
+    if already:
+        return "honcho: already neutralized"
+    overlay = {"memory": {"provider": "", "memory_enabled": False, "user_profile_enabled": False},
+               "agent": {"disabled_toolsets": ["memory"]}}
+
+    def merge(b, o):
+        for k, v in o.items():
+            if isinstance(b.get(k), dict) and isinstance(v, dict):
+                merge(b[k], v)
+            else:
+                b[k] = v
+    merge(base, overlay)
+    if apply:
+        cfg.with_suffix(cfg.suffix + ".pre-unify.bak").write_text(cfg.read_text()) if not cfg.with_suffix(cfg.suffix + ".pre-unify.bak").exists() else None
+        yaml.safe_dump(base, cfg.open("w"), sort_keys=False)
+    return "honcho: neutralized"
+
+
+def install_lease(role_dir: Path, apply: bool) -> str:
+    scripts = role_dir / ".scripts"
+    msgs = []
+    if not scripts.is_dir():
+        return "no .scripts (skip lease)"
+    dst = scripts / "momo-wip-lock.py"
+    if not dst.exists() or dst.read_bytes() != LOCK_SRC.read_bytes():
+        if apply:
+            dst.write_bytes(LOCK_SRC.read_bytes()); dst.chmod(0o755)
+        msgs.append("lock helper installed")
+    else:
+        msgs.append("lock helper present")
+    hb = scripts / "heartbeat.sh"
+    if not hb.is_file():
+        msgs.append("no heartbeat.sh (reactive agent — lease unused)")
+        return "; ".join(msgs)
+    txt = hb.read_text()
+    if "momo-wip-lock.py" in txt:
+        msgs.append("heartbeat already lease-wired")
+    elif SPAWN_ANCHOR in txt:
+        if apply:
+            hb.write_text(txt.replace(SPAWN_ANCHOR, LEASE_BLOCK + SPAWN_ANCHOR, 1))
+        msgs.append("heartbeat lease-wired")
+    else:
+        msgs.append("WARN: heartbeat spawn anchor not found — wire manually")
+    return "; ".join(msgs)
+
+
+def unify(role_dir: Path, spec: dict, apply: bool, repo_override: str | None = None) -> None:
+    r = load_role(role_dir)
+    if r is None:
+        if not repo_override:
+            print(f"  SKIP: no role.yaml at {role_dir} (bare-layout agent — pass --repo to unify it)"); return
+        r = {"repo": repo_override, "role": "pm", "agent_id": f"{repo_override}-pm"}
+        print(f"  (synthesized identity for bare agent: {r['agent_id']})")
+    idt = identity(r, spec)
+    render = SOUL_TMPL.format(**idt)
+    # Write BOTH the role-dir source AND the LIVE runtime/SOUL.md that hermes
+    # actually loads (HERMES_HOME=runtime). Provisioning copies source->runtime,
+    # but for an already-deployed agent we must update the live copy directly.
+    for label, sp in (("src ", role_dir / "SOUL.md"),
+                      ("live", role_dir / "runtime" / "SOUL.md")):
+        if not sp.parent.exists():
+            continue
+        cur = sp.read_text() if sp.is_file() else ""
+        if cur.strip() == render.strip():
+            print(f"  SOUL[{label}]: already unified ({idt['agent_id']})")
+        else:
+            if apply:
+                sp.write_text(render)
+            print(f"  SOUL[{label}]: {'written' if apply else 'would write'} ({idt['agent_id']})")
+    print("  " + neutralize_config(role_dir / "runtime" / "config.yaml", apply))
+    print("  " + install_lease(role_dir, apply))
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--role-dir", required=True)
+    ap.add_argument("--spec", default=str(SPEC_DEFAULT))
+    ap.add_argument("--repo", default=None, help="synthesize identity for a bare agent with no role.yaml")
+    ap.add_argument("--apply", action="store_true")
+    a = ap.parse_args()
+    spec = yaml.safe_load(Path(a.spec).read_text())
+    role_dir = Path(a.role_dir).expanduser().resolve()
+    print(f"== unify ({'APPLY' if a.apply else 'dry-run'}) :: {role_dir}")
+    unify(role_dir, spec, a.apply, a.repo)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/templates/hermes-agent/scripts/repair-runtime-checkpoint.sh

@@ -1,122 +1,10 @@
 #!/usr/bin/env bash
-# Repair a failing runtime-checkpoint service caused by an UNPOPULATED runtime
-# submodule (`git add -A` -> "fatal: in unpopulated submodule" -> exit 128).
-#
-# Dry-run by default (diagnose + print plan). Pass --apply to mutate. The mutate
-# path only ever runs `git init` / `fetch` / `reset --mixed` / `.gitignore` edits
-# / `rm --cached` — it NEVER rewrites working-tree files, so live runtime state
-# (incl. a large state.db) is preserved. It does NOT commit or push; run the
-# role's checkpoint.sh afterward.
-#
-# Docs: docs/runbooks/runtime-checkpoint-repair.md
-# Usage: repair-runtime-checkpoint.sh [--apply] <runtime-dir>
+# Retained only so older automation fails with a clear compatibility message.
+# The former checkpoint repair belongs to a retired persistence design.
 set -euo pipefail
 
-APPLY=0; RT=""
-for a in "$@"; do
-  case "$a" in
-    --apply) APPLY=1 ;;
-    -h|--help) sed -n '2,12p' "$0"; exit 0 ;;
-    *) RT="$a" ;;
-  esac
-done
-
-die(){ printf 'ERROR: %s\n' "$*" >&2; exit 1; }
-note(){ printf '  %s\n' "$*"; }
-
-[ -n "$RT" ] || die "usage: $0 [--apply] <runtime-dir>  (e.g. agents/hermes/pm/runtime)"
-[ -d "$RT" ] || die "no such directory: $RT"
-
-PARENT="$(git -C "$RT" rev-parse --show-superproject-working-tree 2>/dev/null || true)"
-[ -n "$PARENT" ] || PARENT="$(git -C "$RT" rev-parse --show-toplevel 2>/dev/null || true)"
-[ -n "$PARENT" ] || die "$RT is not inside a git repository"
-RTABS="$(cd "$RT" && pwd)"
-RELPATH="${RTABS#"$PARENT"/}"
-
-MODE="dry-run"; [ "$APPLY" -eq 1 ] && MODE="APPLY"
-printf '== runtime-checkpoint repair (%s) ==\n' "$MODE"
-note "runtime: $RTABS"
-note "parent:  $PARENT"
-note "subpath: $RELPATH"
-
-if git -C "$RTABS" rev-parse --git-dir >/dev/null 2>&1 && [ -e "$RTABS/.git" ]; then
-  POPULATED=1; note "state:   runtime already has its own .git (re-attach not needed)"
-else
-  POPULATED=0; note "state:   UNPOPULATED submodule (no .git) — re-attach required"
-fi
-
-URL="$(git -C "$PARENT" config -f "$PARENT/.gitmodules" --get "submodule.$RELPATH.url" 2>/dev/null || true)"
-[ -n "$URL" ] || die "no .gitmodules url for submodule '$RELPATH'"
-note "remote:  $URL"
-GIT_SSH_COMMAND='ssh -o BatchMode=yes -o ConnectTimeout=15' git ls-remote "$URL" >/dev/null 2>&1 \
-  || die "remote not reachable (check SSH/network): $URL"
-note "remote reachable: yes"
-
-IGNORE_MARK='NOT part of the durable brain backup'
-IGNORE_BLOCK='# Runtime working state — NOT part of the durable brain backup.
-*.db
-*.db-wal
-*.db-shm
-*.sqlite
-*.sqlite3
-*.lock
-.update_check
-lsp/
-checkpoints/
-sessions/
-cron/
-*_cache.json'
-
-if [ "$APPLY" -eq 0 ]; then
-  cat <<EOF
-
-PLAN (dry-run; re-run with --apply):
-  cd $RELPATH
-  $( [ "$POPULATED" -eq 0 ] && echo "git init -q; git symbolic-ref HEAD refs/heads/main; git remote add origin <url>; git fetch origin; git reset --mixed origin/main" || echo "(already populated — skip re-init)" )
-  git lfs install --local
-  git checkout origin/main -- .gitattributes README.md   # restore tracked config
-  ensure runtime/.gitignore has the volatile-state block
-  git rm -r --cached --ignore-unmatch state.db state.db-wal state.db-shm cron
-  # safety gate: git add -A --dry-run must show no >1MB blobs / secrets / volatile paths
-  then: run the role's checkpoint.sh and (re)start the systemd checkpoint unit.
-EOF
-  exit 0
-fi
-
-cd "$RTABS"
-if [ "$POPULATED" -eq 0 ]; then
-  git init -q
-  git symbolic-ref HEAD refs/heads/main
-  git remote add origin "$URL" 2>/dev/null || git remote set-url origin "$URL"
-  GIT_SSH_COMMAND='ssh -o BatchMode=yes -o ConnectTimeout=20' git fetch -q origin
-  git reset --mixed -q origin/main
-  git branch --set-upstream-to=origin/main main >/dev/null 2>&1 || true
-  note "re-attached HEAD -> $(git rev-parse --short HEAD) on $(git rev-parse --abbrev-ref HEAD)"
-fi
-git lfs install --local >/dev/null 2>&1 || true
-git checkout origin/main -- .gitattributes README.md 2>/dev/null || true
-
-touch .gitignore
-if grep -q "$IGNORE_MARK" .gitignore 2>/dev/null; then
-  note ".gitignore already has the volatile-state block"
-else
-  printf '\n%s\n' "$IGNORE_BLOCK" >> .gitignore
-  note "appended volatile-state ignore block to .gitignore"
-fi
-git rm -r --cached --quiet --ignore-unmatch state.db state.db-wal state.db-shm cron 2>/dev/null || true
-
-# ---- mandatory safety gate ----
-staged(){ git add -A --dry-run 2>/dev/null | sed -E "s/^[a-z]+ '?//; s/'?$//"; }
-BIG="$(staged | while read -r f; do [ -f "$f" ] && s=$(stat -c%s "$f" 2>/dev/null) && [ "${s:-0}" -gt 1048576 ] && printf '%s (%sMB)\n' "$f" "$((s/1048576))"; done)"
-SECRETS="$(staged | grep -iE '(^|/)(\.env|\.env\.|auth\.json|auth\.lock)([./]|$)|\.(pem|key)$' || true)"
-VOL="$(staged | grep -E '(^|/)(state\.db|lsp|sessions|checkpoints)(/|$)' || true)"
-if [ -n "$BIG$SECRETS$VOL" ]; then
-  printf 'SAFETY GATE FAILED — fix .gitignore before committing.\n' >&2
-  [ -n "$BIG" ]     && printf '  >1MB blobs:\n%s\n' "$BIG" >&2
-  [ -n "$SECRETS" ] && printf '  secrets:\n%s\n' "$SECRETS" >&2
-  [ -n "$VOL" ]     && printf '  volatile state:\n%s\n' "$VOL" >&2
-  exit 2
-fi
-note "safety gate passed: staged set is brain-only."
-note "DONE. Now run the role's checkpoint.sh, then:"
-note "  systemctl --user reset-failed <checkpoint-service> && systemctl --user start <checkpoint-service>"
+printf '%s\n' \
+  'ERROR: repair-runtime-checkpoint.sh is retired and intentionally non-operational.' \
+  'Current Hermes runtimes are ignored local state; this command changed nothing.' \
+  'See docs/operations.md for backup, restore, and retention policy.' >&2
+exit 64

package/templates/hermes-agent/template/.gitignore.jinja

@@ -1,6 +1,9 @@
 # Per-role ignores in agents/hermes/{{ role }}/
 
-# The runtime submodule manages its own ignores (.env, auth.json, etc.).
-# We just ignore the provisioning log so it doesn't end up in the project repo.
+# The local runtime contains mutable agent state and secrets. It is never a
+# project submodule or publishable project content.
+runtime/
+
+# Provisioning logs are host-local as well.
 .scripts/.provision.log
 .scripts/.last-run

package/templates/hermes-agent/template/.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/template/.scripts/00-banner.sh

@@ -13,7 +13,7 @@ cat >&2 <<EOF
 │  display     $DISPLAY_NAME
 │  telegram    @$BOT_HANDLE   (one bot per agent)
 │  plane       $PLANE_WORKSPACE workspace
-│  runtime     gh:$RUNTIME_REPO   (auto-checkpointed)
+│  runtime     $ROLE_DIR/runtime   (pure-local, ignored)
 │  profile     ~/.hermes/profiles/$PROFILE_NAME
 ╰────────────────────────────────────────────────────────────────────────╯
 

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

@@ -23,6 +23,9 @@ else
 [fleet]
 hermes_bin = "~/.hermes/hermes-agent/.venv/bin/hermes"
 hermes_repo = "~/.hermes/hermes-agent"
+hermes_git_url = "https://github.com/delorenj/hermes-agent.git"
+hermes_git_ref = "feature/PJAN-19-routing-publication"
+hermes_git_sha = "113e1b182b6d72a7dd02a191f134a41668ceaf0e"
 fleet_env = "~/.hermes/fleet.env"
 registry_file = "~/.hermes/agents-registry.yaml"
 canonical_skills_dir = "/home/delorenj/.agents/skills"

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

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # Stage the per-agent runtime config/secrets via a TRANSIENT Hermes profile.
-# HERMES_HOME is the ./runtime submodule; this profile dir is a staging area
+# HERMES_HOME is the ignored ./runtime directory; this profile dir is a staging area
 # (cred-stripped .env + SOUL) that 20-runtime-repo.sh folds into the runtime and
 # then replaces with a symlink ~/.hermes/profiles/<name> -> ./runtime. That
 # symlink is load-bearing: hermes resolves `--profile <name>` invocations
@@ -57,6 +57,17 @@ rm -f "$PROFILE_HOME/gateway.pid" "$PROFILE_HOME/gateway_state.json" \
 # never borrow the parent's.
 PROFILE_ENV="$PROFILE_HOME/.env"
 if [[ -f "$PROFILE_ENV" ]]; then
+  # Some Hermes versions implement `profile create --clone` by symlinking the
+  # cloned .env back to the default profile.  Never sanitize through that
+  # symlink: doing so would delete the operator's fleet-wide provider secrets.
+  # Break only the .env link into a private, mode-0600 copy first.
+  if [[ -L "$PROFILE_ENV" ]]; then
+    log "    detaching cloned .env symlink before profile-local sanitization"
+    PROFILE_ENV_COPY="$PROFILE_HOME/.env.profile-local.$$"
+    cp -L "$PROFILE_ENV" "$PROFILE_ENV_COPY"
+    chmod 600 "$PROFILE_ENV_COPY"
+    mv -fT "$PROFILE_ENV_COPY" "$PROFILE_ENV"
+  fi
   log "    stripping inherited platform credentials from profile .env"
   python3 - "$PROFILE_ENV" <<'PYEOF'
 import re, sys, pathlib