Ln 034 Vps Environment Diagnostics

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

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: 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