# Queue Worker Production Runbook

Use this runbook for P4.2 queue and background job deployment. The worker is CLI-only and lives at `logs/queue_worker.php`.

## Recommended Production Modes

### VPS or Dedicated Server

Run one or more supervised daemon workers so queued OpenAI and messaging jobs are processed without waiting for web traffic.

```ini
[program:thesol-chat-queue]
command=/usr/bin/php /var/www/thesol-chat/logs/queue_worker.php --daemon --poll-ms=500
directory=/var/www/thesol-chat
autostart=true
autorestart=true
numprocs=2
process_name=%(program_name)s_%(process_num)02d
stdout_logfile=/var/log/thesol-chat/queue-worker.log
stderr_logfile=/var/log/thesol-chat/queue-worker-error.log
stopwaitsecs=30
```

### Shared Hosting or cPanel

Use cron batch mode when a persistent worker is not available.

```cron
* * * * * /usr/bin/php /home/account/public_html/Chatbot/logs/queue_worker.php --batch=30 >> /home/account/logs/thesol-queue-worker.log 2>&1
```

### Windows Server or XAMPP

Create a Task Scheduler task that runs every minute:

```powershell
D:\xampp\php\php.exe D:\xampp\htdocs\Chatbot\logs\queue_worker.php --batch=30
```

For a long-running Windows worker, use NSSM or the host's service wrapper with:

```powershell
D:\xampp\php\php.exe D:\xampp\htdocs\Chatbot\logs\queue_worker.php --daemon --poll-ms=500
```

## Cleanup And Retention

Run cleanup from cron or Task Scheduler. The command keeps recent completed and failed jobs and prints deleted counts for audit logs.

```cron
12 * * * * /usr/bin/php /var/www/thesol-chat/logs/queue_worker.php --cleanup --cleanup-hours=48 >> /var/log/thesol-chat/queue-cleanup.log 2>&1
```

Use `--cleanup-hours=48` as the production default unless the host needs a longer dead-letter investigation window. Recent failed jobs remain visible in the admin Queue tab until they pass the retention window or an admin retries/dismisses them.

Run OTP-only purge when the host separates queue retention from verification cleanup. This removes resolved OTP sessions and sessions older than the configured window without touching queue jobs.

```cron
42 * * * * /usr/bin/php /var/www/thesol-chat/logs/queue_worker.php --otp-purge --otp-purge-hours=24 >> /var/log/thesol-chat/otp-purge.log 2>&1
```

On Windows Task Scheduler, use:

```powershell
D:\xampp\php\php.exe D:\xampp\htdocs\Chatbot\logs\queue_worker.php --otp-purge --otp-purge-hours=24
```

Use a longer OTP purge window, such as `--otp-purge-hours=72`, only when support needs a larger audit window for failed verifications.

## Health Checks

Check queue status manually:

```bash
/usr/bin/php /var/www/thesol-chat/logs/queue_worker.php --stats
```

Operational expectations:

- `Pending` should return toward zero when workers are running.
- `Failed` should stay below the admin alert threshold.
- `Processing` should not remain stuck above zero for longer than `SB_QUEUE_WORKER_TIMEOUT`.
- Cleanup output should show exact deleted counts and should not remove recent failed jobs inside the configured retention window.
- OTP purge output should show deleted session counts, and the release smoke test should pass the OTP hash, purge, and rate-limit checks.
