# Port Conflict Resolution Feature

## Overview

Added automatic **port conflict detection and resolution** to the OpenClaw auto-login automation. When port 18789 is already in use, the system will automatically detect the conflicting process and terminate it before starting the gateway.

## Implementation

### New Functions Added

#### Python (`auto_login.py`)

1. **`find_process_using_port(port: int)`** - Cross-platform port usage detection
   - Windows: `netstat -ano` + `tasklist`
   - macOS: `lsof -i :port`
   - Linux: `ss -tlnp` (preferred) or `netstat -tlnp`

2. **`kill_process(pid: int)`** - Cross-platform process termination
   - Windows: `taskkill /F /PID`
   - Unix: `SIGTERM` (graceful) → `SIGKILL` (force)

3. **`resolve_port_conflict(port: int, force: bool)`** - Main resolution logic
   - Detects process using port
   - Optionally kills process
   - Verifies port is released

#### PowerShell (`auto-login.ps1`)

1. **`Find-ProcessUsingPort($Port)`** - Uses `Get-NetTCPConnection` + `netstat` fallback
2. **`Resolve-PortConflict($Port, $Force)`** - Terminates with `Stop-Process`

#### Bash (`auto-login.sh`)

1. **`find_process_using_port(port)`** - Uses `lsof` (macOS) or `ss`/`netstat` (Linux)
2. **`kill_process(pid)`** - Uses `taskkill` (Windows) or `kill`/`kill -9` (Unix)
3. **`resolve_port_conflict(port, force)`** - Main resolution logic

## Integration

### Before Starting Gateway

The port conflict resolution runs automatically before attempting to start the gateway:

```
[START] Starting OpenClaw gateway service...
   [INFO] Port 18789 is in use by node.exe (PID: 12345)
   [INFO] Attempting to terminate process...
   [OK] Process node.exe (PID: 12345) terminated, port 18789 is now available
```

### Cross-Platform Support

| Platform | Detection | Kill Method |
|----------|-----------|-------------|
| Windows | netstat, Get-NetTCPConnection | taskkill /F |
| macOS | lsof | kill, kill -9 |
| Linux | ss, netstat | kill, kill -9 |

## Usage

### Default Behavior (Auto-Kill Enabled)

```bash
openclaw-installer auto-login
# Automatically detects and kills port conflicts
```

### Disable Auto-Kill (Python API)

```python
from openclaw_installer.automation.auto_login import auto_login

# Disable port conflict resolution
auto_login(force_kill_conflicts=False)
```

## Testing

Run the test suite:

```bash
python test_automation.py
```

Test output:
```
Testing port conflict resolution...
  [OK] Port 18789 is available
  
Result: 7/7 tests passed
```

## Manual Port Check

### Windows
```powershell
# Check port usage
netstat -ano | findstr :18789

# Kill by PID
taskkill /F /PID <PID>
```

### macOS
```bash
# Check port usage
lsof -i :18789

# Kill by PID
kill <PID>
```

### Linux
```bash
# Check port usage
ss -tlnp sport = :18789

# Kill by PID
kill <PID>
```

## Error Handling

If the process cannot be killed:

```
[WARNING] Port 18789 is in use by system_process (PID: 1234)
[WARNING] Failed to terminate process system_process (PID: 1234)
[WARNING] Attempting to start anyway...
```

The gateway startup will still proceed, as OpenClaw may be able to bind to the port or use an alternative.

## Files Modified

- `openclaw_installer/automation/auto_login.py` - Core Python functions
- `openclaw_installer/automation/auto-login.ps1` - PowerShell functions
- `openclaw_installer/automation/auto-login.sh` - Bash functions
- `openclaw_installer/automation/README.md` - Documentation
- `test_automation.py` - Added port conflict tests
- `PORT_CONFLICT_RESOLUTION.md` - This summary
