@delorenj/pjangler 1.2.33 → 1.3.7

package/templates/hermes-agent/template/.scripts/30-telegram.sh

@@ -46,15 +46,28 @@ path.write_text(text[: match.start("body")] + body + text[match.end("body") :],
 PYEOF
 }
 
-already_done 30-telegram && { log "[30] telegram already wired — skipping"; exit 0; }
+telegram_status="$(yaml_get telegram.provisioning_status)"
 
 if [[ "${SKIP_TELEGRAM:-0}" == "1" ]]; then
-  telegram_yaml_update provisioning_status disabled
-  log "[30] telegram — SKIPPED (SKIP_TELEGRAM=1)"
-  mark_done 30-telegram
+  if [[ "$telegram_status" == "verified" ]] && already_done 30-telegram; then
+    log "[30] telegram — SKIPPED; existing verified wiring preserved"
+  else
+    telegram_yaml_update provisioning_status disabled
+    clear_done 30-telegram
+    log "[30] telegram — DEFERRED (SKIP_TELEGRAM=1; completion marker cleared)"
+  fi
   exit 0
 fi
 
+if already_done 30-telegram; then
+  if [[ "$telegram_status" == "verified" ]]; then
+    log "[30] telegram already wired — skipping"
+    exit 0
+  fi
+  clear_done 30-telegram
+  log "[30] stale deferred completion marker cleared — reconciling Telegram"
+fi
+
 RUNTIME="$ROLE_DIR/runtime"
 ENVF="$RUNTIME/.env"
 mkdir -p "$RUNTIME"
@@ -81,6 +94,7 @@ fi
 
 if [[ -z "${TELEGRAM_BOT_TOKEN:-}" ]]; then
   telegram_yaml_update provisioning_status deferred
+  clear_done 30-telegram
   warn "    no token provided; Telegram step deferred"
   warn "    re-run later with a profile-dedicated TELEGRAM_BOT_TOKEN invocation"
   exit 0

package/templates/hermes-agent/template/.scripts/42-ticket-provider.sh

@@ -12,6 +12,15 @@
 #         it becomes the SOT for every agent in this repo.
 # Either way we register this agent under .project.json `agents` and mirror the
 # binding into role.yaml for back-compat (80-registry.sh / 99-summary.sh).
+
+# The caller's negative board grant is authoritative. Check it before sourcing
+# _lib.sh so a skipped step cannot load fleet credentials, create logs/markers,
+# inspect bindings, or reach a provider adapter.
+if [[ "${SKIP_PLANE:-0}" == "1" ]]; then
+  printf '%s\n' '[42] ticket provider — SKIPPED (SKIP_PLANE=1)' >&2
+  exit 0
+fi
+
 # shellcheck source=_lib.sh
 source "$(dirname "$0")/_lib.sh"
 load_role_env
@@ -74,7 +83,15 @@ if set_provider == "1":
     if board_url:  tp["board_url"] = board_url
     if team:       tp["team"] = team
 ag = d.setdefault("agents", {})
-ag[os.environ["AGENT_ID"]] = {"role": os.environ["ROLE"], "role_dir": os.environ["ROLE_DIR_REL"]}
+entry = ag.get(os.environ["AGENT_ID"], {})
+if not isinstance(entry, dict):
+    entry = {}
+entry.update({
+    "role": os.environ["ROLE"],
+    "role_dir": os.environ["ROLE_DIR_REL"],
+    "provisioning_state": "provisioned",
+})
+ag[os.environ["AGENT_ID"]] = entry
 p.write_text(json.dumps(d, indent=2) + "\n")
 PY
   log "    .project.json updated (agent=$AGENT_ID)"

package/templates/hermes-agent/template/.scripts/70-systemd.sh

@@ -12,9 +12,88 @@ if [[ "$ROLE" == "reporter" ]]; then
   exit 0
 fi
 
+# Resolve expected paths without creating directories or querying the user
+# manager.  A legacy skip-created marker is complete only when all units exist.
 RUNTIME="$ROLE_DIR/runtime"
+FLEET_HOME="${HERMES_FLEET_HOME:-$HOME/.hermes}"
+PROFILE_HOME="$FLEET_HOME/profiles/${PROFILE_NAME:-$AGENT_ID}"
 REPO_ROOT="$(project_repo_path)" || REPO_ROOT="$ROLE_DIR"
 SYS_DIR="$HOME/.config/systemd/user"
+GW_UNIT="hermes-${AGENT_ID}-gateway.service"
+HB_SVC="hermes-${AGENT_ID}-heartbeat.service"
+HB_TIMER="hermes-${AGENT_ID}-heartbeat.timer"
+
+# Local-only provisioning must not inspect or mutate the host user manager.
+# Honor the explicit skip before creating unit directories or querying legacy
+# unit state; cleanup remains fail-closed whenever systemd management is active.
+if [[ "${SKIP_SYSTEMD:-0}" == "1" ]]; then
+  if already_done 70-systemd \
+     && [[ -f "$SYS_DIR/$GW_UNIT" && -f "$SYS_DIR/$HB_SVC" && -f "$SYS_DIR/$HB_TIMER" ]]; then
+    log "[70] systemd — SKIPPED; existing complete unit set preserved"
+  else
+    clear_done 70-systemd
+    log "[70] systemd — DEFERRED (completion marker cleared)"
+  fi
+  exit 0
+fi
+
+# Render every caller-controlled systemd scalar through the same data-only
+# serializer used by fleet backfill. This validation happens before mkdir,
+# systemctl, or unit writes, so CR/LF/NUL cannot create a second directive and
+# spaces/quotes/backslashes/specifier bytes remain exact.
+PYTHON_BIN="$(builtin type -P python3)" || die "python3 is unavailable for systemd unit serialization"
+systemd_value() {
+  "$PYTHON_BIN" -I "$FLEET_ENV_PARSER" --systemd-value "$1" \
+    || die "systemd value validation failed"
+}
+systemd_environment() {
+  "$PYTHON_BIN" -I "$FLEET_ENV_PARSER" --systemd-environment "$1" "$2" \
+    || die "systemd environment validation failed"
+}
+systemd_exec_value() {
+  "$PYTHON_BIN" -I "$FLEET_ENV_PARSER" --systemd-exec-value "$1" \
+    || die "systemd ExecStart value validation failed"
+}
+GW_DESCRIPTION="$(systemd_value "Hermes Gateway — $DISPLAY_NAME")"
+HB_DESCRIPTION="$(systemd_value "Hermes Heartbeat (reconcile + checkpoint) — $DISPLAY_NAME")"
+TIMER_DESCRIPTION="$(systemd_value "Heartbeat (reconcile + checkpoint) for $AGENT_ID")"
+ENV_HERMES_HOME="$(systemd_environment HERMES_HOME "$PROFILE_HOME")"
+ENV_HERMES_BIN="$(systemd_environment HERMES_BIN "$HERMES_BIN")"
+ENV_CODEX_HOME="$(systemd_environment CODEX_HOME "$CODEX_HOME")"
+ENV_TERMINAL_CWD="$(systemd_environment TERMINAL_CWD "$REPO_ROOT")"
+WORKING_DIRECTORY="$(systemd_value "$REPO_ROOT")"
+RUNTIME_ENV_FILE="$(systemd_value "-$RUNTIME/.env")"
+GW_LOG_OUTPUT="$(systemd_value "append:$RUNTIME/logs/gateway.systemd.log")"
+HB_LOG_OUTPUT="$(systemd_value "append:$RUNTIME/logs/heartbeat.log")"
+GW_EXEC_START="$(systemd_exec_value "$ROLE_DIR/.scripts/credential-launch.sh")"
+HB_EXEC_START="$GW_EXEC_START"
+
+# Encrypted credentials are optional and take precedence over the existing
+# ignored runtime/.env fallback. Validate every path-derived unit scalar before
+# any directory, unit, marker, or systemd mutation.
+CREDENTIAL_DIR="${HERMES_SYSTEMD_CREDENTIAL_DIR:-$HOME/.config/hermes-agent/credentials}"
+TELEGRAM_CREDENTIAL="$CREDENTIAL_DIR/${AGENT_ID}-telegram-bot-token.cred"
+MODEL_CREDENTIAL="$CREDENTIAL_DIR/${AGENT_ID}-model-api-key.cred"
+GW_CREDENTIAL_LINES=""
+HB_CREDENTIAL_LINES=""
+if [[ -f "$TELEGRAM_CREDENTIAL" ]]; then
+  command -v systemd-creds >/dev/null 2>&1 \
+    || die "encrypted Telegram credential exists but systemd-creds is unavailable"
+  GW_CREDENTIAL_LINES="LoadCredentialEncrypted=$(systemd_value "telegram_bot_token:$TELEGRAM_CREDENTIAL")"
+fi
+if [[ -f "$MODEL_CREDENTIAL" ]]; then
+  [[ -n "$(yaml_get model.key_env)" ]] \
+    || die "encrypted model credential exists but model.key_env is blank in role.yaml"
+  command -v systemd-creds >/dev/null 2>&1 \
+    || die "encrypted model credential exists but systemd-creds is unavailable"
+  GW_CREDENTIAL_LINES="${GW_CREDENTIAL_LINES}${GW_CREDENTIAL_LINES:+$'\n'}LoadCredentialEncrypted=$(systemd_value "model_api_key:$MODEL_CREDENTIAL")"
+  HB_CREDENTIAL_LINES="LoadCredentialEncrypted=$(systemd_value "model_api_key:$MODEL_CREDENTIAL")"
+fi
+
+# Singleton-runtime contract: units set HERMES_HOME to the agent's NAMED PROFILE
+# dir, never the raw runtime path — Hermes derives profile identity and shared
+# fleet auth from the unresolved HERMES_HOME. $RUNTIME stays correct for
+# EnvironmentFile and logs: those are the repo-owned side the profile links to.
 mkdir -p "$SYS_DIR" "$RUNTIME/logs"
 
 # Upgrade remediation must run before honoring a legacy done marker. Older
@@ -56,34 +135,45 @@ if [[ $legacy_consumer_present -eq 1 ]]; then
   log "    retired legacy per-profile Bloodbank consumer: $LEGACY_CONSUMER_UNIT"
 fi
 
-already_done 70-systemd && { log "[70] systemd already installed — legacy cleanup checked"; exit 0; }
-[[ "${SKIP_SYSTEMD:-0}" == "1" ]] && { log "[70] systemd — SKIPPED"; mark_done 70-systemd; exit 0; }
+if already_done 70-systemd; then
+  if [[ -f "$SYS_DIR/$GW_UNIT" && -f "$SYS_DIR/$HB_SVC" && -f "$SYS_DIR/$HB_TIMER" ]]; then
+    log "[70] systemd already installed — reconciling unit definitions"
+  else
+    clear_done 70-systemd
+    log "    stale/incomplete systemd marker cleared — reconciling required units"
+  fi
+fi
 
 # The heartbeat runner (board-reconciliation sentinel pass + gated checkpoint)
 # and the checkpoint helper both render into the role dir; just ensure they are
 # executable. heartbeat.sh calls checkpoint.sh internally.
 HEARTBEAT_BIN="$ROLE_DIR/.scripts/heartbeat.sh"
-chmod +x "$HEARTBEAT_BIN" "$ROLE_DIR/.scripts/checkpoint.sh" 2>/dev/null || true
+CREDENTIAL_LAUNCHER="$ROLE_DIR/.scripts/credential-launch.sh"
+chmod +x "$HEARTBEAT_BIN" "$CREDENTIAL_LAUNCHER" "$ROLE_DIR/.scripts/checkpoint.sh" 2>/dev/null || true
+
+[[ -d "$PROFILE_HOME" && ! -L "$PROFILE_HOME" ]] \
+  || die "named profile is not a real directory; run: pj migrate hermes.runtime-singleton '$REPO_ROOT'"
 
 # Gateway unit
-GW_UNIT="hermes-${AGENT_ID}-gateway.service"
 cat > "$SYS_DIR/$GW_UNIT" <<UNIT
 [Unit]
-Description=Hermes Gateway — $DISPLAY_NAME
+Description=$GW_DESCRIPTION
 After=network-online.target
 Wants=network-online.target
 
 [Service]
 Type=simple
-Environment=HERMES_HOME=$RUNTIME
-Environment=HERMES_OAUTH_FILE=$HERMES_OAUTH_FILE
-Environment=CODEX_HOME=$CODEX_HOME
-EnvironmentFile=-$RUNTIME/.env
-ExecStart=$HERMES_BIN gateway run --replace
+$ENV_HERMES_HOME
+$ENV_HERMES_BIN
+$ENV_CODEX_HOME
+$ENV_TERMINAL_CWD
+EnvironmentFile=$RUNTIME_ENV_FILE
+$GW_CREDENTIAL_LINES
+ExecStart=$GW_EXEC_START gateway
 Restart=on-failure
 RestartSec=10
-StandardOutput=append:$RUNTIME/logs/gateway.systemd.log
-StandardError=append:$RUNTIME/logs/gateway.systemd.log
+StandardOutput=$GW_LOG_OUTPUT
+StandardError=$GW_LOG_OUTPUT
 
 [Install]
 WantedBy=default.target
@@ -93,33 +183,33 @@ UNIT
 # Frequent ticks (1 min); heartbeat.sh's own cooldown/lock logic rate-limits the
 # full Hermes pass, and the checkpoint is gated to ~hourly inside the runner.
 # The per-agent EnvironmentFiles load ticket-provider creds for the sentinel pass.
-HB_SVC="hermes-${AGENT_ID}-heartbeat.service"
-HB_TIMER="hermes-${AGENT_ID}-heartbeat.timer"
 cat > "$SYS_DIR/$HB_SVC" <<UNIT
 [Unit]
-Description=Hermes Heartbeat (reconcile + checkpoint) — $DISPLAY_NAME
+Description=$HB_DESCRIPTION
 After=network-online.target
 Wants=network-online.target
 
 [Service]
 Type=oneshot
-WorkingDirectory=$REPO_ROOT
-Environment=HERMES_HOME=$RUNTIME
-Environment=HERMES_OAUTH_FILE=$HERMES_OAUTH_FILE
-Environment=CODEX_HOME=$CODEX_HOME
+WorkingDirectory=$WORKING_DIRECTORY
+$ENV_HERMES_HOME
+$ENV_HERMES_BIN
+$ENV_CODEX_HOME
+$ENV_TERMINAL_CWD
 EnvironmentFile=-%h/.config/hermes-agent/env
 EnvironmentFile=-%h/.hermes/env
 EnvironmentFile=-%h/.hermes/hermes-agent.env
 EnvironmentFile=-%h/.hermes/${AGENT_ID}.env
-EnvironmentFile=-$RUNTIME/.env
-ExecStart=$HEARTBEAT_BIN
+EnvironmentFile=$RUNTIME_ENV_FILE
+$HB_CREDENTIAL_LINES
+ExecStart=$HB_EXEC_START heartbeat
 TimeoutStartSec=45min
-StandardOutput=append:$RUNTIME/logs/heartbeat.log
-StandardError=append:$RUNTIME/logs/heartbeat.log
+StandardOutput=$HB_LOG_OUTPUT
+StandardError=$HB_LOG_OUTPUT
 UNIT
 cat > "$SYS_DIR/$HB_TIMER" <<UNIT
 [Unit]
-Description=Heartbeat (reconcile + checkpoint) for $AGENT_ID
+Description=$TIMER_DESCRIPTION
 
 [Timer]
 OnBootSec=1min

package/templates/hermes-agent/template/.scripts/80-registry.sh

@@ -1,5 +1,11 @@
 #!/usr/bin/env bash
 # Append this agent's entry to the global fleet registry.
+
+if [[ "${SKIP_HOST_STATE:-0}" == "1" ]]; then
+  printf '%s\n' '[80] fleet registry — DEFERRED (SKIP_HOST_STATE=1)' >&2
+  exit 0
+fi
+
 # shellcheck source=_lib.sh
 source "$(dirname "$0")/_lib.sh"
 load_role_env
@@ -29,7 +35,8 @@ python3 - "$REGISTRY_FILE" "$AGENT_ID" "$REPO" "$ROLE" "$DISPLAY_NAME" \
   "$(yaml_get slack.provisioning_status)" "$(yaml_get slack.team_id)" \
   "$(yaml_get slack.team_name)" "$(yaml_get slack.bot_user_id)" \
   "$(yaml_get slack.bot_id)" "$(yaml_get slack.bot_username)" \
-  "$(yaml_get bloodbank.gateway_scope)" "$(yaml_get bloodbank.target_agent_id)" \
+  "$(yaml_get bloodbank.enabled)" "$(yaml_get bloodbank.gateway_scope)" \
+  "$(yaml_get bloodbank.target_agent_id)" \
   "$PLANE_WORKSPACE" "$PLANE_PROJECT_ID" "$(yaml_get plane.identifier)" \
   "$RUNTIME_REPO" "$HERMES_BIN" "$HERMES_AGENT_REPO" "$HERMES_RUNTIME_GIT_URL" \
   "$HERMES_RUNTIME_GIT_REF" "$HERMES_RUNTIME_GIT_SHA" "$FLEET_ENV" \
@@ -47,13 +54,21 @@ except ImportError:
 (path, agent_id, repo, role, display, project, role_dir, profile,
  telegram_status, bot, telegram_bot_id,
  slack_status, slack_team_id, slack_team_name, slack_user_id, slack_bot_id,
- slack_username, bloodbank_scope, bloodbank_target, plane_ws, plane_id,
+ slack_username, bloodbank_enabled, bloodbank_scope, bloodbank_target, plane_ws, plane_id,
  plane_ident, runtime_repo, hermes_bin, hermes_repo, hermes_git_url,
- hermes_git_ref, hermes_git_sha, fleet_env, gw, heartbeat) = sys.argv[1:32]
+ hermes_git_ref, hermes_git_sha, fleet_env, gw, heartbeat) = sys.argv[1:33]
 p = pathlib.Path(path)
 if p.is_symlink():
     raise SystemExit(f"refusing to update registry symlink: {p}")
 data = yaml.safe_load(p.read_text()) or {"schema_version": 1, "agents": {}}
+if bloodbank_enabled == "":
+    bloodbank_enabled_value = False
+elif bloodbank_enabled == "true":
+    bloodbank_enabled_value = True
+elif bloodbank_enabled == "false":
+    bloodbank_enabled_value = False
+else:
+    raise SystemExit("bloodbank.enabled must be the strict YAML boolean true or false")
 data.setdefault("agents", {})[agent_id] = {
   "repo": repo, "role": role, "display_name": display,
   "project_path": project, "role_dir": role_dir,
@@ -72,6 +87,7 @@ data.setdefault("agents", {})[agent_id] = {
     "bot_username": slack_username,
   },
   "bloodbank": {
+    "enabled": bloodbank_enabled_value,
     "gateway_scope": bloodbank_scope,
     "target_agent_id": bloodbank_target,
   },

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

@@ -137,13 +137,57 @@ already_done() {
 mark_done() {
   touch "$ROLE_DIR/.scripts/.done-$1"
 }
+clear_done() {
+  # Remove only the marker for the explicitly deferred step.  This lets a
+  # later activation reconcile that phase without disturbing completed,
+  # unrelated provisioning state.
+  rm -f -- "$ROLE_DIR/.scripts/.done-$1"
+}
+
+# The parser protocol, unsafe-family scrub, complete framing validation, and
+# atomic environment apply live in one reusable library shared by provisioners,
+# launchers, and maintenance commands.
+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
+  builtin printf 'fleet environment loader rejected: trusted library is unavailable\n' >&2
+  return 1
+fi
+# shellcheck source=lib/fleet-env.sh
+builtin source "$FLEET_ENV_LIBRARY"
 
 # Fleet source-of-truth (shared across all wrappers/provisioners).
 # Every default below resolves as: env var > fleet.env > config.toml > fallback.
+# Invocation authority is not fleet configuration. Capture the caller's board
+# gate before importing fleet.env so that file cannot weaken an MCP/CLI
+# SKIP_PLANE decision or re-enable credentials by assigning SKIP_PLANE=0.
+PJANGLER_INVOCATION_SKIP_PLANE="${SKIP_PLANE:-0}"
 FLEET_ENV="${HERMES_FLEET_ENV:-$(config_get fleet.fleet_env "$HOME/.hermes/fleet.env")}"
-if [[ -f "$FLEET_ENV" ]]; then
-  # shellcheck disable=SC1090
-  source "$FLEET_ENV"
+
+# A direct CLI caller may not have passed through the MCP parent boundary. The
+# shared loader hardens both before parser startup and again after atomic import.
+if ! load_fleet_environment "$FLEET_ENV" "$FLEET_ENV_PARSER"; then
+  return 1
+fi
+SKIP_PLANE="$PJANGLER_INVOCATION_SKIP_PLANE"
+unset PJANGLER_INVOCATION_SKIP_PLANE
+scrub_subprocess_interpreter_injection
+
+# fleet.env is allowed to supply provider credentials only for an explicitly
+# board-authorized invocation. A no-board/deferred phase must remove every
+# supported provider alias after sourcing and before any Python, Hermes,
+# systemd, provider, or other child process can inherit it.
+scrub_ticket_provider_authority() {
+  local key
+  unset PLANE_API_KEY TRELLO_KEY TRELLO_TOKEN LINEAR_API_KEY
+  while IFS= read -r key; do
+    case "$key" in
+      PLANE_*_API_KEY) unset "$key" ;;
+    esac
+  done < <(compgen -A variable PLANE_)
+}
+if [[ "$SKIP_PLANE" == "1" ]]; then
+  scrub_ticket_provider_authority
 fi
 # Identity-bearing chat credentials are never fleet-scoped. Platform wiring
 # steps capture explicit invocation values before sourcing this library and
@@ -151,11 +195,12 @@ fi
 unset TELEGRAM_BOT_TOKEN SLACK_BOT_TOKEN SLACK_APP_TOKEN
 
 # Tools we expect on the host
-HERMES_BIN="${HERMES_BIN:-${HERMES_FLEET_BIN:-$(config_get fleet.hermes_bin "$HOME/.hermes/hermes-agent/.venv/bin/hermes")}}"
-HERMES_AGENT_REPO="${HERMES_AGENT_REPO:-${HERMES_FLEET_REPO:-$(config_get fleet.hermes_repo "$HOME/.hermes/hermes-agent")}}"
+HERMES_BIN="${HERMES_BIN:-${HERMES_FLEET_BIN:-$(config_get fleet.hermes_bin "$HOME/.local/share/hermes-agent/releases/0408fec7a153e6c32c064acd2b8053917f1525f1/.venv/bin/hermes")}}"
+HERMES_AGENT_REPO="${HERMES_AGENT_REPO:-${HERMES_FLEET_REPO:-$(config_get fleet.hermes_repo "$HOME/.local/share/hermes-agent/releases/0408fec7a153e6c32c064acd2b8053917f1525f1")}}"
+PJANGLER_BIN="${PJANGLER_BIN:-$(config_get fleet.pjangler_bin "pj")}"
 HERMES_RUNTIME_GIT_URL="${HERMES_RUNTIME_GIT_URL:-$(config_get fleet.hermes_git_url 'https://github.com/delorenj/hermes-agent.git')}"
-HERMES_RUNTIME_GIT_REF="${HERMES_RUNTIME_GIT_REF:-$(config_get fleet.hermes_git_ref 'feature/PJAN-19-routing-publication')}"
-HERMES_RUNTIME_GIT_SHA="${HERMES_RUNTIME_GIT_SHA:-$(config_get fleet.hermes_git_sha '113e1b182b6d72a7dd02a191f134a41668ceaf0e')}"
+HERMES_RUNTIME_GIT_REF="${HERMES_RUNTIME_GIT_REF:-$(config_get fleet.hermes_git_ref 'main')}"
+HERMES_RUNTIME_GIT_SHA="${HERMES_RUNTIME_GIT_SHA:-$(config_get fleet.hermes_git_sha '0408fec7a153e6c32c064acd2b8053917f1525f1')}"
 HERMES_OAUTH_FILE="${HERMES_OAUTH_FILE:-${HERMES_FLEET_OAUTH_FILE:-$(config_get fleet.oauth_file "$HOME/.hermes/auth.json")}}"
 CODEX_HOME="${CODEX_HOME:-${HERMES_FLEET_CODEX_HOME:-$(config_get fleet.codex_home "$HOME/.codex")}}"
 # Prefer a scaffold vendored into this agent directory; fall back to the configured template path.
@@ -183,7 +228,7 @@ fleet_lock_acquire() {
 fleet_lock_release() {
   if [[ "${FLEET_LOCK_FD:-}" =~ ^[0-9]+$ ]]; then
     flock -u "$FLEET_LOCK_FD" 2>/dev/null || true
-    eval "exec ${FLEET_LOCK_FD}>&-"
+    exec {FLEET_LOCK_FD}>&-
   fi
   FLEET_LOCK_FD=""
 }
@@ -195,13 +240,18 @@ BLOODBANK_COMPOSE_DIR="${BLOODBANK_COMPOSE_DIR:-$(config_get bloodbank.compose_d
 
 # Plane
 PLANE_BASE="${PLANE_BASE:-$(config_get plane.base 'https://plane.delo.sh')}"
-PLANE_API_KEY="${PLANE_API_KEY:-${PLANE_33GOD_API_KEY:-}}"
+if [[ "$SKIP_PLANE" != "1" ]]; then
+  PLANE_API_KEY="${PLANE_API_KEY:-${PLANE_33GOD_API_KEY:-}}"
+fi
 
-export FLEET_ENV HERMES_BIN HERMES_AGENT_REPO HERMES_RUNTIME_GIT_URL \
+export FLEET_ENV HERMES_BIN HERMES_AGENT_REPO PJANGLER_BIN HERMES_RUNTIME_GIT_URL \
        HERMES_RUNTIME_GIT_REF HERMES_RUNTIME_GIT_SHA HERMES_OAUTH_FILE CODEX_HOME \
        RUNTIME_SCAFFOLD_DIR REGISTRY_FILE \
        BLOODBANK_NATS_HOST BLOODBANK_NATS_PORT BLOODBANK_COMPOSE_DIR \
-       PLANE_BASE PLANE_API_KEY
+       PLANE_BASE SKIP_PLANE
+if [[ "$SKIP_PLANE" != "1" ]]; then
+  export PLANE_API_KEY
+fi
 
 # systemd --user health check. Accept running/degraded/starting — only one
 # broken unit shouldn't disqualify the rest of the user manager.
@@ -248,6 +298,19 @@ systemctl_user_unit_state() {
 # Resolve project repo path (the repo that holds agents/hermes/<role>/).
 # Walk up from $ROLE_DIR until we find a git root that isn't us.
 project_repo_path() {
+  # Structured provisioners know the project root even before a fresh target
+  # receives its own .git directory. Accept only a root that contains this
+  # exact role path; otherwise fail closed instead of walking into a parent
+  # checkout and mutating its manifest.
+  if [[ -n "${PJANGLER_PROJECT_ROOT:-}" ]]; then
+    local explicit role_real
+    explicit="$(cd "$PJANGLER_PROJECT_ROOT" 2>/dev/null && pwd -P)" || return 1
+    role_real="$(cd "$ROLE_DIR" 2>/dev/null && pwd -P)" || return 1
+    case "$role_real" in
+      "$explicit"/agents/hermes/*) printf '%s\n' "$explicit"; return 0 ;;
+      *) return 1 ;;
+    esac
+  fi
   local d="$ROLE_DIR"
   [[ -d "$d/.git" || -f "$d/.git" ]] && { echo "$d"; return 0; }
   for _ in 1 2 3 4 5; do

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

@@ -38,6 +38,23 @@ secret_scan_ok() {
   return 0
 }
 
+# A checkpoint on a DETACHED HEAD belongs to no branch: `git push origin HEAD`
+# cannot resolve a destination, so every commit stays local forever. One runtime
+# reached 232 orphaned commits this way before anyone noticed.
+BRANCH="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo HEAD)"
+if [ "$BRANCH" = "HEAD" ]; then
+  printf '[checkpoint] ABORT: %s is on a DETACHED HEAD — refusing to create commits that can never be pushed.\n' "$RUNTIME_DIR" >&2
+  printf '[checkpoint] Fix: git -C %s switch -c main && git -C %s push -u origin main\n' "$RUNTIME_DIR" "$RUNTIME_DIR" >&2
+  exit 4
+fi
+
+# Report an existing backlog BEFORE adding to it, so a broken push is visible on
+# the very next tick instead of compounding silently for months.
+backlog="$(git rev-list --count "origin/$BRANCH..HEAD" 2>/dev/null || echo 0)"
+if [ "$backlog" -ge 10 ]; then
+  printf '[checkpoint] WARNING: %s already has %s UNPUSHED commit(s) on %s.\n' "$RUNTIME_DIR" "$backlog" "$BRANCH" >&2
+fi
+
 git add -A
 if git diff --cached --quiet; then
   exit 0
@@ -51,4 +68,15 @@ if ! secret_scan_ok; then
 fi
 
 git -c commit.gpgsign=false commit -m "checkpoint $(date -Iseconds)" >/dev/null
-git push origin HEAD 2>&1 | tail -1 || true
+
+# The push MUST be observable. This line used to be
+#   git push origin HEAD 2>&1 | tail -1 || true
+# where `|| true` swallowed every failure — diverged branch, auth, network —
+# and the pipe masked git's exit status on top of it. Run hourly, that turns a
+# broken push into an invisible, unbounded pile of local-only commits.
+if ! git push origin "$BRANCH" >/dev/null 2>&1; then
+  ahead="$(git rev-list --count "origin/$BRANCH..HEAD" 2>/dev/null || echo '?')"
+  printf '[checkpoint] PUSH FAILED for %s (%s commit(s) exist ONLY on this disk).\n' "$RUNTIME_DIR" "$ahead" >&2
+  printf '[checkpoint] Diagnose: git -C %s push origin %s\n' "$RUNTIME_DIR" "$BRANCH" >&2
+  exit 5
+fi

package/templates/hermes-agent/template/.scripts/config.example.toml

@@ -12,14 +12,17 @@
 
 [fleet]
 # Absolute path to the shared Hermes executable every agent launcher execs.
-hermes_bin = "~/.hermes/hermes-agent/.venv/bin/hermes"
+hermes_bin = "~/.local/share/hermes-agent/releases/0408fec7a153e6c32c064acd2b8053917f1525f1/.venv/bin/hermes"
 # Checkout of the shared hermes-agent repo.
-hermes_repo = "~/.hermes/hermes-agent"
+hermes_repo = "~/.local/share/hermes-agent/releases/0408fec7a153e6c32c064acd2b8053917f1525f1"
+# Canonical CommonProject migration CLI. Runtime provisioning delegates named
+# profile topology to this command; it never rewrites profile links itself.
+pjangler_bin = "pj"
 # Reviewed fleet runtime publication. Provisioning metadata and clean installs
 # must agree on this fork/ref/SHA; do not substitute upstream main.
 hermes_git_url = "https://github.com/delorenj/hermes-agent.git"
-hermes_git_ref = "feature/PJAN-19-routing-publication"
-hermes_git_sha = "113e1b182b6d72a7dd02a191f134a41668ceaf0e"
+hermes_git_ref = "main"
+hermes_git_sha = "0408fec7a153e6c32c064acd2b8053917f1525f1"
 # Fallback runtime scaffold dir — used only when an agent's vendored
 # ./.runtime-scaffold is missing.
 runtime_scaffold_dir = "~/code/hermes-agent-template/runtime-scaffold"

package/templates/hermes-agent/template/.scripts/credential-launch.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# Secret-free systemd entrypoint. Decrypted values are read only from the
+# service manager's volatile credential directory and never printed or written.
+set -euo pipefail
+
+ROLE_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+ROLE_YAML="$ROLE_DIR/role.yaml"
+
+yaml_get() {
+  python3 - "$ROLE_YAML" "$1" <<'PYEOF'
+import re, sys
+from pathlib import Path
+text = Path(sys.argv[1]).read_text()
+parts = sys.argv[2].split(".")
+if len(parts) == 2:
+    match = re.search(
+        rf"(?m)^{re.escape(parts[0])}:[ \t]*\n((?:[ \t]+\S.*\n?)*)", text
+    )
+    text = match.group(1) if match else ""
+key = parts[-1]
+match = re.search(rf'(?m)^\s*{re.escape(key)}:\s*"?([^"\n]*)"?\s*$', text)
+print(match.group(1).strip() if match else "")
+PYEOF
+}
+
+AGENT_ID="$(yaml_get agent_id)"
+PROFILE_NAME="$(yaml_get profile)"
+[[ -n "$AGENT_ID" && -n "$PROFILE_NAME" ]] \
+  || { printf 'credential-launch: incomplete role identity\n' >&2; exit 2; }
+[[ -n "${HERMES_BIN:-}" && -x "$HERMES_BIN" ]] \
+  || { printf 'credential-launch: HERMES_BIN is not executable\n' >&2; exit 1; }
+
+mode="${1:-}"
+[[ "$mode" == "gateway" || "$mode" == "heartbeat" ]] \
+  || { printf 'credential-launch: expected gateway or heartbeat\n' >&2; exit 2; }
+
+FLEET_HOME="${HERMES_FLEET_HOME:-$HOME/.hermes}"
+PROFILE_HOME="$FLEET_HOME/profiles/${PROFILE_NAME:-$AGENT_ID}"
+[[ -d "$PROFILE_HOME" && ! -L "$PROFILE_HOME" ]] \
+  || { printf 'credential-launch: named profile is not a real directory\n' >&2; exit 1; }
+export HERMES_HOME="$PROFILE_HOME"
+
+if ! REPO_ROOT="$(git -C "$ROLE_DIR" rev-parse --show-toplevel 2>/dev/null)"; then
+  REPO_ROOT="$ROLE_DIR"
+fi
+export TERMINAL_CWD="$REPO_ROOT"
+
+load_credential() {
+  local credential_id="$1" env_name="$2" credential_file value
+  [[ "$env_name" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]] \
+    || { printf 'credential-launch: invalid credential environment name\n' >&2; exit 2; }
+  credential_file="${CREDENTIALS_DIRECTORY:-}/$credential_id"
+  [[ -n "${CREDENTIALS_DIRECTORY:-}" && -r "$credential_file" ]] || return 0
+  value="$(<"$credential_file")"
+  printf -v "$env_name" '%s' "$value"
+  export "$env_name"
+  unset value
+}
+
+load_credential telegram_bot_token TELEGRAM_BOT_TOKEN
+MODEL_KEY_ENV="$(yaml_get model.key_env)"
+if [[ -n "$MODEL_KEY_ENV" ]]; then
+  load_credential model_api_key "$MODEL_KEY_ENV"
+fi
+
+if [[ "$mode" == "heartbeat" ]]; then
+  exec "$ROLE_DIR/.scripts/heartbeat.sh"
+fi
+
+gateway_args=(gateway run --replace)
+MODEL_NAME="$(yaml_get model.name)"
+MODEL_PROVIDER="$(yaml_get model.provider)"
+MODEL_BASE_URL="$(yaml_get model.base_url)"
+MODEL_API_MODE="$(yaml_get model.api_mode)"
+[[ -z "$MODEL_NAME" ]] || gateway_args+=(--model "$MODEL_NAME")
+[[ -z "$MODEL_PROVIDER" ]] || gateway_args+=(--provider "$MODEL_PROVIDER")
+[[ -z "$MODEL_BASE_URL" ]] || gateway_args+=(--base-url "$MODEL_BASE_URL")
+[[ -z "$MODEL_API_MODE" ]] || gateway_args+=(--api-mode "$MODEL_API_MODE")
+[[ -z "$MODEL_KEY_ENV" ]] || gateway_args+=(--key-env "$MODEL_KEY_ENV")
+
+exec "$HERMES_BIN" "${gateway_args[@]}"

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

@@ -15,16 +15,29 @@ set -euo pipefail
 
 ROLE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"   # agents/hermes/<role>
 RUNTIME="$ROLE_DIR/runtime"
+RUN_HOME="${HERMES_HOME:-$RUNTIME}"
 PROMPT_FILE="$ROLE_DIR/.scripts/sentinel.prompt.md"
 STATE_FILE="$RUNTIME/continuous-ticket-sentinel-state.json"
 LOCK_FILE="$RUNTIME/continuous-ticket-sentinel.lock"
 ROLE_YAML="$ROLE_DIR/role.yaml"
+FLEET_ENV="${HERMES_FLEET_ENV:-$HOME/.hermes/fleet.env}"
+FLEET_ENV_LIBRARY="$ROLE_DIR/.scripts/lib/fleet-env.sh"
+FLEET_ENV_PARSER="$ROLE_DIR/.scripts/lib/parse-fleet-env.py"
 LOG_FILE="$RUNTIME/logs/heartbeat.log"
 CHECKPOINT_BIN="$ROLE_DIR/.scripts/checkpoint.sh"
 CHECKPOINT_STAMP="$RUNTIME/.last-checkpoint"
 
+if [[ ! -f "$FLEET_ENV_LIBRARY" || -L "$FLEET_ENV_LIBRARY" \
+   || ! -f "$FLEET_ENV_PARSER" || -L "$FLEET_ENV_PARSER" ]]; then
+  echo "heartbeat: trusted fleet environment loader unavailable" >&2
+  exit 1
+fi
+# shellcheck source=lib/fleet-env.sh
+builtin source "$FLEET_ENV_LIBRARY"
+load_fleet_environment "$FLEET_ENV" "$FLEET_ENV_PARSER"
+
 # Hermes binary: explicit env > ~/.config/hermes-agent/hermes-bin > PATH.
-HERMES_BIN="${HERMES_BIN:-}"
+HERMES_BIN="${HERMES_BIN:-${HERMES_FLEET_BIN:-}}"
 if [[ -z "$HERMES_BIN" ]]; then
   if [[ -r "$HOME/.config/hermes-agent/hermes-bin" ]]; then
     HERMES_BIN="$(cat "$HOME/.config/hermes-agent/hermes-bin")"
@@ -242,7 +255,7 @@ trap 'python3 "$ROLE_DIR/.scripts/momo-wip-lock.py" release "$WIP_LOCK" "hermes:
 
 prompt="$(<"$PROMPT_FILE")"
 set +e
-env HERMES_HOME="$RUNTIME" "$HERMES_BIN" chat -Q --source cron --max-turns 90 -q "$prompt"
+env HERMES_HOME="$RUN_HOME" "$HERMES_BIN" chat -Q --source cron --max-turns 90 -q "$prompt"
 status=$?
 set -e