levnikolaevich/ln-033-hex-relay-lifecycle

<!-- markdownlint-disable MD012 MD022 MD032 MD040 MD041 MD060 -->

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

| Direction | Content | |---|---| | Input | mode, project/VPS variables, Telegram variables, optional declared users, optional dry_run, optional runId, optional summaryArtifactPath | | Output | vps-hex-relay-lifecycle summary with status, changes, warnings, blockers, verification, and artifact paths |

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

| Mode | Behavior | |---|---| | initial_deploy | Deploy agents/hex-relay/ into an existing project runtime | | redeploy | Replace source on VPS, rebuild, restart service, verify health | | verify_only | Inspect service, DB, hooks, Telegram command state without mutation | | sync_users | Reconcile declared Telegram users/roles through supported relay state |

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