@delorenj/pjangler 1.4.2 → 1.4.3

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

@@ -24,10 +24,6 @@ fi
 # shellcheck source=_lib.sh
 source "$(dirname "$0")/_lib.sh"
 load_role_env
-# shellcheck source=lib/ticket-provider.sh
-source "$(dirname "$0")/lib/ticket-provider.sh"
-
-already_done 42-ticket-provider && { log "[42] ticket provider already set up — skipping"; exit 0; }
 
 # Locate the repo-root .project.json (the SOT).
 REPO_ROOT="$(project_repo_path 2>/dev/null || true)"
@@ -35,15 +31,59 @@ REPO_ROOT="$(project_repo_path 2>/dev/null || true)"
 PROJECT_JSON="$REPO_ROOT/.project.json"
 ROLE_DIR_REL="${ROLE_DIR#"$REPO_ROOT"/}"
 
+# Serialize the complete read / provider check-or-create / atomic write
+# transaction per project.  The lock lives outside the checkout so a normal
+# provision cannot leave repository dirt behind.
+command -v flock >/dev/null 2>&1 \
+  || die "flock is required for safe ticket-provider binding"
+PROJECT_LOCK_KEY="$(printf '%s' "$PROJECT_JSON" | sha256sum)"
+PROJECT_LOCK_KEY="${PROJECT_LOCK_KEY%% *}"
+PROJECT_LOCK_DIR="${XDG_RUNTIME_DIR:-${TMPDIR:-/tmp}}/pjangler-ticket-provider"
+mkdir -p "$PROJECT_LOCK_DIR"
+PROJECT_LOCK_FILE="$PROJECT_LOCK_DIR/$PROJECT_LOCK_KEY.lock"
+[[ ! -L "$PROJECT_LOCK_FILE" ]] \
+  || die "refusing ticket-provider lock symlink: $PROJECT_LOCK_FILE"
+exec {PROJECT_LOCK_FD}>"$PROJECT_LOCK_FILE"
+chmod 600 "$PROJECT_LOCK_FILE"
+flock -w "${PROJECT_LOCK_TIMEOUT_SECONDS:-30}" "$PROJECT_LOCK_FD" \
+  || die "timed out waiting for ticket-provider lock: $PROJECT_JSON"
+project_lock_release() {
+  flock -u "$PROJECT_LOCK_FD" 2>/dev/null || true
+  exec {PROJECT_LOCK_FD}>&-
+}
+trap project_lock_release EXIT
+
+[[ ! -L "$PROJECT_JSON" ]] || die "refusing .project.json symlink: $PROJECT_JSON"
+if [[ -e "$PROJECT_JSON" ]]; then
+  python3 - "$PROJECT_JSON" <<'PY' \
+    || die "malformed .project.json; refusing ticket-provider mutation or board creation"
+import json
+import pathlib
+import sys
+
+path = pathlib.Path(sys.argv[1])
+try:
+    value = json.loads(path.read_text(encoding="utf-8"))
+except (OSError, UnicodeError, json.JSONDecodeError):
+    raise SystemExit(1)
+raise SystemExit(0 if isinstance(value, dict) else 1)
+PY
+fi
+
+# shellcheck source=lib/ticket-provider.sh
+source "$(dirname "$0")/lib/ticket-provider.sh"
+
+already_done 42-ticket-provider \
+  && log "[42] ticket-provider marker found — revalidating canonical board binding"
+
 # pj <dotted.key> — read a string value from .project.json (empty if absent).
 pj() {
   [ -f "$PROJECT_JSON" ] || { printf ''; return 0; }
   python3 - "$PROJECT_JSON" "$1" <<'PY'
 import sys, json, pathlib
-try:
-    d = json.loads(pathlib.Path(sys.argv[1]).read_text())
-except Exception:
-    print(""); raise SystemExit(0)
+d = json.loads(pathlib.Path(sys.argv[1]).read_text(encoding="utf-8"))
+if not isinstance(d, dict):
+    raise SystemExit(".project.json root must be an object")
 cur = d
 for k in sys.argv[2].split("."):
     if isinstance(cur, dict) and k in cur:
@@ -55,19 +95,63 @@ PY
 }
 
 # pj_write — merge board binding (optional) + this agent into .project.json.
-# args: set_provider(0|1) provider board_id board_url workspace identifier team
+# args: set_provider(0|1) provider board_id workspace identifier team
+#       identifier_source
+#
+# identifier_source is REQUIRED whenever identifier is non-empty and must be
+# `provider` (read back out of the provider's own response) or `proposed` (a
+# local prefix the provider never confirmed, e.g. the string Trello echoes back
+# because Trello mints no key). There is deliberately no third option and no
+# default: an unstamped identifier is refused outright, so no locally-computed
+# string can ever land in .project.json wearing the authority of a live board.
+#
+# `provider` is further refused outright for a provider that assigns no
+# identifiers at all. Trello cannot have named a key it has no concept of, so
+# the claim is not merely unproven, it is impossible — and a downstream reader
+# must always be able to tell "Plane assigned PJAN" from "we picked INT and
+# Trello confirmed a board exists".
+#
+# Those are two different facts, so they get two different fields. Whether the
+# BOARD is real is stamped in board_confirmed_at, and that is what a link rests
+# on; whether the KEY came from the provider is identifier_source. Every
+# provider can answer the first. Only some can answer the second.
 pj_write() {
   REPO="$REPO" REPO_ROOT="$REPO_ROOT" AGENT_ID="$AGENT_ID" ROLE="$ROLE" \
   ROLE_DIR_REL="$ROLE_DIR_REL" PROJECT_DESC="${PROJECT_DESC:-}" \
   python3 - "$PROJECT_JSON" "$@" <<'PY'
-import sys, os, json, pathlib
-(path, set_provider, provider, board_id, board_url, workspace, identifier, team) = sys.argv[1:9]
+import datetime
+import errno
+import sys, os, json, pathlib, stat, tempfile
+(path, set_provider, provider, board_id, workspace, identifier, team,
+ identifier_source) = sys.argv[1:9]
+# Providers that mint their own keys and hand them back on read.
+IDENTIFIER_ASSIGNING = ("plane", "linear")
+if identifier and identifier_source not in ("provider", "proposed"):
+    raise SystemExit(
+        "refusing to persist ticket_provider.identifier %r with source %r: "
+        "every identifier must be stamped provider|proposed" % (identifier, identifier_source)
+    )
+if identifier_source == "provider" and provider not in IDENTIFIER_ASSIGNING:
+    raise SystemExit(
+        "refusing to persist ticket_provider.identifier %r as provider-sourced: "
+        "%s assigns no identifiers, so it cannot have named one" % (identifier, provider)
+    )
+now = (
+    datetime.datetime.now(datetime.timezone.utc)
+    .isoformat(timespec="milliseconds")
+    .replace("+00:00", "Z")
+)
 p = pathlib.Path(path)
-try:
-    d = json.loads(p.read_text())
+if p.is_symlink():
+    raise SystemExit(f"refusing .project.json symlink: {p}")
+if p.exists():
+    try:
+        d = json.loads(p.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        raise SystemExit(f"malformed .project.json: {type(exc).__name__}")
     if not isinstance(d, dict):
-        d = {}
-except Exception:
+        raise SystemExit(".project.json root must be an object")
+else:
     d = {}
 repo = os.environ.get("REPO", "")
 d.setdefault("project_name", repo)
@@ -78,10 +162,22 @@ if set_provider == "1":
     tp = d.setdefault("ticket_provider", {})
     tp["type"] = provider
     if workspace:  tp["workspace"] = workspace
-    if identifier: tp["identifier"] = identifier
-    if board_id:   tp["board_id"] = board_id
-    if board_url:  tp["board_url"] = board_url
+    if identifier:
+        tp["identifier"] = identifier
+        tp["identifier_source"] = identifier_source
+        if identifier_source == "provider":
+            tp["identifier_fetched_at"] = now
+        else:
+            tp.pop("identifier_fetched_at", None)
+    if board_id:
+        tp["board_id"] = board_id
+        # Every caller that reaches here with a board id got it out of the
+        # provider itself (create_board or resolve), so this write IS the
+        # confirmation and may stamp its own instant.
+        tp["board_confirmed_at"] = now
     if team:       tp["team"] = team
+    tp.pop("board_url", None)
+    tp["state"] = "linked" if board_id else "deferred"
 ag = d.setdefault("agents", {})
 entry = ag.get(os.environ["AGENT_ID"], {})
 if not isinstance(entry, dict):
@@ -89,21 +185,46 @@ if not isinstance(entry, dict):
 entry.update({
     "role": os.environ["ROLE"],
     "role_dir": os.environ["ROLE_DIR_REL"],
-    "provisioning_state": "provisioned",
+    "provisioning_state": "linked" if board_id else "deferred",
 })
 ag[os.environ["AGENT_ID"]] = entry
-p.write_text(json.dumps(d, indent=2) + "\n")
+rendered = json.dumps(d, indent=2) + "\n"
+p.parent.mkdir(parents=True, exist_ok=True)
+mode = stat.S_IMODE(p.stat().st_mode) if p.exists() else 0o644
+fd, temporary = tempfile.mkstemp(prefix=f".{p.name}.ticket-provider-", dir=p.parent)
+try:
+    os.fchmod(fd, mode)
+    with os.fdopen(fd, "w", encoding="utf-8") as handle:
+        handle.write(rendered)
+        handle.flush()
+        os.fsync(handle.fileno())
+    os.replace(temporary, p)
+    unsupported = {errno.EINVAL, getattr(errno, "ENOTSUP", errno.EINVAL), errno.ENOSYS}
+    directory_fd = os.open(p.parent, os.O_RDONLY | getattr(os, "O_DIRECTORY", 0))
+    try:
+        try:
+            os.fsync(directory_fd)
+        except OSError as exc:
+            if exc.errno not in unsupported:
+                raise
+    finally:
+        os.close(directory_fd)
+except BaseException:
+    try:
+        os.unlink(temporary)
+    except FileNotFoundError:
+        pass
+    raise
 PY
   log "    .project.json updated (agent=$AGENT_ID)"
 }
 
 # Mirror the binding into role.yaml so legacy consumers keep working.
 mirror_to_role_yaml() {
-  # mirror_to_role_yaml <provider> <board_id> <board_url> <workspace> <identifier> <team>
-  local provider="$1" bid="$2" burl="$3" ws="$4" ident="$5" team="$6"
+  # mirror_to_role_yaml <provider> <board_id> <workspace> <identifier> <team>
+  local provider="$1" bid="$2" ws="$3" ident="$4" team="$5"
   yaml_set ticket_provider.name "$provider" 2>/dev/null || true
   [ -n "$bid" ]  && yaml_set ticket_provider.board_id "$bid" 2>/dev/null || true
-  [ -n "$burl" ] && yaml_set ticket_provider.board_url "$burl" 2>/dev/null || true
   case "$provider" in
     plane)
       [ -n "$bid" ] && echo "$bid" > "$ROLE_DIR/.scripts/.plane-project-id"
@@ -125,9 +246,9 @@ mirror_to_role_yaml() {
 # An existing repo board (in .project.json) wins — every agent binds to it.
 SOT_TYPE="$(pj ticket_provider.type)"
 SOT_BOARD_ID="$(pj ticket_provider.board_id)"
-SOT_URL="$(pj ticket_provider.board_url)"
 SOT_WS="$(pj ticket_provider.workspace)"
 SOT_IDENT="$(pj ticket_provider.identifier)"
+SOT_IDENT_SOURCE="$(pj ticket_provider.identifier_source)"
 SOT_TEAM="$(pj ticket_provider.team)"
 
 # role.yaml provider comes from copier --data (the operator's pjangler choice).
@@ -140,8 +261,30 @@ if [ -n "$SOT_BOARD_ID" ]; then
     warn "[42] requested provider '$ROLE_PROVIDER' but repo board is '$PROVIDER' (.project.json wins); binding to existing board"
   fi
   log "[42] binding $AGENT_ID to existing repo board (provider=$PROVIDER, id=$SOT_BOARD_ID)"
-  mirror_to_role_yaml "$PROVIDER" "$SOT_BOARD_ID" "$SOT_URL" "$SOT_WS" "$SOT_IDENT" "$SOT_TEAM"
-  pj_write 0 "$PROVIDER" "" "" "" "" ""   # register agent only; board already recorded
+  LIVE_IDENT="$SOT_IDENT"
+  # An identifier already sitting in .project.json is only as trustworthy as
+  # the source recorded beside it. A record written before sources existed
+  # carries none, and an unsourced identifier is a proposal — not a fact.
+  IDENT_SOURCE=""
+  [ -z "$LIVE_IDENT" ] || IDENT_SOURCE="${SOT_IDENT_SOURCE:-proposed}"
+  # …and a `provider` stamp beside a provider that assigns no identifiers is
+  # not evidence either. It is a stale claim from a writer that conflated
+  # "the board is confirmed" with "the provider named this key". Correct it
+  # on the way through rather than carrying the lie into another manifest.
+  case "$PROVIDER" in
+    plane|linear) ;;
+    *) if [ "$IDENT_SOURCE" = provider ]; then IDENT_SOURCE=proposed; fi ;;
+  esac
+  if [ "$PROVIDER" = plane ]; then
+    OUT="$(tp resolve)" || die "existing Plane board could not be validated"
+    LIVE_IDENT="$(printf '%s' "$OUT" | python3 -c 'import sys,json
+try: print(str(json.load(sys.stdin).get("identifier") or ""))
+except Exception: print("")')"
+    [ -n "$LIVE_IDENT" ] || die "existing Plane board has no authoritative live identifier"
+    IDENT_SOURCE=provider
+  fi
+  mirror_to_role_yaml "$PROVIDER" "$SOT_BOARD_ID" "$SOT_WS" "$LIVE_IDENT" "$SOT_TEAM"
+  pj_write 1 "$PROVIDER" "$SOT_BOARD_ID" "$SOT_WS" "$LIVE_IDENT" "$SOT_TEAM" "$IDENT_SOURCE"
   mark_done 42-ticket-provider
   exit 0
 fi
@@ -150,10 +293,14 @@ fi
 PROVIDER="${ROLE_PROVIDER:-${SOT_TYPE:-plane}}"
 log "[42] no board in .project.json — bootstrapping a repo board (provider: $PROVIDER)"
 
-# Repo-based identity, matching CommonProject's scheme (slug[:4] uppercased).
-RAW=$(printf '%s' "$REPO" | tr -cd '[:alnum:]' | tr '[:lower:]' '[:upper:]')
-while [ ${#RAW} -lt 2 ]; do RAW="${RAW}X"; done
-IDENT="${SOT_IDENT:-${RAW:0:4}}"
+# Identifier PROPOSAL for a brand-new board only. It is sent to the provider in
+# the create request and is NEVER persisted as though it were confirmed: every
+# write below uses LIVE_IDENT, taken from the provider's own response, carrying
+# the source that response earns it (`provider` where the provider mints the
+# identifier, `proposed` where — as with Trello — it only echoes ours back).
+PROPOSED_RAW=$(printf '%s' "$REPO" | tr -cd '[:alnum:]' | tr '[:lower:]' '[:upper:]')
+while [ ${#PROPOSED_RAW} -lt 2 ]; do PROPOSED_RAW="${PROPOSED_RAW}X"; done
+PROPOSED_IDENT="${SOT_IDENT:-${PROPOSED_RAW:0:4}}"
 # Board NAME = repo name, separators->space, title-cased. NOT display_name —
 # display_name carries the role suffix and must never become the board name.
 NAME="$(printf '%s' "$REPO" | tr '_-' '  ' | python3 -c 'import sys; print(" ".join(w[:1].upper()+w[1:] for w in sys.stdin.read().split()))')"
@@ -161,24 +308,28 @@ DESC="Ticket board for $REPO"
 
 case "$PROVIDER" in
   linear)
+    # Linear DOES mint an authoritative identifier — the team key — so nothing
+    # here ever persists the local proposal. Without a live team read there is
+    # no identifier to record, and the record simply carries none.
     if [[ -z "${LINEAR_API_KEY:-}" ]]; then
       warn "[42] LINEAR_API_KEY not set; set role.yaml/.project.json ticket_provider.team and re-run ./.scripts/42-ticket-provider.sh"
-      pj_write 1 linear "" "" "" "$IDENT" "$SOT_TEAM"
+      pj_write 1 linear "" "" "" "$SOT_TEAM" ""
       mark_done 42-ticket-provider; exit 0
     fi
     OUT="$(tp resolve 2>/dev/null || true)"
     BID="$(printf '%s' "$OUT" | python3 -c 'import sys,json
 try: print(json.load(sys.stdin).get("board_id",""))
 except Exception: print("")')"
-    BURL="$(printf '%s' "$OUT" | python3 -c 'import sys,json
-try: print(json.load(sys.stdin).get("board_url",""))
+    LIVE_IDENT="$(printf '%s' "$OUT" | python3 -c 'import sys,json
+try: print(str(json.load(sys.stdin).get("identifier") or ""))
 except Exception: print("")')"
     if [ -n "$BID" ]; then
-      mirror_to_role_yaml linear "$BID" "$BURL" "" "$IDENT" "$SOT_TEAM"
-      pj_write 1 linear "$BID" "$BURL" "" "$IDENT" "$SOT_TEAM"
+      [ -n "$LIVE_IDENT" ] || die "linear resolved a team with no authoritative key"
+      mirror_to_role_yaml linear "$BID" "" "$LIVE_IDENT" "$SOT_TEAM"
+      pj_write 1 linear "$BID" "" "$LIVE_IDENT" "$SOT_TEAM" provider
     else
       warn "[42] linear resolve returned no board; set ticket_provider.team and re-run"
-      pj_write 1 linear "" "" "" "$IDENT" "$SOT_TEAM"
+      pj_write 1 linear "" "" "" "$SOT_TEAM" ""
     fi
     ;;
 
@@ -186,16 +337,34 @@ except Exception: print("")')"
     KEYVAR=PLANE_API_KEY; [ "$PROVIDER" = trello ] && KEYVAR=TRELLO_KEY
     if [[ -z "${!KEYVAR:-}" ]]; then
       warn "[42] $KEYVAR not set; skipping board creation. Set creds and re-run ./.scripts/42-ticket-provider.sh"
-      pj_write 1 "$PROVIDER" "" "" "${SOT_WS:-$PLANE_WORKSPACE}" "$IDENT" ""
+      # Deferred: no board was created, so there is no confirmed identifier.
+      # Persist nothing rather than freezing the proposal into .project.json.
+      pj_write 1 "$PROVIDER" "" "${SOT_WS:-$PLANE_WORKSPACE}" "" "" ""
       mark_done 42-ticket-provider; exit 0
     fi
-    OUT="$(tp create_board "$NAME" "$IDENT" "$DESC")" || die "create_board failed for $PROVIDER"
+    OUT="$(tp create_board "$NAME" "$PROPOSED_IDENT" "$DESC")" || die "create_board failed for $PROVIDER"
     BID="$(printf '%s' "$OUT" | python3 -c 'import sys,json; print(json.load(sys.stdin).get("board_id",""))')"
-    BURL="$(printf '%s' "$OUT" | python3 -c 'import sys,json; print(json.load(sys.stdin).get("board_url",""))')"
+    LIVE_IDENT="$(printf '%s' "$OUT" | python3 -c 'import sys,json; print(json.load(sys.stdin).get("identifier","") or "")')"
     WS="${SOT_WS:-$PLANE_WORKSPACE}"
     [ "$PROVIDER" = trello ] && WS=""
-    mirror_to_role_yaml "$PROVIDER" "$BID" "$BURL" "$WS" "$IDENT" ""
-    pj_write 1 "$PROVIDER" "$BID" "$BURL" "$WS" "$IDENT" ""
+    case "$PROVIDER" in
+      plane)
+        # Plane mints the identifier and hands it back on create; anything else
+        # is a guess and must not be written.
+        [ -n "$LIVE_IDENT" ] \
+          || die "created/bound Plane board has no authoritative live identifier"
+        IDENT_SOURCE=provider
+        ;;
+      trello)
+        # Trello mints no key. create_board echoes back the prefix it was
+        # handed, which confirms what the board is BOUND under — not a value
+        # Trello chose. Record it stamped as the proposal it is, so nothing
+        # downstream can read it as provider truth.
+        IDENT_SOURCE=proposed
+        ;;
+    esac
+    mirror_to_role_yaml "$PROVIDER" "$BID" "$WS" "$LIVE_IDENT" ""
+    pj_write 1 "$PROVIDER" "$BID" "$WS" "$LIVE_IDENT" "" "$IDENT_SOURCE"
     ;;
 
   *) die "unknown ticket provider: $PROVIDER (expected linear|plane|trello)" ;;

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

@@ -8,6 +8,8 @@ load_role_env
 if [[ "$ROLE" == "reporter" ]]; then
   log "[70] reporter systemd — gateway/consumer intentionally not installed"
   log "    use the reporter runtime's explicit install command after credential and policy preflight"
+  yaml_upsert_block_value service_state gateway not-applicable
+  yaml_upsert_block_value service_state heartbeat not-applicable
   mark_done 70-systemd
   exit 0
 fi
@@ -18,6 +20,7 @@ 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"
@@ -37,6 +40,19 @@ if [[ "${SKIP_SYSTEMD:-0}" == "1" ]]; then
   exit 0
 fi
 
+# Legacy manifests defaulted reconciliation off and had no way to distinguish
+# that default from an operator decision. The new explicit_opt_out sentinel is
+# authoritative: migrate unmarked roles to the operational PM default, while a
+# rendered/operator-recorded opt-out remains checkpoint-only on every rerun.
+if [[ "$(yaml_get reconcile.explicit_opt_out)" == "true" ]]; then
+  yaml_upsert_block_value reconcile enabled false bool
+  log "    PM reconciliation explicit opt-out preserved"
+else
+  yaml_upsert_block_value reconcile enabled true bool
+  yaml_upsert_block_value reconcile explicit_opt_out false bool
+  log "    PM reconciliation enabled (operational default)"
+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
@@ -72,19 +88,13 @@ HB_LOG_OUTPUT="$(systemd_scalar "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.
+# A model credential may be supplied through systemd's encrypted credential
+# store. Chat-channel values are never materialized here: Hermes resolves their
+# profile-scoped op:// references natively at process startup.
 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"
@@ -94,6 +104,42 @@ if [[ -f "$MODEL_CREDENTIAL" ]]; then
   HB_CREDENTIAL_LINES="LoadCredentialEncrypted=$(systemd_value "model_api_key:$MODEL_CREDENTIAL")"
 fi
 
+# A gateway is eligible only when at least one channel identity is verified AND
+# both the named-profile mapping and the referenced 1Password value resolve.
+# Role metadata alone is not sufficient: a stale done marker must never revive
+# a credential-less crash loop.
+gateway_ready=0
+gateway_validation_unavailable=0
+if [[ "$(yaml_get telegram.provisioning_status)" == "verified" ]] \
+   && profile_onepassword_ref_exists "$PROFILE_HOME" TELEGRAM_BOT_TOKEN; then
+  telegram_reference_rc=0
+  profile_onepassword_ref_validate "$PROFILE_HOME" TELEGRAM_BOT_TOKEN \
+    || telegram_reference_rc=$?
+  if [[ $telegram_reference_rc -eq 0 ]]; then
+    gateway_ready=1
+  elif [[ $telegram_reference_rc -eq 75 ]]; then
+    gateway_validation_unavailable=1
+  fi
+fi
+if [[ "$(yaml_get slack.provisioning_status)" == "verified" ]] \
+   && profile_onepassword_ref_exists "$PROFILE_HOME" SLACK_BOT_TOKEN \
+   && profile_onepassword_ref_exists "$PROFILE_HOME" SLACK_APP_TOKEN; then
+  slack_bot_reference_rc=0
+  slack_app_reference_rc=0
+  profile_onepassword_ref_validate "$PROFILE_HOME" SLACK_BOT_TOKEN \
+    || slack_bot_reference_rc=$?
+  profile_onepassword_ref_validate "$PROFILE_HOME" SLACK_APP_TOKEN \
+    || slack_app_reference_rc=$?
+  if [[ $slack_bot_reference_rc -eq 0 && $slack_app_reference_rc -eq 0 ]]; then
+    gateway_ready=1
+  elif [[ $slack_bot_reference_rc -eq 75 || $slack_app_reference_rc -eq 75 ]]; then
+    gateway_validation_unavailable=1
+  fi
+fi
+if [[ $gateway_ready -eq 0 && $gateway_validation_unavailable -eq 1 ]]; then
+  die "channel 1Password validation is temporarily unavailable; preserving existing gateway state for retry"
+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
@@ -159,11 +205,21 @@ chmod +x "$HEARTBEAT_BIN" "$CREDENTIAL_LAUNCHER" "$ROLE_DIR/.scripts/checkpoint.
   || die "named profile is not a real directory; run: pj migrate hermes.runtime-singleton '$REPO_ROOT'"
 
 # Gateway unit
+#
+# StartLimit* belongs in [Unit], not [Service] — systemd only still parses it
+# under [Service] for backwards compatibility. Without it, Restart=on-failure
+# retries forever and a gateway that can never start (bad token, bad config)
+# sits in `activating` indefinitely instead of settling into `failed`, so
+# `systemctl --user --failed` never lists it and neither the sentinel nor a
+# human ever sees the crashloop. That is exactly how the fleet accumulated
+# 10,427 invisible restarts. 5 tries in 5 minutes, then stop and report failed.
 cat > "$SYS_DIR/$GW_UNIT" <<UNIT
 [Unit]
 Description=$GW_DESCRIPTION
 After=network-online.target
 Wants=network-online.target
+StartLimitIntervalSec=300
+StartLimitBurst=5
 
 [Service]
 Type=simple
@@ -227,14 +283,72 @@ UNIT
 
 if systemd_user_available; then
   systemctl --user daemon-reload
-  # `enable --now` both enables (persist across login) AND starts the unit now, so a
-  # freshly provisioned agent comes up live instead of dormant. Units with missing
-  # creds (e.g. a gateway with no Telegram token yet) fail softly via Restart=on-failure.
-  for u in "$GW_UNIT" "$HB_TIMER"; do
-    systemctl --user enable --now "$u" >/dev/null 2>&1 && log "    enabled + started: $u" || warn "    failed to enable/start: $u"
-  done
+  if systemctl --user enable --now "$HB_TIMER" >/dev/null 2>&1; then
+    # The timer's first scheduled tick can be a minute away. Run the oneshot
+    # once now so deployment proves the heartbeat command itself completed;
+    # timer activity alone is not an operational postcondition.
+    if ! systemctl --user start "$HB_SVC" >/dev/null 2>&1; then
+      systemctl --user disable --now "$HB_TIMER" >/dev/null 2>&1 || true
+      yaml_upsert_block_value service_state heartbeat error
+      clear_done 70-systemd
+      die "required heartbeat oneshot failed its deployment probe: $HB_SVC"
+    fi
+    if hb_health="$(systemd_wait_for_stable_health \
+        systemd_timer_health_snapshot "$HB_TIMER" "$HB_SVC")"; then
+      yaml_upsert_block_value service_state heartbeat active
+      log "    heartbeat enabled + active with healthy latest result: $HB_TIMER"
+    else
+      systemctl --user disable --now "$HB_TIMER" >/dev/null 2>&1 || true
+      yaml_upsert_block_value service_state heartbeat error
+      clear_done 70-systemd
+      die "heartbeat did not stabilize healthy: $hb_health"
+    fi
+  else
+    yaml_upsert_block_value service_state heartbeat error
+    clear_done 70-systemd
+    die "failed to enable/start required heartbeat timer: $HB_TIMER"
+  fi
+
+  if [[ $gateway_ready -eq 1 ]]; then
+    if systemctl --user enable --now "$GW_UNIT" >/dev/null 2>&1; then
+      if gw_health="$(systemd_wait_for_stable_health \
+          systemd_service_health_snapshot "$GW_UNIT" running)"; then
+        yaml_upsert_block_value service_state gateway active
+        log "    credentialed gateway enabled + active and stabilized: $GW_UNIT"
+      else
+        systemctl --user disable --now "$GW_UNIT" >/dev/null 2>&1 || true
+        systemctl --user reset-failed "$GW_UNIT" >/dev/null 2>&1 || true
+        yaml_upsert_block_value service_state gateway error
+        clear_done 70-systemd
+        die "credentialed gateway did not stabilize healthy: $gw_health"
+      fi
+    else
+      yaml_upsert_block_value service_state gateway error
+      clear_done 70-systemd
+      die "failed to enable/start credentialed gateway: $GW_UNIT"
+    fi
+  else
+    systemctl --user disable --now "$GW_UNIT" >/dev/null 2>&1 \
+      || die "could not enforce deferred gateway disablement: $GW_UNIT"
+    systemctl --user reset-failed "$GW_UNIT" >/dev/null 2>&1 || true
+    gw_deferred_health="$(systemd_gateway_deferred_snapshot "$GW_UNIT")"
+    if [[ "$gw_deferred_health" == "ok|deferred" ]]; then
+      yaml_upsert_block_value service_state gateway deferred
+      log "    gateway deferred: disabled + inactive until a channel credential is verified"
+    else
+      yaml_upsert_block_value service_state gateway error
+      clear_done 70-systemd
+      die "gateway deferral was not proven disabled + inactive ($gw_deferred_health)"
+    fi
+  fi
 else
   warn "    systemd --user not available; units installed at $SYS_DIR but not enabled"
+  yaml_upsert_block_value service_state heartbeat installed
+  if [[ $gateway_ready -eq 1 ]]; then
+    yaml_upsert_block_value service_state gateway installed
+  else
+    yaml_upsert_block_value service_state gateway deferred
+  fi
 fi
 
 mark_done 70-systemd

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

@@ -40,8 +40,10 @@ python3 - "$REGISTRY_FILE" "$AGENT_ID" "$REPO" "$ROLE" "$DISPLAY_NAME" \
   "$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" \
-  "hermes-${AGENT_ID}-gateway.service" "hermes-${AGENT_ID}-heartbeat.timer" <<'PYEOF'
+  "hermes-${AGENT_ID}-gateway.service" "hermes-${AGENT_ID}-heartbeat.timer" \
+  "$(yaml_get service_state.gateway)" "$(yaml_get service_state.heartbeat)" <<'PYEOF'
 import datetime
+import copy
 import errno
 import os
 import pathlib
@@ -56,11 +58,17 @@ except ImportError:
  slack_status, slack_team_id, slack_team_name, slack_user_id, slack_bot_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:33]
+ hermes_git_ref, hermes_git_sha, fleet_env, gw, heartbeat,
+ gateway_state, heartbeat_state) = sys.argv[1:35]
 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": {}}
+data = yaml.safe_load(p.read_text(encoding="utf-8")) or {"schema_version": 1, "agents": {}}
+if not isinstance(data, dict):
+    raise SystemExit("fleet registry root must be a mapping")
+agents = data.setdefault("agents", {})
+if not isinstance(agents, dict):
+    raise SystemExit("fleet registry agents must be a mapping")
 if bloodbank_enabled == "":
     bloodbank_enabled_value = False
 elif bloodbank_enabled == "true":
@@ -69,7 +77,13 @@ 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] = {
+existing = agents.get(agent_id, {})
+if not isinstance(existing, dict):
+    raise SystemExit(f"fleet registry entry for {agent_id} must be a mapping")
+provisioned_at = existing.get("provisioned_at")
+if not isinstance(provisioned_at, str) or not provisioned_at:
+    provisioned_at = datetime.datetime.now(datetime.timezone.utc).isoformat().replace("+00:00", "Z")
+managed = {
   "repo": repo, "role": role, "display_name": display,
   "project_path": project, "role_dir": role_dir,
   "profile_name": profile,
@@ -101,9 +115,31 @@ data.setdefault("agents", {})[agent_id] = {
     "git_sha": hermes_git_sha,
     "fleet_env": fleet_env,
   },
-  "systemd": {"gateway_unit": gw, "heartbeat_timer": heartbeat},
-  "provisioned_at": datetime.datetime.now(datetime.timezone.utc).isoformat().replace("+00:00", "Z"),
+  "systemd": {
+    "gateway_unit": gw,
+    "heartbeat_timer": heartbeat,
+    "gateway_state": gateway_state,
+    "heartbeat_state": heartbeat_state,
+  },
+  "provisioned_at": provisioned_at,
 }
+
+def merge_managed(current, update):
+    result = copy.deepcopy(current)
+    for key, value in update.items():
+        if isinstance(value, dict) and isinstance(result.get(key), dict):
+            result[key] = merge_managed(result[key], value)
+        else:
+            result[key] = copy.deepcopy(value)
+    return result
+
+entry = merge_managed(existing, managed)
+# This is retired managed schema, not extension metadata.  Keeping it would
+# falsely advertise a second per-agent Bloodbank execution path.
+systemd = entry.get("systemd")
+if isinstance(systemd, dict):
+    systemd.pop("consumer_unit", None)
+agents[agent_id] = entry
 rendered = yaml.safe_dump(data, sort_keys=False)
 p.parent.mkdir(parents=True, exist_ok=True)