@delorenj/pjangler 1.3.0 → 1.3.7

package/templates/hermes-agent/template/.scripts/05-fleet-env.sh

@@ -1,5 +1,11 @@
 #!/usr/bin/env bash
 # Ensure a single shared fleet source-of-truth file exists.
+
+if [[ "${SKIP_HOST_STATE:-0}" == "1" ]]; then
+  printf '%s\n' '[05] fleet env — DEFERRED (SKIP_HOST_STATE=1)' >&2
+  exit 0
+fi
+
 # shellcheck source=_lib.sh
 source "$(dirname "$0")/_lib.sh"
 load_role_env
@@ -8,45 +14,29 @@ already_done 05-fleet-env && log "[05] fleet env already checked — refreshing
 
 mkdir -p "$(dirname "$FLEET_ENV")"
 
+new_fleet_env=0
 if [[ ! -f "$FLEET_ENV" ]]; then
   log "[05] creating fleet source-of-truth: $FLEET_ENV"
-  cat > "$FLEET_ENV" <<EOF
-# Hermes fleet source of truth.
-# All generated wrappers and provisioning scripts read this file.
-HERMES_FLEET_BIN=${HERMES_BIN}
-HERMES_FLEET_REPO=${HERMES_AGENT_REPO}
-HERMES_FLEET_REGISTRY_FILE=${REGISTRY_FILE}
-HERMES_FLEET_OAUTH_FILE=${HERMES_OAUTH_FILE}
-HERMES_FLEET_CODEX_HOME=${CODEX_HOME}
-EOF
-  chmod 600 "$FLEET_ENV"
+  new_fleet_env=1
 else
   log "[05] fleet env exists: $FLEET_ENV"
 fi
 
+fleet_env_parser="$ROLE_DIR/.scripts/lib/parse-fleet-env.py"
+fleet_env_python="$(builtin type -P python3)" \
+  || die "python3 is required to update the fleet source-of-truth"
+
 upsert_fleet_env() {
   local key="$1" value="$2"
-  python3 - "$FLEET_ENV" "$key" "$value" <<'PYEOF'
-import pathlib
-import sys
-
-path = pathlib.Path(sys.argv[1])
-key = sys.argv[2]
-value = sys.argv[3]
-line = f"{key}={value}"
-lines = path.read_text().splitlines() if path.exists() else []
-for idx, existing in enumerate(lines):
-    if existing.startswith(f"{key}="):
-        lines[idx] = line
-        break
-else:
-    lines.append(line)
-path.write_text("\n".join(lines) + "\n")
-PYEOF
+  "$fleet_env_python" -I "$fleet_env_parser" --upsert "$FLEET_ENV" "$key" "$value"
 }
 
+if [[ "$new_fleet_env" == "1" ]]; then
+  upsert_fleet_env HERMES_FLEET_BIN "$HERMES_BIN"
+  upsert_fleet_env HERMES_FLEET_REPO "$HERMES_AGENT_REPO"
+  upsert_fleet_env HERMES_FLEET_REGISTRY_FILE "$REGISTRY_FILE"
+fi
 upsert_fleet_env HERMES_FLEET_OAUTH_FILE "$HERMES_OAUTH_FILE"
 upsert_fleet_env HERMES_FLEET_CODEX_HOME "$CODEX_HOME"
-chmod 600 "$FLEET_ENV"
 
 mark_done 05-fleet-env

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

@@ -3,6 +3,12 @@
 # The directory remains REAL. Step 20 delegates final shared-vs-owned link
 # topology to `pj migrate hermes.runtime-singleton`; no template step may
 # replace the profile itself with a symlink.
+
+if [[ "${SKIP_HOST_STATE:-0}" == "1" ]]; then
+  printf '%s\n' '[10] Hermes profile — DEFERRED (SKIP_HOST_STATE=1)' >&2
+  exit 0
+fi
+
 # shellcheck source=_lib.sh
 source "$(dirname "$0")/_lib.sh"
 load_role_env
@@ -108,8 +114,56 @@ PYEOF
 fi
 
 # Never persist a project-specific terminal.cwd through the named profile.
-# PJangler intentionally links profile config.yaml to the fleet-shared config;
-# the generated launchers therefore pass TERMINAL_CWD process-locally instead.
+# The generated launchers pass TERMINAL_CWD process-locally instead.
+#
+# config.yaml is GENERATED, never hand-written and never a symlink to the fleet
+# base. It is deep_merge(~/.hermes/config.yaml, <profile>/config.delta.yaml).
+# The old symlink-to-base topology was actively harmful: Hermes' atomic writes
+# use os.replace, which REPLACES a symlink with a regular file, so the first
+# in-agent write (/model, onboarding, a config migration) silently detached the
+# profile onto a frozen copy of an old base — and a symlink gave the profile no
+# way to override anything in the first place.
+#
+# Seed an EMPTY delta: a new agent should be identical to the fleet base, and
+# every line here is an override someone must justify later.
+PROFILE_DELTA="$PROFILE_HOME/config.delta.yaml"
+if [[ ! -f "$PROFILE_DELTA" ]]; then
+  log "    seeding empty config.delta.yaml (override-only SSOT)"
+  cat > "$PROFILE_DELTA" <<'DELTA_EOF'
+# Override-only delta for this Hermes profile.
+# Merged over ~/.hermes/config.yaml to produce config.yaml (which is GENERATED).
+# Empty == identical to the fleet base. Add ONLY what must differ.
+{}
+DELTA_EOF
+  chmod 600 "$PROFILE_DELTA"
+fi
+
+# Pin the identity-memory bank explicitly rather than relying on the fleet
+# bank_id_template (agent-{profile}). {profile} resolves through Hermes'
+# get_active_profile_name(), which calls Path.resolve() on HERMES_HOME and
+# requires a lowercase id sitting directly under profiles/. A symlinked profile
+# dir or an uppercase name silently yields the literal "custom" — which would
+# merge this agent's PRIVATE memory into a bank shared with every other agent
+# that also failed to resolve.
+PROFILE_MEM_CFG="$PROFILE_HOME/hindsight/config.json"
+mkdir -p "$(dirname "$PROFILE_MEM_CFG")"
+if [[ ! -f "$PROFILE_MEM_CFG" ]]; then
+  log "    pinning identity-memory bank: agent-$PROFILE_NAME"
+  printf '{\n  "bank_id": "agent-%s"\n}\n' "$PROFILE_NAME" > "$PROFILE_MEM_CFG"
+  chmod 600 "$PROFILE_MEM_CFG"
+fi
+
+# Render config.yaml from base + delta when the renderer is available. Without
+# it the profile still boots (Hermes reads whatever config.yaml exists), but it
+# is not yet under inheritance and `pj audit` will say so.
+PROFILE_RENDERER="${PROFILE_RENDERER:-$HOME/code/33GOD/hermes-agent-template/scripts/hermes-profile-config.py}"
+if [[ -x "$PROFILE_RENDERER" || -f "$PROFILE_RENDERER" ]]; then
+  log "    rendering config.yaml from fleet base + delta"
+  python3 "$PROFILE_RENDERER" render --profile "$PROFILE_NAME" >/dev/null 2>&1 \
+    || warn "    render failed; run hermes-profile-config.py render --profile $PROFILE_NAME"
+else
+  warn "    profile renderer not found at $PROFILE_RENDERER — config.yaml not rendered"
+fi
 
 # Canonical shared-skill source of truth + local PM fallback sync.
 CANONICAL_SKILLS_DIR="${CANONICAL_SKILLS_DIR:-$(config_get fleet.canonical_skills_dir '/home/delorenj/.agents/skills')}"
@@ -117,8 +171,18 @@ CANONICAL_PM_SKILL_SRC="$CANONICAL_SKILLS_DIR/subagent-driven-development"
 LOCAL_PM_SKILL_DST="$PROFILE_HOME/skills/software-development/subagent-driven-development"
 
 if [[ -d "$CANONICAL_SKILLS_DIR" ]]; then
-  log "    setting skills.external_dirs[0] = $CANONICAL_SKILLS_DIR"
-  env HERMES_HOME="$PROFILE_HOME" "$HERMES_BIN" config set skills.external_dirs.0 "$CANONICAL_SKILLS_DIR"
+  # skills.external_dirs is a FLEET setting and already lives in
+  # ~/.hermes/config.yaml, so every rendered profile inherits it. Writing it
+  # per-profile here would (a) be redundant, and (b) write into the GENERATED
+  # config.yaml, where the next render discards it — the classic "I set it and
+  # it reverted" trap. Verify inheritance instead of re-asserting it.
+  if ! env HERMES_HOME="$PROFILE_HOME" "$HERMES_BIN" config get skills.external_dirs 2>/dev/null \
+       | grep -qF "$CANONICAL_SKILLS_DIR"; then
+    warn "    skills.external_dirs does not include $CANONICAL_SKILLS_DIR"
+    warn "    add it to the FLEET base (~/.hermes/config.yaml), then: hermes-profile-config.py render --all"
+  else
+    log "    skills.external_dirs inherited from fleet base: $CANONICAL_SKILLS_DIR"
+  fi
 
   # Ensure key PM/local-ops skills are symlinked into runtime/profile skills root.
   # This preserves canonical ownership and keeps updates instant across agents.

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

@@ -37,6 +37,59 @@ if [[ "${SKIP_SYSTEMD:-0}" == "1" ]]; then
   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
@@ -101,49 +154,26 @@ chmod +x "$HEARTBEAT_BIN" "$CREDENTIAL_LAUNCHER" "$ROLE_DIR/.scripts/checkpoint.
 [[ -d "$PROFILE_HOME" && ! -L "$PROFILE_HOME" ]] \
   || die "named profile is not a real directory; run: pj migrate hermes.runtime-singleton '$REPO_ROOT'"
 
-# Encrypted credentials are optional and take precedence over the existing
-# ignored runtime/.env fallback. Their plaintext appears only below /run while
-# systemd executes the unit. Files are provisioned separately with
-# `systemd-creds encrypt --user`; this step never reads or writes secret values.
-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=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=model_api_key:$MODEL_CREDENTIAL"
-  HB_CREDENTIAL_LINES="LoadCredentialEncrypted=model_api_key:$MODEL_CREDENTIAL"
-fi
-
 # Gateway unit
 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=$PROFILE_HOME
-Environment=HERMES_BIN=$HERMES_BIN
-Environment=CODEX_HOME=$CODEX_HOME
-Environment="TERMINAL_CWD=$REPO_ROOT"
-EnvironmentFile=-$RUNTIME/.env
+$ENV_HERMES_HOME
+$ENV_HERMES_BIN
+$ENV_CODEX_HOME
+$ENV_TERMINAL_CWD
+EnvironmentFile=$RUNTIME_ENV_FILE
 $GW_CREDENTIAL_LINES
-ExecStart=$CREDENTIAL_LAUNCHER gateway
+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
@@ -155,31 +185,31 @@ UNIT
 # The per-agent EnvironmentFiles load ticket-provider creds for the sentinel pass.
 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=$PROFILE_HOME
-Environment=HERMES_BIN=$HERMES_BIN
-Environment=CODEX_HOME=$CODEX_HOME
-Environment="TERMINAL_CWD=$REPO_ROOT"
+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
+EnvironmentFile=$RUNTIME_ENV_FILE
 $HB_CREDENTIAL_LINES
-ExecStart=$CREDENTIAL_LAUNCHER heartbeat
+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

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

@@ -144,12 +144,50 @@ clear_done() {
   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
@@ -190,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=""
 }
@@ -202,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 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.
@@ -255,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/heartbeat.sh

@@ -20,12 +20,24 @@ 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")"