codex-call SSE 分幀與終端事件語意：byte 邊界丟包、殘留 buffer 不 flush、終端事件政策缺證據

[kiki830621]

Problem

bin/codex-call 的 SSE 分幀與終端事件處理有一組互相關聯的缺陷。它們不是獨立 bug，是同一個子系統的同一組問題，且共同缺少同一份證據：沒有人觀察過後端 teardown 的實際行為。

本 issue 自 #25 拆出。#25 的原始症狀（extractErrorMessage 漏了 json["error"]["message"] 路徑）是可證偽、有實測 payload、one-line 可修的；本 issue 承接的則是政策性問題 —— #25 在三輪 verify 中兩度嘗試順帶解決，兩度被推翻。

Type

bug

缺陷清單（皆有 verify 實測佐證）

1. byte-level 分幀：UTF-8 切在字中間 → 整個 chunk 被丟棄

guard let chunk = String(data: data, encoding: .utf8) else { return }   // bin/codex-call

URLSession 的 didReceive data: 按 TCP 可用量交付，與 UTF-8 codepoint 邊界零對齊保證。切點落在多位元組字元中間時 String(data:encoding:.utf8) 回 nil（Foundation 不做 U+FFFD 替換），guard else { return } 把整個 chunk 連同其中所有完整事件一起丟棄，且 bytes 不保留、不與下一 chunk 重組 —— 下一 chunk 開頭成為孤兒 continuation bytes，同樣整塊丟掉。

verify 實測（/usr/bin/swift）：

cut at byte 46 (continuation byte) — chunk1=46B chunk2=34B
String(data: chunk1, .utf8) = nil  <-- 整個 chunk 被 guard 丟棄
String(data: chunk2, .utf8) = nil  <-- 整個 chunk 被 guard 丟棄

這被本 plugin 的預設放大：codex-call 預設 --instructions 是「Respond in the user's language」，workflows/ensemble-workflow.js 的 codexPrompt() 更明確要求繁體中文輸出 —— 所有 delta 與所有後端錯誤訊息都是 3-byte CJK，切在字中間是常態不是邊角。

後果兩種，都靜默：

• 掉的是 response.output_text.delta → accumulated 少一段、streamError 仍 nil → 寫出截斷的 review 並 exit 0。末端的 fail-closed 只擋 accumulated 完全空（code 422），擋不住部分遺失 → ensemble 把腰斬的跨模型審閱當完整票採計
• 掉的是終端 error 事件 → 錯誤本身消失，最後以 422「no text output」歸因，把後端過載誤報成模型沒輸出

修法方向：以 Data 累積 buffer、在 byte 層找 \n\n，或保留無法解碼的尾段與下一 chunk 重組。

2. 殘留 buffer 從不 flush：未終結的最後一個事件被丟棄

drain loop 只處理有完整 \n\n 分隔的事件；didCompleteWithError 從不碰 buffer。後端送出 error 後直接關閉 socket（可能不送 trailing 空行）時，該事件永遠不被處理。

verify 實測：

$ codex-call --selftest-process-events '["data: {...delta...}\n\ndata: {"type":"error",...,"message":"Our servers are currently overloaded."}"]'
(no error)

對照組（同輸入 + trailing \n\n）正確印出訊息。

後果鏈：streamError 保持 nil → 不 throw → accumulated 非空 → 寫出截斷內容 → exit 0 = forged vote。

修法方向：didCompleteWithError 在 200 路徑上先處理殘留 buffer 再 signal。

3. 「哪個終端事件勝出」缺乏證據，且兩種嘗試都失敗

#25 在 R1 與 R2 分別試過兩種政策，都被 verify 推翻：

嘗試	判準	推翻理由
R1：first-wins latch	if streamError == nil	arrival-order 政策。實測四交錯後證明它只是把失敗從 D 搬到 B（B 在修法前是好的），不是消除
R2：informativeness	streamErrorIsFallback && msg != CODEX_FALLBACK_MESSAGE	只是 1-bit 投影。bare↔rich 確實 order-independent，但 rich↔rich 退回純 arrival-order —— 正是 R1 被判定「押一個沒有證據的排序」的那個 heuristic

而後端 teardown 的真實形狀恰恰落在 rich↔rich：{"type":"error","error":{"code":"server_is_overloaded","message":…}}（#25 實測 payload）與 {"type":"response.failed","response":{"error":{"message":…}}} 兩者都帶 message。哪個更該呈現給使用者？至今沒有證據。

附帶缺陷（同一個病的不同症狀，非獨立 bug）：

• 空字串 / 純空白 message 鎖死：判準是與 sentinel 字面值比對，空字串通過 → 標記為非 fallback → 永久阻擋升級。實測輸出空行且真訊息被丟棄。同一個洞也在 extractErrorMessage 內（top-level 空 message 遮蔽 nested 真訊息）
• 後端真的送 "Codex error" 會被誤判為 fallback

修法方向：換成對訊息本身求值的謂詞（trim 後非空、長度/內容有意義），而非與字面值比較。但這仍不回答 rich↔rich 該選誰 —— 那需要先補 trace。

4. didCompleteWithError 的同址政策未統一

} else if let err = error, streamError == nil {
    streamError = err
}

這是 first-wins arrival-order latch。可達交錯：HTTP 200 → 一個 bare 終端事件抵達（streamError = fallback）→ socket 死掉 → didCompleteWithError 收到真實 NSURLError（「The network connection was lost.」）→ 因 streamError != nil 而丟棄 transport error，使用者看到 Codex error。

「後端送 code-only error 然後斷線」正是 #25 那次事故最可能的形狀。

5. CRLF-framed SSE 永遠不產生事件邊界

分隔符硬編碼 \n\n。若後端改送 \r\n\r\n，buffer 無上限成長且每個事件（含終端事件）都不會被處理。

為什麼要先補 trace 再定政策

第 3 項的核心問題是「多個終端事件時哪個勝出」，而這個問題在三輪 verify 中始終缺同一份證據：

• 後端 teardown 到底會不會送 ≥2 個終端事件？
• 若會，順序如何？
• 兩個都帶 message 時，哪個比較完整？

#25 的 R2 曾為此寫了 9 個測試 case 去釘住一個自承無證據的偏好 —— 其中「兩個 rich：先到者保留」把未定義行為升級成有測試保護的契約，使得日後拿到真實 trace 想改對時，會被自己的測試擋下、且看起來像「破壞既有行為」。

先補 trace（開啟 raw SSE 記錄、蒐集數次真實 teardown），再定政策，才不會重演。

Impact

• 靜默的截斷輸出 + exit 0 = ensemble 採計不完整的跨模型票（forged vote）
• 後端過載被誤報成「模型沒輸出」，診斷方向被帶偏
• 中文輸出情境下 byte 邊界問題是常態，非邊角

Strategy（待 diagnose 確認）

• 先補 trace：加一個可選的 raw SSE dump（env var 或 hidden flag），蒐集數次真實後端 teardown
• byte-level buffering：改以 Data 累積、byte 層找分隔符，或保留無法解碼的尾段
• didCompleteWithError flush 殘留 buffer（200 路徑）
• 依 trace 證據定義終端事件政策；判準改為對訊息求值的謂詞
• 統一 didCompleteWithError 與 processEvent 的政策
• CRLF 分隔符支援
• 測試改以 byte 序列表達邊界（現有的 [String] hook 在構造上表達不出危險的那一半）

與 #25 的關係

#25 保留有實測錨點的部分（extractErrorMessage 補漏路徑 + 5 case + metadata），本 issue 承接政策性與分幀問題。切分理由：證據強度不同的東西不該綁在同一個交付單元 —— #25 的症狀有可重現的 payload，本 issue 的核心問題至今無 trace。

---

Source: surfaced during /idd-verify #25 --pr 26 rounds 1–3（三輪 FAIL 累積；R3 的 devil's-advocate 明確建議此切分）

[kiki830621]

三輪 verify 的可執行產物（保存自 PR #26，commit ab1d266）

#25 收斂時把這些從 PR 移除了。R4 的 devil's-advocate 指出這是個實質損失：四交錯矩陣與能表達 chunk 邊界的 harness 是三輪 verify 最貴的產物，刪掉之後本 issue 只剩散文結論，KNOWN GAP 註解變得不可稽核。故完整保存於此，#28 開工時可直接取用。

注意：這個 harness 本身有 R3 指出的結構限制 —— 它吃 [String]，表達不出 production 的 byte 邊界（didReceive 收的是 Data）。#28 的測試應改以 byte 序列表達。這裡保存的是它能覆蓋的那一半（事件層交錯），以及它示範的「不需 CODEX_URL 注入點即可驅動真實 StreamCollector」這個技法。

一、test/codex-call-stream-latch.bats（9 case，四交錯矩陣）

#!/usr/bin/env bats
# codex-call 的 SSE 終端事件「勝出政策」測試（--selftest-process-events）。
#
# 為什麼需要這一支（#25 R2）：
#   `codex-call-error-extract.bats` 測的是純函式 extractErrorMessage —— 每個 case
#   只餵一個 payload，因此**在構造上看不見**多事件交錯的問題。R1 的修法（arrival-order
#   latch `if streamError == nil`）就是在那組測試全綠的情況下引入了一個回歸：把失敗
#   從「分 chunk, rich→bare」搬到「分 chunk, bare→rich」。
#
#   爭議所在的語意（哪個終端事件勝出）恰恰是零覆蓋的那一塊，而不具爭議的
#   extractErrorMessage 有 5 個 case。這支測試補的正是那一塊。
#
# 兩個被本輪修正的缺陷是**複合**的，必須一起測：
#   (1) 勝出政策：arrival-order → informativeness（bare 不得壓住後到的 rich）
#   (2) buffer drain：原本 while-loop 內的 early return 會在同一個 chunk 內丟掉
#       sibling 事件 —— 而終端錯誤正是 backend flush+close 的時刻，同 chunk 抵達
#       的機率不低於分開
#
# 輸入格式：--selftest-process-events 吃一個 JSON array of chunk strings，
# 每個元素代表一次 didReceive 收到的 chunk（可含 0..N 個完整 SSE 事件）。
# 這讓「chunk 邊界」成為可直接表達的測試輸入，不需要網路或 CODEX_URL 注入點。

setup() {
  BIN="${BATS_TEST_DIRNAME}/../bin/codex-call"
  # 同 codex-call-error-extract.bats：codex-call 是 #!/usr/bin/swift script。
  [ "$(uname)" = "Darwin" ] && [ -x /usr/bin/swift ] \
    || skip "needs macOS + Xcode CLT swift (codex-call is a #!/usr/bin/swift script)"
}

# 無 message 的終端事件（會落到 fallback）
BARE='data: {\"type\":\"error\",\"error\":{\"code\":\"some_code_without_message\"}}\n\n'
# 帶 message 的終端事件
RICH='data: {\"type\":\"response.failed\",\"response\":{\"error\":{\"message\":\"RICH_MESSAGE\"}}}\n\n'

@test "A 同 chunk, bare→rich：rich 勝出（需要 buffer drain）" {
  run "$BIN" --selftest-process-events "[\"${BARE}${RICH}\"]"
  [ "$status" -eq 0 ]
  [[ "$output" == *"RICH_MESSAGE"* ]]
  [[ "$output" != *"Codex error"* ]]
}

@test "B 分 chunk, bare→rich：rich 勝出（需要 informativeness policy）" {
  run "$BIN" --selftest-process-events "[\"${BARE}\",\"${RICH}\"]"
  [ "$status" -eq 0 ]
  [[ "$output" == *"RICH_MESSAGE"* ]]
  [[ "$output" != *"Codex error"* ]]
}

@test "C 同 chunk, rich→bare：rich 保留（bare 不得覆寫）" {
  run "$BIN" --selftest-process-events "[\"${RICH}${BARE}\"]"
  [ "$status" -eq 0 ]
  [[ "$output" == *"RICH_MESSAGE"* ]]
}

@test "D 分 chunk, rich→bare：rich 保留（R1 原本要修的那個）" {
  run "$BIN" --selftest-process-events "[\"${RICH}\",\"${BARE}\"]"
  [ "$status" -eq 0 ]
  [[ "$output" == *"RICH_MESSAGE"* ]]
}

@test "只有 bare：如實落到 fallback，不虛構訊息" {
  run "$BIN" --selftest-process-events "[\"${BARE}\"]"
  [ "$status" -eq 0 ]
  [[ "$output" == *"Codex error"* ]]
}

@test "只有 rich：訊息完整取出" {
  run "$BIN" --selftest-process-events "[\"${RICH}\"]"
  [ "$status" -eq 0 ]
  [[ "$output" == *"RICH_MESSAGE"* ]]
}

@test "兩個 rich：先到者保留，後到者不覆寫（policy 只提升資訊量、不追新）" {
  R2='data: {\"type\":\"error\",\"error\":{\"message\":\"SECOND_RICH\"}}\n\n'
  run "$BIN" --selftest-process-events "[\"${RICH}\",\"${R2}\"]"
  [ "$status" -eq 0 ]
  [[ "$output" == *"RICH_MESSAGE"* ]]
  [[ "$output" != *"SECOND_RICH"* ]]
}

@test "無終端事件：不虛構錯誤" {
  DELTA='data: {\"type\":\"response.output_text.delta\",\"delta\":\"hello\"}\n\n'
  run "$BIN" --selftest-process-events "[\"${DELTA}\"]"
  [ "$status" -eq 0 ]
  [[ "$output" == *"(no error)"* ]]
}

@test "非 JSON array 輸入 → 非零 exit" {
  run "$BIN" --selftest-process-events '{"not":"an array"}'
  [ "$status" -ne 0 ]
}

二、支撐它的 production hook（bin/codex-call）

// StreamCollector.feed(_:) —— 從 didReceive 抽出的 drain 邏輯
    /// Drain one chunk's worth of SSE events. Split out of `didReceive` so chunk
    /// boundaries are directly expressible as test input — no URLSession, no socket,
    /// no CODEX_URL injection point needed (see --selftest-process-events).
    func feed(_ chunk: String) {
        buffer += chunk
        while let range = buffer.range(of: "\n\n") {
            let event = String(buffer[buffer.startIndex..<range.lowerBound])
            buffer.removeSubrange(buffer.startIndex..<range.upperBound)
            processEvent(event)
            // NO early return on streamError (#25 R2). Bailing here aborted the drain
            // loop, so sibling events already sitting in `buffer` were never processed —
            // and a terminal error is exactly when the backend flushes and closes, so
            // `error` + `response.failed` landing in ONE segment is at least as likely
            // as being split. The stream is torn down regardless; draining costs nothing.
        }
    }

// main 內的 hook 區塊
// Hidden test hook (#25 R2) — same placement rationale as above: no request, no file.
// Drives the real StreamCollector through a caller-specified chunk sequence so that
// chunk boundaries (which decide the outcome) are test input rather than luck.
if let raw = a.selftestProcessEvents {
    guard let data = raw.data(using: .utf8),
          let chunks = try? JSONSerialization.jsonObject(with: data) as? [String]
    else { die("--selftest-process-events: expected a JSON array of chunk strings") }
    let collector = StreamCollector()
    collector.statusCode = 200
    for chunk in chunks { collector.feed(chunk) }
    print((collector.streamError as NSError?)?.localizedDescription ?? "(no error)")
    exit(0)
}
// parseArgs case
        case "--selftest-process-events": a.selftestProcessEvents = next()

三、R2 實測的四交錯矩陣（first-wins latch 下的行為）

                                 PRE-FIX            first-wins latch
A same chunk, bare then rich  →  Codex error        Codex error
B split,      bare then rich  →  真實訊息            Codex error   ← latch 引入的回歸
C same chunk, rich then bare  →  真實訊息            真實訊息
D split,      rich then bare  →  Codex error        真實訊息       ← latch 修好的那格

Source: preserved during /idd-verify #25 --pr 26 R4 follow-up（R4 devil's-advocate HIGH：「收斂把三輪最貴的產物整份刪除，只留散文結論 —— KNOWN GAP 因此不可稽核」）

[kiki830621]

更正：上方保存的 harness 無法直接貼回 HEAD 執行（3/9 紅）

R5 的 devil's-advocate 實測指出，把上一則 comment 保存的 harness 原樣貼回 main/HEAD 會有 3 個 case 失敗。這個更正必須留在這裡，否則保存動作會被誤讀成「已可直接取用」。

原因：該 harness 測的是 R2 實作的 informativeness policy，而那段 code 在 #25 收斂時已被回復（b6fbb91）。缺的正是：

• streamErrorIsFallback 狀態與升級判斷 → 失敗的是 B（分 chunk, bare→rich）與相關 case
• feed(_:) 與移除 early return 的 drain → 失敗的是 A（同 chunk, bare→rich）
• --selftest-process-events hook → 若未一併貼回，全部 9 個都跑不起來

因此本 issue 開工時的正確用法：harness 與 hook 是一組，必須連同 policy 實作一起回填才有意義；且 R3 已證明它本身有結構限制（吃 [String]，表達不出 production 的 byte 邊界）。建議把它當作起點而非終點 —— 先照 #28 的 Strategy 補 byte-level 測試表達力，再把事件層的四交錯矩陣接上去。

保存的價值在於：R2 量到的四交錯矩陣數據、以及「不需 CODEX_URL 注入點即可驅動真實 StreamCollector」這個技法，兩者都不必重新推導。

Source: /idd-verify #25 --pr 26 R5 devil's-advocate MEDIUM —— 對前一則 comment「完整保存」宣稱的更正。