prose-contracts/zulip-resilience-v3.prose.md

---
kind: responsibility
name: zulip-resilience-v3
description: >
  Rewrite the pi Zulip gateway with production-grade resilience patterns drawn from
  Zulip's own event system docs (queue lifecycle, heartbeat monitoring, BAD_EVENT_QUEUE_ID
  handling, idle_queue_timeout) and battle-tested Node.js resilience patterns
  (circuit breaker, exponential backoff with jitter, bulkhead isolation, supervisor watchdog).
replaces: zulip-self-heal (retired)
agent: abiba
triggers:
  - "/zulip self-heal v3"
  - "zulip stopped responding"
  - "PM2 abiba-zulip crashed"
---

# Zulip Gateway v3 — Production Resilience

## Architecture Overview

The current v2 gateway (`/root/.pi/agent/extensions/zulip/index.js`) has three structural
weaknesses that cause repeated deaths:

1. **No crash recovery** — uncaught errors kill the Node process, PM2 exhausts max_restarts
2. **No circuit breaker** — 502/fetch-failed errors escalate to process death with no fallback
3. **No queue lifecycle management** — doesn't use Zulip's documented heartbeat protocol or
   idle_queue_timeout, so BAD_EVENT_QUEUE_ID errors cascade into crashes

The v3 rewrite addresses all three, following patterns from:

- [Zulip Events System docs](https://zulip.readthedocs.io/en/11.6/subsystems/events-system.html) —
  queue registration, heartbeat, BAD_EVENT_QUEUE_ID recovery, call_on_each_event loop
- [Zulip API: Get Events](https://zulip.com/api/get-events) — long-poll timeout, dont_block, event ack
- [Circuit Breaker & Retry Patterns in Node.js 2026](https://1xapi.com/blog/resilient-api-circuit-breaker-bulkhead-retry-nodejs-2026) —
  Opossum-based circuit breaker with fallback, retry with jitter, bulkhead isolation

---

## Maintains

- `zulip-gateway`: { status: "healthy" | "degraded" | "down" }
- `circuit-breaker`: { state: "CLOSED" | "OPEN" | "HALF_OPEN", failures, successes }
- `queue-lifecycle`: { queue_id, last_event_id, idle_timeout, heartbeat_age }
- `workers`: { count, busy, idle, stuck }
- `supervisor`: { pid, last_check, health_failures }

---

## Detection Rules

### Rule 1: Queue Expired (BAD_EVENT_QUEUE_ID)
- **Detect**: Events API returns error with BAD_EVENT_QUEUE_ID in body
- **Fix**: Call `POST /register` to create new queue, update queue_id and last_event_id
- **Debounce**: If 3 re-registrations fail within 60s, escalate (server may be down)
- **Ref**: Zulip docs: "Your software will need to handle that error condition by re-initializing itself"

### Rule 2: Network Degradation (502/ECONNREFUSED/fetch failed)
- **Detect**: Events API returns 502 or network error
- **Circuit breaker**: Track failure rate over 10s rolling window
  - CLOSED → OPEN: 50% failure rate with ≥5 requests
  - OPEN → HALF_OPEN: After 30s reset timeout
  - HALF_OPEN → CLOSED: Probe succeeds
  - HALF_OPEN → OPEN: Probe fails
- **While OPEN**: Log errors, skip events, notify user via DM: "⚠️ Zulip connection degraded — will retry in 30s"

### Rule 3: Long-Poll Timeout (natural)
- **Detect**: Events API response takes > `event_queue_longpoll_timeout_seconds`
- **Not an error**: Server sends heartbeat events when no real events. Simply re-poll.

### Rule 4: Worker Busy Timeout (>5 min)
- **Detect**: Worker `busySince` exceeds 5 minutes
- **Fix**: SIGKILL worker, send error DM, clean up pending replies

### Rule 5: Process Crash (uncaught)
- **Detect**: `uncaughtException` / `unhandledRejection` fires
- **Fix**: Log → clear poll timer → attempt reconnect with backoff → if reconnect fails 3x, exit(1) and let PM2 restart

### Rule 6: Supervisor Detects Router Stall
- **Detect**: External supervisor (`zulip-watchdog`) polls `/health` every 30s. If 3 consecutive failures:
- **Fix**: `pm2 restart abiba-zulip` gracefully (SIGTERM, drain workers, restart)

---

## Implementation Plan

### Phase 1: Rewrite Router Core (circuit-breaker + queue lifecycle)

Replace the poll loop in index.js with a resilience-first event loop:

```js
// Queue lifecycle (Zulip docs pattern)
async function createOrRefreshQueue() {
  // POST /register with event_types=["message"]
  // Store: queueId, lastEventId, eventQueueLongpollTimeoutSeconds
  // NEW: pass idle_queue_timeout parameter (Zulip 12.0+)
}

// Circuit breaker (Opossum pattern, implemented inline to avoid dependency)
class ZulipCircuitBreaker {
  constructor({ failureThreshold=0.5, resetTimeout=30000, volumeThreshold=5, windowMs=10000 }) {
    this.state = "CLOSED"; // CLOSED | OPEN | HALF_OPEN
    this.failures = 0;
    this.successes = 0;
    this.totalRequests = 0;
    this.lastFailureTime = null;
    this.openedAt = null;
    this.failureThreshold = failureThreshold;
    this.resetTimeout = resetTimeout;
    this.volumeThreshold = volumeThreshold;
    this.windowMs = windowMs;
  }

  async fire(fn) {
    if (this.state === "OPEN") {
      if (Date.now() - this.openedAt > this.resetTimeout) {
        this.state = "HALF_OPEN";
      } else {
        throw new CircuitOpenError("Circuit is OPEN");
      }
    }
    try {
      const result = await fn();
      this.onSuccess();
      return result;
    } catch (err) {
      this.onFailure();
      throw err;
    }
  }

  onSuccess() {
    this.successes++;
    this.totalRequests++;
    if (this.state === "HALF_OPEN") {
      this.state = "CLOSED";
      this.failures = 0;
    }
    // Reset counters periodically
    if (this.totalRequests > this.volumeThreshold * 2) {
      this.failures = Math.floor(this.failures / 2);
      this.successes = Math.floor(this.successes / 2);
      this.totalRequests = Math.floor(this.totalRequests / 2);
    }
  }

  onFailure() {
    this.failures++;
    this.totalRequests++;
    this.lastFailureTime = Date.now();
    if (this.totalRequests >= this.volumeThreshold &&
        this.failures / this.totalRequests >= this.failureThreshold) {
      if (this.state !== "OPEN") {
        this.state = "OPEN";
        this.openedAt = Date.now();
        console.error(`[zulip-ext] CIRCUIT BREAKER OPEN — ${this.failures}/${this.totalRequests} failures`);
      }
    }
  }
}

// Retry with exponential backoff + jitter (from resilience patterns)
async function withRetry(fn, { maxAttempts=3, baseDelay=200, maxDelay=10000, shouldRetry=()=>true }={}) {
  let lastError;
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (err) {
      lastError = err;
      if (attempt === maxAttempts || !shouldRetry(err)) throw err;
      const delay = Math.min(baseDelay * Math.pow(2, attempt - 1), maxDelay);
      const jitter = delay * (0.5 + Math.random() * 0.5); // 50-100% of delay
      console.warn(`[zulip-ext] Retry ${attempt}/${maxAttempts} after ${Math.round(jitter)}ms: ${err.message.slice(0,80)}`);
      await new Promise(r => setTimeout(r, jitter));
    }
  }
  throw lastError;
}

// Resilience-first event loop (Zulip call_on_each_event pattern)
async function resilientPollLoop() {
  while (connected) {
    try {
      const events = await circuitBreaker.fire(() =>
        withRetry(() => zulipQueue.poll(), {
          maxAttempts: 2,
          baseDelay: 1000,
          shouldRetry: (err) => {
            const msg = err.message || "";
            return msg.includes("fetch failed") || msg.includes("ECONN") || msg.includes("network");
          }
        })
      );

      lastError = null;
      retryCount = 0;

      for (const ev of events) {
        await processEvent(ev);
      }

      heartbeat();
    } catch (err) {
      const msg = err instanceof Error ? err.message : String(err);

      if (msg.includes("BAD_EVENT_QUEUE_ID") || msg.includes("deregistered")) {
        // Queue expired — re-register (Zulip docs pattern)
        console.log(`[zulip-ext] Queue expired, re-registering… (${msg.slice(0,80)})`);
        try {
          zulipQueue = await createZulipQueue();
          console.log(`[zulip-ext] Re-registered, new queue=${zulipQueue.queueId}`);
        } catch (reRegErr) {
          console.error(`[zulip-ext] Re-registration failed: ${reRegErr.message}`);
          connected = false;
          retryCount++;
          const backoff = Math.min(5000 * Math.pow(2, retryCount), 300000);
          console.log(`[zulip-ext] Full reconnect in ${Math.round(backoff/1000)}s`);
          await new Promise(r => setTimeout(r, backoff));
          await startPolling();
          return;
        }
      } else if (err.name === "CircuitOpenError") {
        // Circuit is open — skip this cycle, wait for HALF_OPEN
        lastError = "circuit_open";
        await new Promise(r => setTimeout(r, POLL_INTERVAL_MS));
      } else {
        lastError = msg;
        retryCount++;
        const backoff = Math.min(POLL_INTERVAL_MS * Math.pow(1.5, Math.min(retryCount, 8)), 60000);
        console.error(`[zulip-ext] Poll error (retry ${retryCount}, backoff ${backoff}ms): ${msg}`);
        await new Promise(r => setTimeout(r, backoff));
      }
    }
  }
}
```

### Phase 2: PM2 Hardening

Create `/root/.pm2/ecosystem.config.cjs`:

```js
module.exports = {
  apps: [
    {
      name: "abiba-zulip",
      script: "/bin/pi",
      args: "--mode rpc --session-id zulip-service",
      env: {
        ZULIP_ROLE: "router",
        ZULIP_SITE: "https://chat.sysloggh.net",
        ZULIP_EMAIL: "abiba-bot@chat.sysloggh.net",
        ZULIP_API_KEY: process.env.ZULIP_API_KEY,
        AGENT_NAME: "abiba",
        AGENT_OWNER_EMAIL: "jerome@sysloggh.com",
      },
      max_restarts: 100,            // Up from default 10 — crash loops won't exhaust
      min_uptime: "10s",            // Must survive 10s to count as "alive"
      max_memory_restart: "500M",   // OOM protection
      restart_delay: 5000,          // 5s between restarts
      kill_timeout: 15000,          // 15s SIGTERM grace before SIGKILL
      listen_timeout: 30000,        // 30s to bind health port
      log_date_format: "YYYY-MM-DD HH:mm:ss Z",
      error_file: "/root/.pm2/logs/abiba-zulip-error.log",
      out_file: "/root/.pm2/logs/abiba-zulip-out.log",
      merge_logs: true,
      autorestart: true,
      watch: false,
      instances: 1,
      exec_mode: "fork",
    },
    {
      name: "zulip-watchdog",
      script: "/root/.pi/agent/extensions/zulip/watchdog.js",
      max_restarts: 10,
      min_uptime: "3s",
      restart_delay: 3000,
      autorestart: true,
    },
  ],
};
```

### Phase 3: Supervisor Watchdog

Create `/root/.pi/agent/extensions/zulip/watchdog.js`:

```js
// External supervisor — monitors router health and restarts if stalled.
// This is the pattern Hermes uses: an external process that can recover
// the gateway even if the gateway process itself is hung (not just crashed).

const HEALTH_URL = "http://127.0.0.1:9200/health";
const CHECK_INTERVAL_MS = 30_000;
const MAX_FAILURES = 3;

let failures = 0;

async function check() {
  try {
    const res = await fetch(HEALTH_URL, { signal: AbortSignal.timeout(5000) });
    if (res.ok) {
      const data = await res.json();
      if (data.status === "ok" && data.zulip?.connected) {
        if (failures > 0) {
          console.log(`[watchdog] Router recovered after ${failures} failures`);
        }
        failures = 0;
        return;
      }
    }
    failures++;
    console.warn(`[watchdog] Health check ${failures}/${MAX_FAILURES}: status not ok`);
  } catch (err) {
    failures++;
    console.warn(`[watchdog] Health check ${failures}/${MAX_FAILURES}: ${err.message}`);
  }

  if (failures >= MAX_FAILURES) {
    console.error(`[watchdog] ${MAX_FAILURES} consecutive failures — restarting abiba-zulip`);
    const { execSync } = require("child_process");
    try {
      execSync("pm2 restart abiba-zulip", { timeout: 30000 });
      console.log("[watchdog] Restart command sent");
    } catch (e) {
      console.error(`[watchdog] Restart failed: ${e.message}`);
    }
    failures = 0;
    // Wait for restart to complete before checking again
    await new Promise(r => setTimeout(r, 15000));
  }
}

console.log("[watchdog] Zulip gateway supervisor started");
setInterval(check, CHECK_INTERVAL_MS);
check(); // Immediate first check
```

### Phase 4: Health Endpoint Enhancement

Add circuit breaker stats to the existing health endpoint:

```js
// In /health response, add:
"circuit_breaker": {
  "state": circuitBreaker.state,
  "failures": circuitBreaker.failures,
  "successes": circuitBreaker.successes,
  "total_requests": circuitBreaker.totalRequests,
  "failure_rate": circuitBreaker.totalRequests > 0
    ? (circuitBreaker.failures / circuitBreaker.totalRequests).toFixed(2)
    : "0.00"
}
```

---

## Test Plan

### Test 1: Queue Re-registration
1. Manually delete the Zulip event queue via API
2. Next poll should detect BAD_EVENT_QUEUE_ID
3. Router should auto re-register within 1 poll cycle
4. Verify: `/health` shows new queue_id, connected=true

### Test 2: Circuit Breaker Trip
1. Block Zulip server with iptables: `iptables -A OUTPUT -d 192.168.68.19 -j DROP`
2. Router should detect failures, trip circuit after 5 failures
3. `/health` should show circuit_breaker.state = "OPEN"
4. Remove iptables rule
5. Circuit should transition to HALF_OPEN → CLOSED within 60s
6. Verify: messages processed after recovery

### Test 3: Supervisor Recovery
1. Kill the router process: `kill -STOP $(pm2 pid abiba-zulip)` (freeze, don't kill)
2. Watchdog should detect 3 failed health checks in 90s
3. Watchdog should execute `pm2 restart abiba-zulip`
4. Verify: router back online, connected=true

### Test 4: Worker Busy Timeout
1. Send a message that triggers a long-running operation
2. If worker stays busy >5 minutes, should receive SIGKILL
3. User should receive error DM: "Response timed out"

### Test 5: End-to-End Message
1. Send DM "What time is it?" from Jerome
2. Should receive response within 30s
3. `/health` should show messages_processed incremented

---

## Rollback Plan

If v3 causes issues:
1. `pm2 delete abiba-zulip; pm2 delete zulip-watchdog`
2. Restore v2 from git: `cd /root/.pi/agent/extensions/zulip && git checkout index.js`
3. `pm2 resurrect` to reload previous process list
4. Verify: `/health` returns ok

Backup v2 before starting: `cp index.js index.js.v2-backup-$(date +%Y%m%d-%H%M%S)`

---

## Success Metrics

| Metric | Current (v2) | Target (v3) |
|--------|-------------|-------------|
| Uptime between manual interventions | 1-3 days | 30+ days |
| Crash recovery | Manual (PM2 resurrect) | Automatic (circuit breaker + supervisor) |
| Queue expiry handling | Crash | Auto re-register |
| Busy worker deadlock | Router death | Worker SIGKILL + error DM |
| PM2 restart exhaustion | Yes (max_restarts=10) | No (max_restarts=100 + watchdog) |