Ln 033 Hex Relay Lifecycle

Paths: File paths (shared/, agents/hex-relay/, ../ln-030-vps-bootstrap/references/) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root.

ln-033-hex-relay-lifecycle

Type: L3 Worker Category: 0XX Shared / Infrastructure

Manages hex-relay as a standalone product deployed into one project environment.

MANDATORY READ

MANDATORY READ: Load shared/references/worker_runtime_contract.md, shared/references/coordinator_summary_contract.md, and shared/references/vps_runtime_contract.md MANDATORY READ: Load ../ln-030-vps-bootstrap/references/hex_relay_deploy.md, ../ln-030-vps-bootstrap/references/verification_recipes.md, agents/hex-relay/README.md, agents/hex-relay/docs/redeploy.md, and agents/hex-relay/docs/telegram-operator-runbook.md

Input / Output

If summaryArtifactPath is provided, write the same summary JSON there. If not provided, return the summary inline and write it to the standalone run-scoped path. Generate a standalone run_id when runId is absent.

Modes

Workflow

Phase 1: Preflight

Verify:

• Telegram is enabled for deploy/sync modes
• ${PROJECT_NAME}, ${SERVICE_PREFIX}, ${PROJECT_DIR}, ${RELAY_HOOK_PORT} are set
• project runtime exists
• /etc/${PROJECT_NAME}/secrets.env exists but secret values are not printed
• agents/hex-relay/ source is available locally

Phase 2: Compatibility

Use hex_relay_deploy.md.

Detect old ${SERVICE_PREFIX}-relay-bot.service and /opt/${SERVICE_PREFIX}-relay-bot.

Rule:

• disable or migrate old relay before enabling ${SERVICE_PREFIX}-hex-relay.service
• never run old and new relay units together

Phase 3: Deploy Or Redeploy

For initial_deploy, install:

• /opt/${SERVICE_PREFIX}-hex-relay
• ${SERVICE_PREFIX}-hex-relay.service
• project-scope hooks
• Telegram command registration

For redeploy, follow agents/hex-relay/docs/redeploy.md:

• package source without node_modules or dist
• upload source
• rebuild with npm ci && npm run build
• restart service

Phase 4: Users And Telegram

For sync_users, reconcile declared users without exposing tokens.

Verify:

• allowlist state
• per-user god target behavior
• /new_session, /sessions, /tasks, /users, /usage command availability
• BotFather hardening checklist status when applicable

Phase 5: Health

Verify:

• ${SERVICE_PREFIX}-hex-relay.service
• GET /health
• relay.db schema
• outbox/dispatch/todo state smoke
• final Claude reply mirrored through Stop hook when full smoke is requested

Phase 6: Summary

Write a vps-hex-relay-lifecycle summary artifact with deploy/redeploy/user-sync changes and health evidence.

Critical Rules

• hex-relay source is owned by agents/hex-relay/.
• Do not edit built dist/ on the VPS.
• Do not upload node_modules/.
• Do not print or store Telegram/provider token values.
• dry_run=true and verify_only do not mutate remote state.
• Product-specific behavior is documented in agents/hex-relay/README.md.

Definition of Done

• Telegram/relay gate evaluated and skipped as N/A: when disabled.
• Old relay-bot unit/path detected and disabled or reported before enabling hex-relay.
• /opt/${SERVICE_PREFIX}-hex-relay source installed or verified.
• ${SERVICE_PREFIX}-hex-relay.service active or planned.
• Product was built with npm ci && npm run build for deploy/redeploy.
• /health returns expected service and god-session fields.
• Telegram commands and declared users are verified or explicitly gated.
• dry_run=true / verify_only performed no mutation.
• Structured vps-hex-relay-lifecycle summary artifact written.

Version: 1.0.0 Last Updated: 2026-05-05