fix: improve gateway diagnostics

docs/gateway/doctor.md

@@ -47,8 +47,11 @@ cat ~/.clawdbot/clawdbot.json
 - Legacy config migration and normalization.
 - Legacy on-disk state migration (sessions/agent dir/WhatsApp auth).
 - State integrity and permissions checks (sessions, transcripts, state dir).
+- Legacy workspace dir detection (`~/clawdis`, `~/clawdbot`).
 - Sandbox image repair when sandboxing is enabled.
 - Legacy service migration and extra gateway detection.
+- Gateway runtime checks (service installed but not running; cached launchd label).
+- Gateway port collision diagnostics (default `18789`).
 - Security warnings for open DM policies.
 - systemd linger check on Linux.
 - Writes updated config + wizard metadata.
@@ -140,11 +143,17 @@ workspace.
 Doctor runs a health check and offers to restart the gateway when it looks
 unhealthy.
 
-### 11) Config write + wizard metadata
+### 11) Gateway runtime + port diagnostics
+Doctor inspects the daemon runtime (PID, last exit status) and warns when the
+service is installed but not actually running. It also checks for port collisions
+on the gateway port (default `18789`) and reports likely causes (gateway already
+running, SSH tunnel).
+
+### 12) Config write + wizard metadata
 Doctor persists any config changes and stamps wizard metadata to record the
 doctor run.
 
-### 12) Workspace tips (backup + memory system)
+### 13) Workspace tips (backup + memory system)
 Doctor suggests a workspace memory system when missing and prints a backup tip
 if the workspace is not already under git.
 

docs/gateway/index.md

@@ -171,6 +171,7 @@ clawdbot daemon restart
 Notes:
 - `daemon status` probes the Gateway RPC by default (same URL/token defaults as `gateway status`).
 - `daemon status --deep` adds system-level scans (LaunchDaemons/system units).
+- `daemon status` now reports runtime state (PID/exit status) and port collisions when the gateway isn’t reachable.
 - `gateway install|uninstall|start|stop|restart` remain supported as aliases; `daemon` is the dedicated manager.
 - `gateway daemon status` is an alias for `clawdbot daemon status`.
 - If other gateway-like services are detected, the CLI warns. We recommend **one gateway per machine**; one gateway can host multiple agents.

docs/gateway/troubleshooting.md

@@ -9,6 +9,36 @@ When your CLAWDBOT misbehaves, here's how to fix it.
 
 ## Common Issues
 
+### Service Installed but Nothing is Running
+
+If the gateway service is installed but the process exits immediately, the daemon
+can appear “loaded” while nothing is running.
+
+**Check:**
+```bash
+clawdbot daemon status
+clawdbot doctor
+```
+
+Doctor/daemon will show runtime state (PID/last exit) and log hints.
+
+**Logs:**
+- macOS: `~/.clawdbot/logs/gateway.log` and `gateway.err.log`
+- Linux: `journalctl --user -u clawdbot-gateway.service -n 200 --no-pager`
+- Windows: `schtasks /Query /TN "Clawdbot Gateway" /V /FO LIST`
+
+### Address Already in Use (Port 18789)
+
+This means something is already listening on the gateway port.
+
+**Check:**
+```bash
+clawdbot daemon status
+```
+
+It will show the listener(s) and likely causes (gateway already running, SSH tunnel).
+If needed, stop the service or pick a different port.
+
 ### "Agent was aborted"
 
 The agent was interrupted mid-response.