FR-181 P-0 gunicorn 長輪詢併發驗證

走長輪詢。 判據兩項都成立：

• gthread 吊 20 條長輪詢時，一般 API p95 為 74.2 ms，比基準①（sync、不吊）的 113.8 ms 還低，也比同一台 gthread 不吊時的 69.3 ms 只多 4.9 ms。兩種比法都低於 100 ms 門檻。
• pytest test/ 在 gthread 設定下的紅燈清單與 sync 基準一模一樣，沒有新紅（見「pytest 對照」）。

E-1 照此把預設翻成 gthread／16 執行緒；F-3 走長輪詢。D2 的三道防護（每台 Agent 一條、長輪詢配額 ≤ 8、等回答配額 ≤ 8）仍然必要，理由見「容量上限」。

• 起法：DEBUG=false USE_GUNICORN=true GUNICORN_WORKERS=2 BENCH_LONGPOLL=1 PORT=8031 python main.py，再用 GUNICORN_WORKER_CLASS 切 sync／gthread（GUNICORN_THREADS=16）。用 8031 埠，不碰共用的 8000。
• 假長輪詢端點：GET /api/1.0/_bench/longpoll?wait=30，睡 30 秒回 204（core/plugins/_bench_longpoll.py，只在 DEBUG 或 BENCH_LONGPOLL=1 時掛）。
• 量測腳本：scripts/dev/longpoll_bench.py --hold N --probe C --seconds 60。先開 N 條長輪詢吊著（吊滿 30 秒就立刻再吊一條，所以全程都有 N 條），等 2 秒再開 C 個並發連續打探測端點，一共打 60 秒。
• 探測端點：卡上寫的 /api/1.0/health 在 api 模式不存在（/healthz 只在 socketio／worker 模式掛）。改打 /api/1.0/version：免認證、不碰業務邏輯，但每個請求照樣會經過 api_log 中介層寫一筆 DB，所以量得到「排隊等 worker」的時間。另外補了一組要登入、走 RLS 的 /api/1.0/users/menu。
• 機器：Apple M4 Pro（12 核）、macOS 15.7.4、gunicorn 26.2.0、DEV DB 在本機。

②：2 條長輪詢就把 2 個 sync worker 全佔住。60 秒內 20 個並發只完成 60 個請求，每一個都等滿 30 秒，也就是排在某條長輪詢後面。這就是「2 核客戶機上 1 台 Agent 加 1 次測試連線，整個主系統停住」的原因。

同一台 gthread 的對照組

要登入、走 DB／RLS 的端點（/api/1.0/users/menu，gthread，探測並發 20）

兩組加起來 6,737 個 200、0 個 500。log 裡沒有 沒有在 context 中找到 session、DuplicatePreparedStatement、QueuePool limit、Traceback，也就是 thread-local session 與 JWT／RLS 的使用者脈絡在 16 執行緒下沒有串線。p95 多 56 ms，算在 DB 正常的並發抖動內（這支端點本身就要 300～600 ms）。

gthread 2 worker × 16 執行緒＝32 個槽。③是 20 條長輪詢加 20 個探測，共 40 條同時在要槽，超過 32。所以 p95 雖然好看，但 max 有 17.9 秒：少數請求剛好排在所有槽都被長輪詢佔住的時候。改成 8 個探測（20＋8＝28 < 32）時，max 就回到 308 ms。

這說明長輪詢不能吃滿執行緒。D2 的「長輪詢 ≤ 8、等回答 ≤ 8」是在保護一般 API 至少留著一半的槽，不是可以省掉的衛生項。gunicorn 的 accept 是每個 worker 各自搶，長輪詢不一定平均分到兩個 worker，所以配額要按每個 worker 進程計，不能只算全域總數。

（pytest test/，5,452 支。測試跑在 Flask test client 上，不會起 gunicorn，也沒有一支測試讀 GUNICORN_*。所以兩輪結果相同是預期中的事，並不證明多執行緒安全；多執行緒安全的證據在上一節實打的 6,737 個登入請求。）

紅燈清單比對：兩輪的 FAILED／ERROR 各 185 支，comm 比對兩邊都沒有多出來的，沒有新紅。基準紅燈集中在 test_detection_profile_source_freshness.py 等與本卡無關的既有測試。

• macOS fork 安全檢查：第一次跑 gthread 時，有一個 worker 被 SIGTRAP 打掉。macOS 當機報告寫的是 multi-threaded process forked 與 libdispatch crashed on child side of fork pre-exec。原因是 preload_app 在 master 先起了執行緒（排程、log 轉發），fork 之後 Apple 的系統框架在子程序裡自殺。另一個 worker 在同一輪 WORKER TIMEOUT 被殺，症狀相同。這是 macOS 才有的檢查，正式環境的 Linux 容器不會遇到。重跑時加了 OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES no_proxy='*'（macOS 跑 gunicorn 的標準解法），之後全程沒有 worker 死掉。上表的 gthread 數字都是這一輪的。sync 那兩組沒加也沒出事，可能只是運氣（sync worker 收到請求前不會碰到同一條路徑），所以①②不重跑。
• 同一台機器上同時跑壓測與服務，用 127.0.0.1 連線，沒有網路延遲。數字是相對比較用的，不能當成客戶機的絕對效能。
• 2 worker 是刻意模擬 2 核客戶機（出貨預設 worker 數＝nproc，封頂 4），不是這台 12 核機器的上限。
• 探測端點換成 /api/1.0/version，理由見「怎麼跑的」。