From 995cba5d02cdc8418beed04143fbf13fd83b6e71 Mon Sep 17 00:00:00 2001
From: Kilo <kilo@kilo.ai>
Date: Wed, 6 May 2026 18:34:58 +0000
Subject: [PATCH] =?UTF-8?q?docs:=20README=20=E2=80=94=20PortManager=20arch?=
 =?UTF-8?q?itecture=20section?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/README.md b/README.md
index e771ec7e..bc2c1e81 100644
--- a/README.md
+++ b/README.md
@@ -447,6 +447,30 @@ User (Telegram) → Webhook → Bot → Intent Detection
                           └─────────────────────┘
 ```
 
+### PortManager — Smart Port Lifecycle
+
+Handles HTTP server port binding with intelligent recovery, replacing the old probe→kill→exit pattern that caused crash-loops under systemd.
+
+```
+PortManager (EventEmitter)
+├── States: idle → probing → claiming → owned → releasing → failed
+├── Holder Detection (3 methods):
+│   ├── pidfile read (fast path)
+│   ├── ss -tlnp (system socket lookup)
+│   └── lsof -ti (fallback)
+├── Recovery:
+│   ├── Age-based kill strategy (young siblings waited, not killed)
+│   ├── Exponential backoff retry (5 attempts, 500ms → 5000ms)
+│   └── State events: stateChange, claimed, retry, failed
+└── API:
+    ├── claim(server) — acquire port with retry loop
+    ├── release() — cleanup on shutdown
+    ├── probe() — check if port is free
+    └── getStatus() — diagnostics for health checks
+```
+
+**File**: `src/bot/port-manager.js` | **Exposed via**: `bot.portManager`
+
 ---
 
 ## 📊 Feature Comparison