kilo-and-hosting-fixes

name	kilo-and-hosting-fixes
description	Skill to systematically diagnose and fix Kilo extension errors and to repair servers running on Hostinger VPS (Docker), generic Docker hosts, and Oracle Cloud instances.

Kilo & Hosting Fixes

Purpose: provide a repeatable workflow to diagnose and fix (A) Kilo extension errors in this codebase and (B) server issues on Hostinger VPS, Docker hosts, and Oracle Cloud VMs. Use when: kilo extension fails to load, runtime errors surface in kilo-mesh.cjs agents, or services are down on VPS/containers/cloud instances.

Prerequisites

• SSH or control-plane access to the host(s)
• Repo checkout and local logs (e.g., logs/, build/, core/) available
• Access to Docker CLI on hosts (or docker-compose) when relevant
• Oracle Cloud/Hostinger console credentials if cloud-side changes are required

Inputs (what the agent should request automatically)

• target: kilo | hostinger-vps | docker-host | oracle-vm
• access: SSH key or jump-host instructions (or readonly if only logs are provided)
• docker_compose_path (if using compose)
• service_name or container_name for targeted restarts
• recent_logs (last 200 lines from journalctl, docker logs, or agent logs)

Outputs

• A root-cause summary (one paragraph)
• A list of concrete remedial steps taken (commands run, files changed)
• Validation checks showing service healthy (commands and their successful outputs)

Workflow A — Fix Kilo extension errors

1. Gather context

   • Collect recent logs: logs/exec_log.ndjson, logs/*, and any runtime output from agent-system/agents/*.
   • Run local static checks: node --check (for JS files) or npm run lint if available.
   • Identify failing component (extension load, mesh connection, provider auth).

2. Quick pattern matching (decision points)

   • If error message contains Cannot find module → missing dependency or incorrect path. Check node_modules, package.json, and build artifacts.
   • If stack shows syntax errors or transpile issues → mismatch in Node version or broken build step. Check Node version and build/ outputs.
   • If runtime throws ERR_SOCKET / network errors → network or permission issue (see Workflow B).

3. Fix candidates

   • Missing deps: run npm ci or npm install in the package owning kilo (document exact package path), then re-run the failing command.
   • Build mismatch: run repo's build script (e.g., npm run build or ./scripts/kilo-build.sh), then restart service.
   • Node version: confirm node -v vs .nvmrc / engine field and use matching version.
   • Path mismatches: ensure require/import paths are correct relative to compiled output.

4. Validate

   • Reproduce the failing step and capture logs.
   • Run unit/test script if available for the target module.
   • Mark successful when extension loads and agent processes start without the original error for one full restart.

Workflow B — Fix servers on Hostinger VPS, Docker, and Oracle Cloud

1. Collect host facts

   • For Hostinger/Oracle, collect instance metadata (OS, kernel), public IP, firewall rules, and provider-level status.
   • On the host: uname -a, docker ps -a, docker-compose -f <path> config, systemctl status <service> (if systemd), ss -tuln.
   • Collect container logs: docker logs --tail 200 <container>.

2. Common decision branches

   • Containers not starting: check docker-compose config, environment variables, image pulls, registry auth.
   • Crash loops: inspect container logs for stack traces, check resource limits (memory), and restart policy.
   • Port conflicts / firewall: verify ss -tuln and provider security groups (VCN rules on Oracle, Hostinger panel settings).
   • Database or external service unreachable: verify network/DNS, service health, and any cloud NAT/firewall rules.

3. Remediation checklist (ordered)

   • Ensure Docker daemon running: sudo systemctl status docker → sudo systemctl restart docker if needed.
   • Recreate containers: docker-compose -f <path> down && docker-compose -f <path> pull && docker-compose -f <path> up -d --remove-orphans.
   • Clear problematic images: docker image prune -af (document before/after sizes).
   • If system resource limits hit: check df -h, free -m, and increase swap or disk as needed.
   • For Hostinger panel-specific issues: confirm domain pointing, reverse proxy settings, and their Docker app configuration if using Hostinger Docker.
   • For Oracle Cloud: verify VCN/Subnet, security list ingress/egress rules, and OCI instance agent status. Use OCI Console to check instance health.

4. Post-fix validation

   • docker ps shows desired containers running.
   • curl -fL http://localhost:<port>/health (or equivalent health endpoint) returns 200.
   • ss -tuln shows service listening on expected ports.

Common error signatures and quick fixes

• Cannot find module 'xxx': npm ci in correct package, confirm NODE_PATH or build artifacts
• EACCES binding port <1024: use non-privileged port or run via systemd with capability CAP_NET_BIND_SERVICE` or set up an external reverse proxy
• port already in use: find process with ss -tulpn | grep :<port> and stop/adjust
• Docker OOM: increase memory or reduce container memory limits

Quality Criteria / Completion checks

• All previously failing error messages no longer appear in the last 200 lines of logs after restart.
• Health endpoint(s) respond 2× consecutively within 30s.
• No new critical errors in journalctl or docker logs for 2 minutes after restart.

Files & artifacts to collect for human handoff

• docker-compose.yml (or compose overrides), Dockerfile, systemd unit files, nginx or reverse proxy config, provider console screenshots (security rules), and trimmed logs.

Example prompts to use with this skill

• "Diagnose Kilo extension load error: here's the last 200 lines of logs..."
• "Repair Hostinger VPS: docker-compose failing to start clawhub container; here's docker logs and docker-compose.yml"
• "Oracle VM networking problem: instance up but service unreachable; provide ss -tuln, iptables -L -n, and OCI security rules"

Clarifying questions (agent should ask these when missing)

• Which target should I operate on? kilo | hostinger-vps | docker-host | oracle-vm
• Do you have SSH access with sudo, or should I only analyze logs you provide?
• Which service_name or container should I prioritize?
• Which Node version and package manager (npm, pnpm, yarn) are used for kilo?

Next steps for iteration

1. If you provide logs and access, I can run the diagnostic commands and propose exact commands to execute.
2. If you'd like, I can generate a short runbook script (scripts/repair-kilo.sh) that automates the common fixes described above.

---

Created by agent-customization workflow. Try: Fix Kilo extension or Repair Hostinger VPS docker as prompts.