hoatv2211 Multi-Service Local Environment Doctor
Overview
Build a read-only topology of services, processes, ports, and configuration, then identify collisions without starting or stopping anything.
When to use
Use for local server startup failures, port 27000 conflicts, MySQL 3306/3307 isolation, Redis or web listener issues, config drift, or multiple game stacks on one workstation.
When NOT to use
Do not use to kill processes, start services, edit configs, import databases, or claim a runtime is healthy from static config alone.
Required inputs and context discovery
Collect service names, executable or script paths, expected and configured hosts/ports, dependency order, process snapshot, listener snapshot, config files, project ownership, and forbidden service-control actions.
Safety and risk level
Read-only only. Process and port inspection is allowed; start, stop, kill, firewall, registry, database, and config changes require explicit approval and another workflow.
Workflow
- Inventory declared services and configuration sources. Completion criterion: each service has an owner, config path, expected host, and expected port.
- Capture active processes and listeners without controlling them. Completion criterion: observed listeners are a timestamped Snapshot.
- Compare expected, configured, and observed ports and dependencies. Completion criterion: collisions, missing listeners, and mismatches are separated.
- Identify cross-project ownership such as Project Alpha versus Project Beta and database port isolation. Completion criterion: no proposed fix crosses a project boundary silently.
- Recommend the smallest safe next action and label service-control work BLOCKED pending approval. Completion criterion: the report does not mutate the environment.
Evidence and output contract
Produce environment-report.json with services, configs, expected/observed listeners, conflicts, mismatches, ownership, limitations, and recommended next checks.
Handoff contract
Record service topology, commands used, process IDs only when necessary and sanitized, port conflicts, config paths, project owners, and blocked control actions.
Pitfalls and anti-rationalization
- A free port now may not be the configured port.
- A listening port does not prove the correct executable owns it.
- Do not reuse a DB port across projects because “only one runs at a time.”
- Do not stop unknown processes to make a test pass.
Verification checklist
- Expected, configured, and observed ports are distinct fields.
- Project ownership is explicit.
- No process or service was controlled.
- Static-only limitations are stated.
- Mutating next steps are BLOCKED pending approval.
References and scripts
Read references/commands.md for read-only Windows and Linux snapshots. Use the bundled scripts/environment_doctor.py for static topology and project-native read-only process/port commands for live snapshots.