ln-034-vps-environment-diagnostics

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

Paths: File paths (shared/, ../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-034-vps-environment-diagnostics

Type: L3 Worker Category: 0XX Shared / Infrastructure

Inspects one VPS project environment and reports health, drift, logs, auth state, ports, systemd, tmux, and bounded safe repairs.

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/scope_layers.md, ../ln-030-vps-bootstrap/references/troubleshooting.md, and ../ln-030-vps-bootstrap/references/verification_recipes.md

---

Input / Output

Direction	Content
Input	mode, project/VPS variables, optional repair_scope, optional dry_run, optional runId, optional summaryArtifactPath
Output	vps-environment-diagnostics summary with status, findings, drift, safe repairs, warnings, blockers, and verification

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
inspect	Read-only health and drift report
verify	Read-only post-install/post-redeploy verification
repair_safe	Apply only documented bounded safe repairs selected by repair_scope

Workflow

Phase 1: Scope And Safety

Resolve target environment and set mutation guard:

• inspect and verify are read-only
• repair_safe requires explicit repair_scope
• dry_run=true converts repairs to planned actions

Phase 2: Host And Shared Runtime

Inspect:

• required binaries
• ${BOT_USER}
• Node/Claude/Codex versions
• auth health indicators without printing tokens
• ${AGENT_SKILLS_DIR} git state
• marketplace/plugin health
• agent-update.timer and log tail

Phase 3: Project Runtime

Inspect:

• ${PROJECT_DIR} git state
• /etc/${PROJECT_NAME} and /var/lib/${PROJECT_NAME}
• ${SERVICE_PREFIX}-god@*.service
• tmux socket and targets
• dispatch timer/service
• provider credential wiring without secret output

Phase 4: Relay Runtime

When Telegram/relay is enabled, inspect:

• ${SERVICE_PREFIX}-hex-relay.service
• /opt/${SERVICE_PREFIX}-hex-relay
• HTTP /health
• relay DB presence/schema
• old relay-bot service/path drift
• RELAY_HOOK_PORT listener collisions

Phase 5: Safe Repair

Allowed safe repairs only:

• restart a named inactive project service after confirming unit file exists
• re-enable an expected timer
• recreate missing non-secret directories with documented owner/mode
• rerun systemctl daemon-reload
• report, but do not rewrite, missing auth or secrets

Forbidden repairs:

• secret creation or token edits
• deleting DB files
• deleting project repos
• changing Git remotes/branches
• changing shared auth
• broad package upgrades

Phase 6: Summary

Write a vps-environment-diagnostics summary artifact with:

• health verdict
• drift list
• repair actions applied or planned
• blockers
• warnings
• verification evidence

Critical Rules

• This worker diagnoses one environment at a time.
• Fleet target selection belongs outside this worker.
• Read-only modes must not mutate remote or local state.
• Repair actions are bounded and explicit.
• Never print secrets or auth tokens.

Definition of Done

• [ ] Target environment and mutation guard resolved.
• [ ] Host/shared runtime health inspected.
• [ ] Project runtime health inspected.
• [ ] Relay runtime health inspected or gated N/A:.
• [ ] Drift and blockers reported with concrete evidence.
• [ ] Safe repair actions were explicit, bounded, and recorded.
• [ ] Forbidden repair categories were not performed.
• [ ] dry_run=true, inspect, and verify performed no mutation.
• [ ] Structured vps-environment-diagnostics summary artifact written.

---

Version: 1.0.0 Last Updated: 2026-05-05