@delorenj/pjangler 1.2.33 → 1.3.7

package/templates/hermes-agent/template/.scripts/lifecycle.sh

@@ -0,0 +1,126 @@
+#!/usr/bin/env bash
+# Lifecycle helper — resolves the CANONICAL Krebs ticket lifecycle for this role.
+#
+# The state machine is NOT defined here. It lives in
+# krebs/spec/lifecycle.v1.yaml, which is the contract between ticket providers
+# and fleet orchestrators. This script is a reader: it answers "which tp band
+# does phase X map to" and "is this ticket stale" without any repo growing its
+# own private copy of the phase list. A second copy is how a PM ends up
+# transitioning against labels the board no longer uses.
+#
+# Provider LABELS are deliberately absent — those belong to the tp adapter's
+# normalized-state map (.scripts/providers/<provider>.sh). This layer speaks
+# only phases and the five tp bands.
+#
+# Usage:
+#   lifecycle.sh phases                 list every phase with band + staleness
+#   lifecycle.sh band <phase>           print the tp band for a phase
+#   lifecycle.sh staleness <phase>      print staleness minutes ("-" if none)
+#   lifecycle.sh is-terminal <phase>    exit 0 when the phase is terminal
+#   lifecycle.sh stale <phase> <iso8601>  exit 0 when that timestamp is stale
+#   lifecycle.sh spec                   print the resolved spec path
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Resolution order: explicit override, the 33GOD checkout, then a sibling walk
+# for hosts that keep the platform elsewhere.
+resolve_spec() {
+  if [ -n "${KREBS_LIFECYCLE_SPEC:-}" ] && [ -r "$KREBS_LIFECYCLE_SPEC" ]; then
+    printf '%s\n' "$KREBS_LIFECYCLE_SPEC"; return 0
+  fi
+  local candidates=(
+    "$HOME/code/33GOD/krebs/spec/lifecycle.v1.yaml"
+    "$SCRIPT_DIR/../../../../krebs/spec/lifecycle.v1.yaml"
+    "$SCRIPT_DIR/../../../../../krebs/spec/lifecycle.v1.yaml"
+  )
+  local c
+  for c in "${candidates[@]}"; do
+    [ -r "$c" ] && { printf '%s\n' "$c"; return 0; }
+  done
+  return 1
+}
+
+SPEC="$(resolve_spec || true)"
+
+need_spec() {
+  if [ -z "$SPEC" ]; then
+    echo "lifecycle: canonical spec not found (set KREBS_LIFECYCLE_SPEC)" >&2
+    echo "lifecycle: expected krebs/spec/lifecycle.v1.yaml in the 33GOD checkout" >&2
+    exit 2
+  fi
+  if ! command -v python3 >/dev/null 2>&1; then
+    echo "lifecycle: python3 required to read $SPEC" >&2
+    exit 2
+  fi
+}
+
+# One python entrypoint for every query keeps YAML parsing in exactly one place.
+query() {
+  need_spec
+  python3 - "$SPEC" "$@" <<'PY'
+import sys
+try:
+    import yaml
+except ImportError:
+    sys.exit("lifecycle: PyYAML required to read the lifecycle spec")
+
+spec_path, op = sys.argv[1], sys.argv[2]
+arg = sys.argv[3] if len(sys.argv) > 3 else None
+arg2 = sys.argv[4] if len(sys.argv) > 4 else None
+
+spec = yaml.safe_load(open(spec_path)) or {}
+states = {s["phase"]: s for s in (spec.get("states") or []) if s.get("phase")}
+if not states:
+    sys.exit(f"lifecycle: no states in {spec_path}")
+
+def need_phase(p):
+    if p not in states:
+        sys.exit(f"lifecycle: unknown phase {p!r}; known: {', '.join(states)}")
+    return states[p]
+
+if op == "phases":
+    print(f"{'phase':<14} {'tp_band':<12} {'terminal':<9} stale_after")
+    for name, s in states.items():
+        stale = s.get("staleness_minutes")
+        print(f"{name:<14} {str(s.get('tp_band')):<12} "
+              f"{str(bool(s.get('terminal'))).lower():<9} "
+              f"{(str(stale) + 'm') if stale else '-'}")
+elif op == "band":
+    print(need_phase(arg)["tp_band"])
+elif op == "staleness":
+    print(need_phase(arg).get("staleness_minutes") or "-")
+elif op == "is-terminal":
+    sys.exit(0 if need_phase(arg).get("terminal") else 1)
+elif op == "stale":
+    from datetime import datetime, timezone
+    mins = need_phase(arg).get("staleness_minutes")
+    if not mins:
+        sys.exit(1)  # phase has no staleness budget -> never stale
+    try:
+        ts = datetime.fromisoformat(arg2.replace("Z", "+00:00"))
+    except Exception:
+        sys.exit(f"lifecycle: unparseable timestamp {arg2!r} (want ISO 8601)")
+    if ts.tzinfo is None:
+        ts = ts.replace(tzinfo=timezone.utc)
+    age = (datetime.now(timezone.utc) - ts).total_seconds() / 60
+    sys.exit(0 if age > mins else 1)
+else:
+    sys.exit(f"lifecycle: unknown operation {op!r}")
+PY
+}
+
+case "${1:-phases}" in
+  phases)      query phases ;;
+  band)        query band "${2:?phase required}" ;;
+  staleness)   query staleness "${2:?phase required}" ;;
+  is-terminal) query is-terminal "${2:?phase required}" ;;
+  stale)       query stale "${2:?phase required}" "${3:?iso8601 timestamp required}" ;;
+  spec)        need_spec; printf '%s\n' "$SPEC" ;;
+  --help|-h|help)
+    sed -n '2,20p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//' ;;
+  *)
+    echo "lifecycle: unknown operation ${1}" >&2
+    echo "try: phases | band <phase> | staleness <phase> | is-terminal <phase> | stale <phase> <ts> | spec" >&2
+    exit 2 ;;
+esac

package/templates/hermes-agent/template/.scripts/providers/plane.sh

@@ -22,10 +22,6 @@ ROLE_YAML="$ROLE_DIR/role.yaml"
 BASE="${PLANE_BASE:-https://plane.delo.sh}"
 
 FLEET_ENV="${HERMES_FLEET_ENV:-$HOME/.hermes/fleet.env}"
-if [ -f "$FLEET_ENV" ]; then
-  # shellcheck disable=SC1090
-  . "$FLEET_ENV"
-fi
 
 die() { echo "plane: $*" >&2; exit 1; }
 need_key() { [ -n "${PLANE_API_KEY:-}" ] || die "PLANE_API_KEY is not set"; }
@@ -36,6 +32,33 @@ workspace_key() {
   printf 'PLANE_%s_API_KEY' "$key"
 }
 
+# dotenv_value FILE KEY — read one exact dotenv assignment as inert data.
+# Never source the shared fleet file: it may contain unrelated command
+# substitutions or credential helpers that this provider must not execute.
+dotenv_value() {
+  python3 - "$1" "$2" <<'PY'
+import pathlib, sys
+
+path = pathlib.Path(sys.argv[1])
+key = sys.argv[2]
+value = ""
+for raw in path.read_text(encoding="utf-8").splitlines():
+    line = raw.strip()
+    if not line or line.startswith("#"):
+        continue
+    if line.startswith("export "):
+        line = line[7:].lstrip()
+    name, sep, candidate = line.partition("=")
+    if sep and name.strip() == key:
+        candidate = candidate.strip()
+        if len(candidate) >= 2 and candidate[0] == candidate[-1] and candidate[0] in "'\"":
+            candidate = candidate[1:-1]
+        value = candidate
+        break
+print(value, end="")
+PY
+}
+
 tp_cfg() {
   [ -f "$ROLE_YAML" ] || return 0
   python3 - "$ROLE_YAML" "$1" <<'PY'
@@ -76,7 +99,10 @@ API="$BASE/api/v1/workspaces/$WS"
 
 if [ -z "${PLANE_API_KEY:-}" ]; then
   KEY="$(workspace_key "$WS")"
-  eval "PLANE_API_KEY=\${$KEY:-}"
+  PLANE_API_KEY="$(printenv "$KEY" 2>/dev/null || true)"
+  if [ -z "${PLANE_API_KEY:-}" ] && [ -f "$FLEET_ENV" ]; then
+    PLANE_API_KEY="$(dotenv_value "$FLEET_ENV" "$KEY")"
+  fi
   export PLANE_API_KEY
 fi
 

package/templates/hermes-agent/template/.scripts/secret-scan.py

@@ -8,45 +8,111 @@ import re
 from pathlib import Path
 
 KEY_VALUE = re.compile(
-    r"(?im)^\s*[\"']?(?:api[_-]?key|token|secret|password|authorization|cookie|client[_-]?secret|private[_-]?key)[\"']?\s*[:=]\s*[\"']?([^\s\"'#][^\r\n#]*)"
+    r"(?im)^\s*[\"']?(?P<key>api[_-]?key|token|secret|password|authorization|cookie|client[_-]?secret|private[_-]?key)[\"']?\s*[:=]\s*(?P<value>[^\r\n#]*)"
 )
 TOKEN = re.compile(
     r"(?:sk-[A-Za-z0-9_-]{12,}|gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|xox[baprs]-[A-Za-z0-9-]{10,}|AKIA[0-9A-Z]{16}|tvly-[A-Za-z0-9_-]{10,}|fc-[A-Za-z0-9_-]{10,}|[0-9]{6,}:[A-Za-z0-9_-]{20,})"
 )
 PRIVATE_KEY = re.compile(r"-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----")
-SAFE_VALUES = {"openrouter", "openai", "anthropic", "auto", "none", "null", "false", "true"}
-SKIP_PARTS = {".git", "__pycache__"}
+SAFE_VALUES = {
+    "openrouter",
+    "openai",
+    "anthropic",
+    "auto",
+    "none",
+    "null",
+    "false",
+    "true",
+}
+SAFE_PREFIXES = ("${", "$", "op://", "env:", "[REDACTED]", "{{", "{%")
+COMPUTED_VALUE = re.compile(r"^[A-Za-z_][A-Za-z0-9_.]*\s*(?:\(|\[)")
+INTERPOLATED_VALUE = re.compile(
+    r"(?:\$\{[A-Za-z_][A-Za-z0-9_]*[^}]*\}|\$[A-Za-z_][A-Za-z0-9_]*|\{[A-Za-z_][A-Za-z0-9_.]*\})"
+)
+ENV_ASSIGNMENT = re.compile(
+    r"(?m)^\s*(?:export\s+)?(?P<key>[A-Za-z_][A-Za-z0-9_]*)\s*=\s*(?P<value>[^\r\n#]*)"
+)
+SENSITIVE_ENV_KEY = re.compile(
+    r"(?i)(?:^|_)(?:api_key|token|secret|password|authorization|cookie|client_secret|private_key)(?:_|$)"
+)
+ALLOWED_ENV_FILES = {".env.example", ".env.op"}
+SKIP_PARTS = {
+    ".cache",
+    ".direnv",
+    ".eggs",
+    ".git",
+    ".mypy_cache",
+    ".nox",
+    ".npm",
+    ".pnpm-store",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".tox",
+    ".turbo",
+    ".uv-cache",
+    ".venv",
+    ".yarn",
+    "__pycache__",
+    "dist-packages",
+    "node_modules",
+    "site-packages",
+    "venv",
+}
+
+
+def safe_assignment(raw_value: str) -> bool:
+    """Return true only for an explicit reference, sentinel, or computation."""
+
+    value = raw_value.strip().rstrip(",").strip().strip("\"'")
+    if not value or value.lower() in SAFE_VALUES:
+        return True
+    if value.startswith(SAFE_PREFIXES) or value.endswith("_ENV"):
+        return True
+    if INTERPOLATED_VALUE.search(value):
+        return True
+    # Source code commonly binds credentials from a runtime provider. A bare
+    # literal does not have a call/index boundary and remains fail-closed.
+    return COMPUTED_VALUE.match(value) is not None
+
+
+def safe_env_reference(raw_value: str) -> bool:
+    """Keep a tracked .env.op declarative: sensitive values stay references."""
+
+    value = raw_value.strip().rstrip(",").strip().strip("\"'")
+    return not value or value.startswith(SAFE_PREFIXES)
 
 
 def findings(root: Path) -> list[str]:
     result: list[str] = []
     for path in root.rglob("*"):
-        if not path.is_file() or any(part in SKIP_PARTS for part in path.parts):
+        relative = path.relative_to(root)
+        if not path.is_file() or any(part in SKIP_PARTS for part in relative.parts):
             continue
         if path.name == "secret-scan.py":
             continue
-        if path.name.startswith(".env") and path.name != ".env.example":
-            result.append(f"forbidden secret file: {path.relative_to(root)}")
+        if path.name.startswith(".env") and path.name not in ALLOWED_ENV_FILES:
+            result.append(f"forbidden secret file: {relative}")
             continue
         if path.name in {"auth.json", "auth.lock"} or path.suffix in {".pem", ".key"}:
-            result.append(f"forbidden credential file: {path.relative_to(root)}")
+            result.append(f"forbidden credential file: {relative}")
             continue
         try:
             text = path.read_text(encoding="utf-8")
         except (UnicodeDecodeError, OSError):
             continue
         if TOKEN.search(text) or PRIVATE_KEY.search(text):
-            result.append(f"credential token pattern: {path.relative_to(root)}")
+            result.append(f"credential token pattern: {relative}")
+        if path.name == ".env.op":
+            for match in ENV_ASSIGNMENT.finditer(text):
+                if SENSITIVE_ENV_KEY.search(
+                    match.group("key")
+                ) and not safe_env_reference(match.group("value")):
+                    result.append(f"literal credential assignment: {relative}")
+                    break
         for match in KEY_VALUE.finditer(text):
-            value = match.group(1).strip().strip("\"'").rstrip(",")
-            if (
-                not value
-                or value.lower() in SAFE_VALUES
-                or value.startswith(("${", "$", "op://", "env:", "[REDACTED]"))
-                or value.endswith("_ENV")
-            ):
+            if safe_assignment(match.group("value")):
                 continue
-            result.append(f"literal credential assignment: {path.relative_to(root)}")
+            result.append(f"literal credential assignment: {relative}")
             break
     return sorted(set(result))
 

package/templates/hermes-agent/template/SOUL.md.jinja

@@ -15,10 +15,10 @@ You are **{{ display_name }}** — a Hermes agent provisioned to work inside the
 
 ## Scope
 
-Your HERMES_HOME is the local runtime at `./runtime/`; Hermes loads its
-`config.yaml` directly. Secrets, SOUL, skills, sessions, and gateway state live
-local to that runtime (pure-local state; durable memory is the shared Hindsight
-bank — see Memory hygiene).
+Your HERMES_HOME is the real named profile under `~/.hermes/profiles/`. Shared
+config/auth/skills link to fleet truth; your SOUL, sessions, memory, and other
+owned state link into the ignored local `./runtime/`. Only PJangler may repair
+that wiring (`pj migrate hermes.runtime-singleton`).
 
 ## Tone
 
@@ -147,14 +147,50 @@ declared` event so the fleet knows what to route to you.
   via Cloudflare Tunnel), `localhost` for same-host, Docker network service
   names for container-to-container, Tailscale for private machine-to-machine.
 
-## Memory hygiene
-
-Your durable memory is the shared **Hindsight bank `{{ target_repo }}`** — one
-bank per PROJECT, shared with the human-drivable Momo twin. Honcho and the
-per-agent `runtime/memories/` store are **neutralized** (see `config.yaml`
-`memory.provider: ""`): do not rely on `MEMORY.md`/`USER.md`. Retain with
-`hindsight memory retain {{ target_repo }} "…" --context <cat>`; recall with
-`hindsight memory recall {{ target_repo }} "…"`.
+## Memory: two namespaces, two questions
+
+You have **two** memory stores. They do not compete — they answer opposite
+questions, and you are expected to use both and play them off each other.
+
+| | **Identity memory** | **Project memory** |
+| --- | --- | --- |
+| Bank | `agent-{{ agent_id }}` | `{{ target_repo }}` |
+| Anchored to | **who you are** | **which repo** |
+| Follows you across repos | yes | no |
+| Written by | the runtime, automatically | you, explicitly |
+| Read by | you alone | every agent on this repo |
+| Answers | "which projects have I worked on, and how do I work?" | "what is true about this repo, and which agent learned it?" |
+
+**Identity memory** is wired to the Hermes memory provider
+(`memory.bank_id_template: agent-{profile}`), so it accrues on its own from
+your turns. It is keyed to your profile name, **never** to a repo or working
+directory — change directories, change projects, it follows you. Treat it as
+self-referential: your capabilities, your recurring mistakes and the
+corrections that stuck, operator preferences you have learned, and the shape of
+the projects you have touched. Do not put repo facts here; they would be
+invisible to every other agent working that repo.
+
+**Project memory** is the shared, temporally-sequenced record of a repository,
+queried by many agents including the human-drivable Momo twin. Write it
+explicitly, and always carry provenance — name yourself in the content so a
+later reader can answer *which agent experienced this*:
+
+```bash
+hindsight memory retain {{ target_repo }} "{{ agent_id }}: <fact>" --context <cat>
+hindsight memory recall {{ target_repo }} "<question>"
+```
+
+**The synergy.** Before starting work in a repo you have not touched lately,
+recall from BOTH: project memory tells you the state of the code; identity
+memory tells you how *you* previously failed or succeeded here and what the
+operator asked you to do differently. When you learn something, route it by
+asking one question — *would another agent on this repo need this?* If yes it
+is project memory; if it is only true of you, it is identity memory. A fact
+about the operator's preferences is identity memory; a fact about the build is
+project memory.
+
+`MEMORY.md` / `USER.md` are live again and are fed by the provider — they are a
+projection of identity memory, not a separate store to hand-maintain.
 
 ## Doctrine
 

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

@@ -1,17 +1,46 @@
 #!/usr/bin/env bash
-# Launcher for {{ agent_id }}. Resolves HERMES_HOME to the local runtime
+# Launcher for {{ agent_id }}. Resolves HERMES_HOME to the agent's NAMED PROFILE
 # and execs the shared fleet Hermes binary configured in ~/.hermes/fleet.env.
 
 set -euo pipefail
 
 ROLE_DIR="$(cd "$(dirname "$0")" && pwd)"
-HERMES_HOME="$ROLE_DIR/runtime"
+RUNTIME_HOME="$ROLE_DIR/runtime"
 
 FLEET_ENV="${HERMES_FLEET_ENV:-$HOME/.hermes/fleet.env}"
-if [[ -f "$FLEET_ENV" ]]; then
-  # shellcheck disable=SC1090
-  source "$FLEET_ENV"
+FLEET_ENV_LIBRARY="$ROLE_DIR/.scripts/lib/fleet-env.sh"
+FLEET_ENV_PARSER="$ROLE_DIR/.scripts/lib/parse-fleet-env.py"
+if [[ ! -f "$FLEET_ENV_LIBRARY" || -L "$FLEET_ENV_LIBRARY" ]]; then
+  echo "hermes: trusted fleet environment loader unavailable" >&2
+  exit 1
+fi
+# shellcheck source=.scripts/lib/fleet-env.sh
+builtin source "$FLEET_ENV_LIBRARY"
+load_fleet_environment "$FLEET_ENV" "$FLEET_ENV_PARSER"
+
+FLEET_HOME="${HERMES_FLEET_HOME:-$HOME/.hermes}"
+PROFILE_NAME="${HERMES_PROFILE_NAME:-{{ agent_id }}}"
+
+# Singleton-runtime contract: HERMES_HOME MUST be the named profile dir, never
+# the raw runtime path. Hermes derives the profile identity from the UNRESOLVED
+# HERMES_HOME path; any HERMES_HOME that is neither under ~/.hermes nor a child
+# of a "profiles" dir makes get_active_profile_name() report "default" and
+# _global_auth_file_path() return None — silently disabling shared fleet auth
+# and giving the agent a divergent config.yaml. The profile dir is a REAL dir
+# whose shared entries (.env, skills) symlink to the fleet root and whose owned
+# entries (memories, sessions, state.db, ...) symlink into $RUNTIME_HOME.
+#
+# config.yaml is NOT symlinked — it is GENERATED as
+# deep_merge(fleet config.yaml, <profile>/config.delta.yaml). Symlinking it
+# detached the profile on the first in-agent write (Hermes' atomic write does
+# os.replace, which swaps the symlink for a regular file) and left no way to
+# override anything. Edit config.delta.yaml, then render.
+# Provision it with: pj migrate hermes.runtime-singleton
+HERMES_HOME="$FLEET_HOME/profiles/$PROFILE_NAME"
+if ! REPO_ROOT="$(git -C "$ROLE_DIR" rev-parse --show-toplevel 2>/dev/null)"; then
+  REPO_ROOT="$ROLE_DIR"
 fi
+
 # Never pass an identity-bearing chat credential from shared fleet state into
 # a profile process. Hermes loads the profile's own runtime/.env itself.
 unset TELEGRAM_BOT_TOKEN SLACK_BOT_TOKEN SLACK_APP_TOKEN
@@ -47,16 +76,28 @@ HERMES_BIN="${HERMES_BIN:-${HERMES_FLEET_BIN:-}}"
 if [[ -z "$HERMES_BIN" ]]; then
   HERMES_BIN="$(config_get fleet.hermes_bin "")"
 fi
-HERMES_BIN="${HERMES_BIN:-$HOME/.hermes/hermes-agent/.venv/bin/hermes}"
-HERMES_OAUTH_FILE="${HERMES_OAUTH_FILE:-${HERMES_FLEET_OAUTH_FILE:-$(config_get fleet.oauth_file "$HOME/.hermes/auth.json")}}"
+HERMES_BIN="${HERMES_BIN:-$HOME/.local/share/hermes-agent/releases/0408fec7a153e6c32c064acd2b8053917f1525f1/.venv/bin/hermes}"
 CODEX_HOME="${CODEX_HOME:-${HERMES_FLEET_CODEX_HOME:-$(config_get fleet.codex_home "$HOME/.codex")}}"
 
-if [[ ! -d "$HERMES_HOME" ]]; then
-  echo "hermes: local runtime not provisioned at $HERMES_HOME" >&2
+if [[ ! -d "$RUNTIME_HOME" ]]; then
+  echo "hermes: local runtime not provisioned at $RUNTIME_HOME" >&2
   echo "  fix: run $ROLE_DIR/.scripts/20-runtime-repo.sh" >&2
   exit 1
 fi
 
+if [[ ! -d "$HERMES_HOME" ]]; then
+  echo "hermes: profile not provisioned at $HERMES_HOME" >&2
+  echo "  fix: pj migrate hermes.runtime-singleton" >&2
+  exit 1
+fi
+
+if [[ -L "$HERMES_HOME" ]]; then
+  echo "hermes: $HERMES_HOME is a symlink; the profile dir must be a REAL dir" >&2
+  echo "  (a symlink breaks profile-name resolution and shared fleet auth)" >&2
+  echo "  fix: pj migrate hermes.runtime-singleton" >&2
+  exit 1
+fi
+
 if [[ ! -x "$HERMES_BIN" ]]; then
   echo "hermes: binary not executable at $HERMES_BIN" >&2
   echo "  set HERMES_BIN or HERMES_FLEET_BIN (in $FLEET_ENV) to the shared Hermes binary." >&2
@@ -64,5 +105,5 @@ if [[ ! -x "$HERMES_BIN" ]]; then
 fi
 
 exec env HERMES_HOME="$HERMES_HOME" HERMES_FLEET_ENV="$FLEET_ENV" \
-  HERMES_OAUTH_FILE="$HERMES_OAUTH_FILE" CODEX_HOME="$CODEX_HOME" \
+  CODEX_HOME="$CODEX_HOME" TERMINAL_CWD="$REPO_ROOT" \
   "$HERMES_BIN" "$@"

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

@@ -0,0 +1,177 @@
+#!/usr/bin/env bash
+# Momo provider dispatcher for {{ target_repo }} ({{ role }}).
+#
+# The stable, per-repo entrypoint Momo (and `pj audit --profile
+# momo-lifecycle-plane`) uses to reach this project's ticket board. It is a thin
+# seam ON PURPOSE: all real provider logic already lives in
+# .scripts/lib/ticket-provider.sh, which dispatches to
+# .scripts/providers/<provider>.sh based on repo-root .project.json. This file
+# adds no second implementation of that — duplicating it is how a repo ends up
+# with two disagreeing notions of "what board am I bound to".
+#
+# What this adds over calling `tp` directly:
+#   * one discoverable path per role (agents/hermes/<role>/momo) instead of
+#     "source the right lib from the right cwd"
+#   * --help / --smoke, so readiness is checkable without credentials
+#   * the canonical Krebs phase -> tp-band map, so callers reason in lifecycle
+#     phases rather than hardcoding provider labels
+#
+# Operations are forwarded verbatim to `tp`. See the contract at the top of
+# .scripts/lib/ticket-provider.sh: resolve, active_milestone, list_issues,
+# get_issue, comment, transition, create_board, create_issue.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+LIB="$SCRIPT_DIR/.scripts/lib/ticket-provider.sh"
+
+# Canonical lifecycle spec. Phases are Krebs' vocabulary; tp bands are the five
+# normalized states every provider adapter must map. Kept in sync with
+# krebs/spec/lifecycle.v1.yaml — that file is the source of truth.
+LIFECYCLE_SPEC="${KREBS_LIFECYCLE_SPEC:-$HOME/code/33GOD/krebs/spec/lifecycle.v1.yaml}"
+
+usage() {
+  cat <<'MOMO_HELP'
+momo — ticket-board dispatcher for this repo's Hermes role
+
+USAGE
+  momo <operation> [args...]     forward an operation to the bound ticket provider
+  momo --help                    show this help
+  momo --smoke [root|nested]     verify wiring without credentials
+  momo --lifecycle               print the canonical phase -> tp-band map
+  momo --provider                print the resolved provider name
+
+OPERATIONS (implemented by .scripts/providers/<provider>.sh)
+  resolve                        -> {provider, board_id, board_url}
+  active_milestone               -> {id, name, state}
+  list_issues                    -> [ {id,key,title,state,state_type,...} ]
+  get_issue <id>                 -> {id,key,title,description,acceptance,...}
+  comment <id> <body>            -> comment id
+  transition <id> <state>        -> backlog|unstarted|started|in_review|completed|cancelled
+  create_board <name> <id> <d>   -> {board_id, board_url}
+  create_issue [--if-absent] <title> [desc]
+
+The provider and board binding come from repo-root .project.json
+(ticket_provider.*). Credentials come from the environment; see the header of
+the matching .scripts/providers/<provider>.sh.
+MOMO_HELP
+}
+
+# Phase -> tp band, read from the canonical spec when present so this never
+# becomes a stale second copy. The inline fallback exists only so --lifecycle
+# still answers on a host without the 33GOD checkout.
+print_lifecycle() {
+  if [ -r "$LIFECYCLE_SPEC" ] && command -v python3 >/dev/null 2>&1; then
+    python3 - "$LIFECYCLE_SPEC" <<'PY' && return 0
+import sys
+try:
+    import yaml
+except ImportError:
+    sys.exit(1)
+try:
+    spec = yaml.safe_load(open(sys.argv[1]))
+except Exception:
+    sys.exit(1)
+states = spec.get("states") or []
+if not states:
+    sys.exit(1)
+print(f"{'phase':<14} {'tp_band':<12} {'terminal':<9} stale_after")
+for s in states:
+    stale = s.get("staleness_minutes")
+    print(f"{str(s.get('phase')):<14} {str(s.get('tp_band')):<12} "
+          f"{str(bool(s.get('terminal'))).lower():<9} "
+          f"{(str(stale) + 'm') if stale else '-'}")
+PY
+  fi
+  # Fallback: spec unreadable or PyYAML absent.
+  cat <<'FALLBACK'
+phase          tp_band      terminal  stale_after
+backlog        backlog      false     -
+triage         unstarted    false     10m
+refining       unstarted    false     30m
+ready          unstarted    false     -
+in_progress    started      false     120m
+review         in_review    false     15m
+qa             in_review    false     -
+FALLBACK
+  echo "(fallback map: could not read $LIFECYCLE_SPEC)" >&2
+}
+
+require_lib() {
+  if [ ! -r "$LIB" ]; then
+    echo "momo: ticket-provider lib missing: $LIB" >&2
+    echo "momo: run the role's provisioning scripts, or pj migrate hermes.pm-scaffold" >&2
+    return 2
+  fi
+}
+
+# Credential-free wiring check. Verifies the pieces a board call needs are
+# present and resolvable; it deliberately does NOT hit the network, so it is
+# safe in CI and in `pj audit`.
+smoke() {
+  local scope="${1:-root}" rc=0
+  require_lib || return 2
+  # shellcheck source=/dev/null
+  . "$LIB"
+
+  local provider=""
+  provider="$(tp_provider_name 2>/dev/null || true)"
+  if [ -z "$provider" ]; then
+    echo "smoke: no ticket provider resolved (.project.json ticket_provider.type)" >&2
+    rc=1
+  else
+    echo "smoke: provider = $provider"
+  fi
+
+  local impl
+  impl="$(tp_providers_dir 2>/dev/null || true)/${provider}.sh"
+  if [ -n "$provider" ] && [ ! -f "$impl" ]; then
+    echo "smoke: provider adapter missing: $impl" >&2
+    rc=1
+  elif [ -n "$provider" ]; then
+    echo "smoke: adapter   = $impl"
+  fi
+
+  if [ -r "$SCRIPT_DIR/../../../.project.json" ]; then
+    echo "smoke: binding   = repo-root .project.json"
+  else
+    echo "smoke: .project.json not found from $SCRIPT_DIR" >&2
+    rc=1
+  fi
+
+  if [ "$scope" = "nested" ]; then
+    # Nested scope additionally asserts the normalized state vocabulary is
+    # intact, since that is what a nested adapter call would transition against.
+    local missing=""
+    for st in backlog unstarted started in_review completed cancelled; do
+      tp_is_valid_state "$st" || missing="$missing $st"
+    done
+    if [ -n "$missing" ]; then
+      echo "smoke: normalized states missing:$missing" >&2
+      rc=1
+    else
+      echo "smoke: states    = ok (6 normalized)"
+    fi
+  fi
+
+  [ "$rc" -eq 0 ] && echo "smoke: ok ($scope)"
+  return "$rc"
+}
+
+main() {
+  case "${1:---help}" in
+    --help|-h|help) usage ;;
+    --lifecycle)    print_lifecycle ;;
+    --smoke)        shift; smoke "${1:-root}" ;;
+    --provider)
+      require_lib || exit 2
+      # shellcheck source=/dev/null
+      . "$LIB"; tp_provider_name ;;
+    *)
+      require_lib || exit 2
+      # shellcheck source=/dev/null
+      . "$LIB"
+      tp "$@" ;;
+  esac
+}
+
+main "$@"