Skip to content

[WRONG BRANCH] fix(stream): gate macOS eager-relay on a verified Bun runtime #56

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
luvs01 wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

[WRONG BRANCH] fix(stream): gate macOS eager-relay on a verified Bun runtime #56

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions docs-site/src/content/docs/ja/troubleshooting/windows-memory.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,6 @@ Windows では、#32111 クラッシュを回避するために、opencodex は
2. **`OPENCODEX_BUN_PATH` を使用して信頼できる Bun ランタイムを実行します。** これは
未検証の領域 — 私たちがテストしていないランタイムで opencodex を実行しています。自己責任で。サービスのインストールにとって重要: オーバーライドは、サービスの開始時ではなく、**サービス アーティファクトの生成時に**読み込まれます。環境変数を設定し、同じシェルから `ocx service repair` を再実行すると、パスが永続サービス定義に組み込まれます。 env を設定するだけでは、すでにインストールされているサービスには何も影響しません。

3. **`streamMode: "eager-relay"` を使用して有界リレーにオプトインします。** 2 つの方法:
`config.json` を編集する (`"streamMode": "eager-relay"` を追加する) か、管理 API を呼び出します。`PUT /api/settings` と `{"streamMode":"eager-relay"}` は、再起動せずに新しいターンに適用されます。 **クラッシュのリスク警告:** Bun 1.3.14 では、#32111 の影響を受けるストリーム形状が使用されており、ストリームの途中でプロセスがクラッシュする可能性があります (Windows に限らず、どの OS でも)。サービス マネージャーはサービスを再起動しますが、実行中のリクエストは失敗します。 `"legacy-tee"` は現在のデフォルトを固定します。 Windows では、`"auto"` (デフォルト) によりランタイム ゲートが決定します。 macOS では、`"auto"` は常に T 上にあります。明示的な `"eager-relay"` はオプトインです。
3. **`streamMode: "eager-relay"` で bounded relay を明示的に選択します。** 設定方法は変わりませんが、macOS では bundled runtime に #32111 の修正が含まれると検証された場合にのみ有効になり、それまでは tee を使用します。Windows では既存の明示設定の動作を維持します。`"legacy-tee"` は tee を固定し、`"auto"` は Windows では runtime gate に従い、macOS では常に tee を使用します。

@coderabbitai coderabbitai Bot Aug 7, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

Synchronize the translated configuration instructions with the English source.

The English page names config.json and PUT /api/settings, and states that the API applies to new turns without a restart. The four locale paragraphs only say that the configuration method is unchanged.

  • docs-site/src/content/docs/ja/troubleshooting/windows-memory.md#L45-L45: restore the concrete configuration methods and no-restart behavior.
  • docs-site/src/content/docs/ko/troubleshooting/windows-memory.md#L39-L39: restore the concrete configuration methods and no-restart behavior.
  • docs-site/src/content/docs/ru/troubleshooting/windows-memory.md#L80-L80: restore the concrete configuration methods and no-restart behavior.
  • docs-site/src/content/docs/zh-cn/troubleshooting/windows-memory.md#L39-L39: restore the concrete configuration methods and no-restart behavior.
📍 Affects 4 files
  • docs-site/src/content/docs/ja/troubleshooting/windows-memory.md#L45-L45 (this comment)
  • docs-site/src/content/docs/ko/troubleshooting/windows-memory.md#L39-L39
  • docs-site/src/content/docs/ru/troubleshooting/windows-memory.md#L80-L80
  • docs-site/src/content/docs/zh-cn/troubleshooting/windows-memory.md#L39-L39
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs-site/src/content/docs/ja/troubleshooting/windows-memory.md` at line 45,
Synchronize the translated configuration paragraphs with the English source by
explicitly naming config.json and PUT /api/settings, and stating that API
changes apply to new turns without requiring a restart. Update
docs-site/src/content/docs/ja/troubleshooting/windows-memory.md:45-45,
docs-site/src/content/docs/ko/troubleshooting/windows-memory.md:39-39,
docs-site/src/content/docs/ru/troubleshooting/windows-memory.md:80-80, and
docs-site/src/content/docs/zh-cn/troubleshooting/windows-memory.md:39-39;
preserve each locale’s existing translation and streamMode behavior.

Source: Path instructions


これらのいずれかを実際の Windows ワークロードで試した場合は、[#314](https://github.com/lidge-jun/opencodex/issues/314) の `ocx doctor` メモリ セクションの前後を報告してください。これがまさにこの軽減策が待っている検証です。
2 changes: 1 addition & 1 deletion docs-site/src/content/docs/ko/troubleshooting/windows-memory.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,6 @@ Windows에서는 opencodex가 #32111 충돌을 피하기 위해 스트리밍 응

2. **`OPENCODEX_BUN_PATH`로 신뢰하는 Bun 런타임을 사용합니다.** 이 경로는 검증되지 않은 영역입니다. opencodex를 아직 테스트하지 않은 런타임에서 실행하는 것이므로, 위험은 사용자에게 있습니다. 서비스 설치에서 특히 중요한 점은 이 override가 서비스 시작 시가 아니라 **서비스 아티팩트를 생성할 때** 읽힌다는 것입니다. 환경 변수를 설정한 뒤, 같은 셸에서 `ocx service repair`를 다시 실행해야 경로가 영구적인 서비스 정의에 반영됩니다. 환경 변수만 설정하면 이미 설치된 서비스에는 아무 영향이 없습니다.

3. **`streamMode: "eager-relay"`로 bounded relay를 opt-in합니다.** 방법은 두 가지입니다. `config.json`을 수정해 `"streamMode": "eager-relay"`를 추가하거나, 관리 API에 `PUT /api/settings`와 `{"streamMode":"eager-relay"}`를 보내 새 턴에 재시작 없이 적용합니다. **충돌 위험 경고:** Bun 1.3.14에서는 이 방식이 #32111의 영향을 받는 스트림 형태를 사용하므로, 어떤 OS에서든 스트림 중간에 프로세스가 충돌할 수 있습니다. 서비스 관리자가 다시 시작하겠지만, 진행 중이던 요청은 실패합니다. `"legacy-tee"`는 현재 기본값을 고정합니다. Windows에서는 `"auto"`(기본값)가 런타임 게이트 판단을 따르게 합니다. macOS에서는 `"auto"`가 항상 tee를 유지하고, 명시적 `"eager-relay"`만 opt-in입니다.
3. **`streamMode: "eager-relay"`로 bounded relay를 명시적으로 선택합니다.** 설정 방법은 그대로지만 macOS에서는 bundled runtime에 #32111 수정이 포함되었다고 검증된 경우에만 적용되며, 그전에는 tee를 계속 사용합니다. Windows는 기존의 명시적 설정 동작을 유지합니다. `"legacy-tee"`는 tee를 고정하고, `"auto"`는 Windows에서 runtime gate를 따르며 macOS에서는 항상 tee를 사용합니다.

이 중 어떤 방법이든 실제 Windows 워크로드에 적용해 보셨다면, 변경 전후의 `ocx doctor` 메모리 섹션을 [#314](https://github.com/lidge-jun/opencodex/issues/314)에 남겨 주세요. 이것이 바로 이 완화책이 기다리고 있는 검증입니다.
10 changes: 1 addition & 9 deletions docs-site/src/content/docs/ru/troubleshooting/windows-memory.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,15 +77,7 @@ opencodex поставляет рантайм Bun (сейчас это **1.3.14*
оболочки, чтобы путь оказался зашит в долговременное определение службы. Одной только
переменной для уже установленной службы недостаточно.

3. **Явно перейти на bounded relay через `streamMode: "eager-relay"`.** Есть два пути:
отредактировать `config.json` (добавить `"streamMode": "eager-relay"`) или вызвать management
API — `PUT /api/settings` с `{"streamMode":"eager-relay"}` применит изменение к новым ходам без
перезапуска. **Предупреждение о риске crash:** на Bun 1.3.14 это использует форму streaming,
затронутую #32111, и процесс может упасть прямо посреди потока (на любой ОС, не только на
Windows). Service manager перезапустит его, но все запросы в полёте потерпят неудачу.
`"legacy-tee"` жёстко фиксирует текущий путь по умолчанию. На Windows `"auto"` (по умолчанию)
позволяет рантайму выбрать путь самому. На macOS `"auto"` всегда остаётся на tee; явный
`"eager-relay"` — это opt-in.
3. **Явно перейти на bounded relay через `streamMode: "eager-relay"`.** Способы настройки не изменились, но на macOS этот режим включается только после подтверждения, что bundled runtime содержит исправление #32111; до этого macOS остаётся на tee. Windows сохраняет существующее поведение явной настройки. `"legacy-tee"` фиксирует tee, а `"auto"` использует runtime gate на Windows и всегда остаётся на tee на macOS.

Если вы попробуете любой из этих вариантов на реальной Windows-нагрузке, пожалуйста, пришлите
разделы памяти из `ocx doctor` до и после в
Expand Down
21 changes: 11 additions & 10 deletions docs-site/src/content/docs/troubleshooting/windows-memory.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,8 +60,9 @@ runtime the leak itself remains an upstream problem:
- **A gated alternative stream path** — a bounded single-reader relay that
removes the unbounded buffering shape entirely. On Windows it becomes the
default automatically once a bundled Bun release verifiably carries the
#32111 fix; today it is opt-in only (see below). On macOS it stays opt-in
even after such a release — flipping macOS `auto` is a separate decision.
#32111 fix; today it is opt-in only (see below). On macOS it requires both
that verified runtime and explicit opt-in — flipping macOS `auto` is a
separate decision.
Comment on lines +63 to +65

@coderabbitai coderabbitai Bot Aug 7, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail
rg -n -C 6 'selectEagerPath|Bun\.version|OPENCODEX_BUN_PATH' src

Repository: luvs01/opencodex

Length of output: 16449

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '%s\n' '--- bun-stream-caps.ts ---'
sed -n '1,135p' src/lib/bun-stream-caps.ts

printf '%s\n' '--- bun-runtime.ts ---'
sed -n '1,215p' src/lib/bun-runtime.ts

printf '%s\n' '--- relevant launch/runtime references ---'
rg -n -C 5 'OPENCODEX_BUN_PATH|withProcessRuntimeProvenance|durableBunRuntime|reportedBunRuntimeSource|BUN_OVERRIDE_ENV|Bun\.version' src --glob '*.ts' --glob '*.mjs'

printf '%s\n' '--- documentation context ---'
for f in \
  docs-site/src/content/docs/troubleshooting/windows-memory.md \
  docs-site/src/content/docs/ja/troubleshooting/windows-memory.md \
  docs-site/src/content/docs/ko/troubleshooting/windows-memory.md \
  docs-site/src/content/docs/ru/troubleshooting/windows-memory.md \
  docs-site/src/content/docs/zh-cn/troubleshooting/windows-memory.md
do
  echo "### $f"
  wc -l "$f"
  sed -n '35,105p' "$f"
done

Repository: luvs01/opencodex

Length of output: 50372

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '%s\n' '--- all runtime override and launcher selection references ---'
rg -n -C 4 'OPENCODEX_BUN_PATH|bundledBunPath|process\.execPath|selectEagerPath\(' . \
  -g '!node_modules' -g '!dist' -g '!build' -g '*.ts' -g '*.mjs' -g '*.json' -g '*.sh' \
  | head -n 500

printf '%s\n' '--- exact English gate and option text ---'
nl -ba docs-site/src/content/docs/troubleshooting/windows-memory.md | sed -n '55,102p'

printf '%s\n' '--- exact translated stream-mode paragraphs ---'
for spec in \
  'docs-site/src/content/docs/ja/troubleshooting/windows-memory.md:35:52' \
  'docs-site/src/content/docs/ko/troubleshooting/windows-memory.md:30:46' \
  'docs-site/src/content/docs/ru/troubleshooting/windows-memory.md:70:87' \
  'docs-site/src/content/docs/zh-cn/troubleshooting/windows-memory.md:30:46'
do
  file=${spec%%:*}
  rest=${spec#*:}
  start=${rest%%:*}
  end=${rest##*:}
  echo "### $file"
  nl -ba "$file" | sed -n "${start},${end}p"
done

printf '%s\n' '--- precise selectEagerPath call arguments ---'
rg -n -U -C 3 'selectEagerPath\(' src --glob '*.ts'

Repository: luvs01/opencodex

Length of output: 34135

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '%s\n' '--- launcher runtime selection ---'
sed -n '350,435p' bin/ocx.mjs

printf '%s\n' '--- English affected lines ---'
awk 'NR >= 55 && NR <= 102 { printf "%6d:%s\n", NR, $0 }' \
  docs-site/src/content/docs/troubleshooting/windows-memory.md

printf '%s\n' '--- translated affected lines ---'
for spec in \
  'docs-site/src/content/docs/ja/troubleshooting/windows-memory.md 35 52' \
  'docs-site/src/content/docs/ko/troubleshooting/windows-memory.md 30 46' \
  'docs-site/src/content/docs/ru/troubleshooting/windows-memory.md 70 87' \
  'docs-site/src/content/docs/zh-cn/troubleshooting/windows-memory.md 30 46'
do
  set -- $spec
  file=$1
  echo "### $file"
  awk -v start="$2" -v end="$3" 'NR >= start && NR <= end { printf "%6d:%s\n", NR, $0 }' "$file"
done

Repository: luvs01/opencodex

Length of output: 11685

Use the running Bun runtime in the macOS gate documentation. selectEagerPath defaults to Bun.version, and OPENCODEX_BUN_PATH can select the runtime used by the service. Update docs-site/src/content/docs/troubleshooting/windows-memory.md#L63-L65, #L92-L97, and the corresponding ja#L45, ko#L39, ru#L80, and zh-cn#L39 text. Keep “bundled runtime” only for the default update path.

📍 Affects 5 files
  • docs-site/src/content/docs/troubleshooting/windows-memory.md#L63-L65 (this comment)
  • docs-site/src/content/docs/troubleshooting/windows-memory.md#L92-L97
  • docs-site/src/content/docs/ja/troubleshooting/windows-memory.md#L45-L45
  • docs-site/src/content/docs/ko/troubleshooting/windows-memory.md#L39-L39
  • docs-site/src/content/docs/ru/troubleshooting/windows-memory.md#L80-L80
  • docs-site/src/content/docs/zh-cn/troubleshooting/windows-memory.md#L39-L39
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs-site/src/content/docs/troubleshooting/windows-memory.md` around lines 63
- 65, Update the macOS gate documentation to describe the currently running Bun
runtime, including the runtime selected through OPENCODEX_BUN_PATH, rather than
implying it always uses the bundled runtime. Apply this wording change at
docs-site/src/content/docs/troubleshooting/windows-memory.md lines 63-65 and
92-97, and the corresponding Japanese line 45, Korean line 39, Russian line 80,
and Simplified Chinese line 39. Retain “bundled runtime” terminology only for
the default update path.

Source: Path instructions


Real-world RSS improvement from these changes is **awaiting verification by
Windows users** — we do not claim the leak is fixed.
Expand All @@ -74,8 +75,8 @@ restart it.

1. **Wait for a bundled runtime update.** Once a Bun release verifiably
carries the fixes, opencodex will bump the bundled runtime and the safer
stream path turns on automatically on Windows (macOS keeps requiring the
explicit opt-in below).
stream path turns on automatically on Windows (macOS also keeps requiring
the explicit opt-in below).

2. **Run a Bun runtime you trust with `OPENCODEX_BUN_PATH`.** This is
unvalidated territory — you are running opencodex on a runtime we have not
Expand All @@ -88,12 +89,12 @@ restart it.
3. **Opt into the bounded relay with `streamMode: "eager-relay"`.** Two ways:
edit `config.json` (add `"streamMode": "eager-relay"`), or call the
management API — a `PUT /api/settings` with `{"streamMode":"eager-relay"}`
applies to new turns without a restart. **Crash risk warning:** on Bun
1.3.14 this uses the stream shape affected by #32111, which can crash the
process mid-stream (on any OS, not just Windows). The service manager will
restart it, but in-flight requests fail. `"legacy-tee"` pins the current
default. On Windows, `"auto"` (default) lets the runtime gate decide. On
macOS, `"auto"` always stays on tee; explicit `"eager-relay"` is the opt-in.
applies to new turns without a restart. On Windows this explicit mode
retains its existing operator-controlled behavior. On macOS it is effective
only after the bundled runtime is verified to carry the #32111 fix; until
then macOS stays on tee. `"legacy-tee"` pins the current default, and
`"auto"` lets the Windows runtime gate decide while always staying on tee on
macOS.

If you try any of these on a real Windows workload, please report the before
and after `ocx doctor` memory sections on
Expand Down
2 changes: 1 addition & 1 deletion docs-site/src/content/docs/zh-cn/troubleshooting/windows-memory.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,6 @@ opencodex 打包了 Bun 运行时（当前为 **1.3.14**）。这类内存增长

2. **通过 `OPENCODEX_BUN_PATH` 运行你信任的 Bun 运行时。** 这属于未验证区域，你是在一个我们没有测试过的运行时上运行 opencodex，风险自负。对服务安装而言，这个覆盖值是在生成服务产物时读取的，而不是在服务启动时读取的。先设置环境变量，然后在同一个 shell 中重新运行 `ocx service repair`，这样路径才会被写入持久化的服务定义。只设置环境变量对已经安装好的服务没有任何作用。

3. **通过 `streamMode: "eager-relay"` 显式启用有界中继。** 有两种方式：编辑 `config.json`（添加 `"streamMode": "eager-relay"`），或调用管理 API - `PUT /api/settings` 携带 `{"streamMode":"eager-relay"}`，即可对新轮次生效，无需重启。**崩溃风险警告：** 在 Bun 1.3.14 上，这会使用受 #32111 影响的流形态，可能在流中途使进程崩溃（任何操作系统都会受影响，不只是 Windows）。服务管理器会把它重启，但正在进行的请求会失败。`"legacy-tee"` 会固定在当前默认路径。Windows 上，`"auto"`（默认值）会交给运行时门控决定。macOS 上，`"auto"` 始终保持 tee；显式 `"eager-relay"` 才是显式启用选项。
3. **通过 `streamMode: "eager-relay"` 显式启用有界中继。** 配置方式不变，但在 macOS 上，只有当捆绑运行时已验证包含 #32111 修复时该设置才会生效；在此之前 macOS 会继续使用 tee。Windows 保留现有的显式配置行为。`"legacy-tee"` 固定当前默认路径；`"auto"` 在 Windows 上由运行时门控决定，在 macOS 上始终使用 tee。

如果你在真实的 Windows 工作负载上尝试这些方案，请把变更前后 `ocx doctor` 的内存部分发到 [#314](https://github.com/lidge-jun/opencodex/issues/314)——这正是这个缓解措施在等待的验证。
15 changes: 8 additions & 7 deletions src/lib/bun-stream-caps.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,9 @@
* that fix yet, so `MIN_FIXED_BUN_VERSION` is null: every runtime is
* "known-bad" until a bundle-bump commit sets it. Windows no-rewrite traffic
* follows this runtime/config decision, preserving the explicit legacy-tee
* safety pin. Darwin no-rewrite traffic stays on tee
* for `auto` regardless of runtime capability and reaches eager relay only via
* explicit `streamMode: "eager-relay"` opt-in (see
* devlog/_fin/260731_macos_rss_retention/100_darwin_eager_optin.md).
* safety pin. Darwin no-rewrite traffic stays on tee for `auto` regardless of
* runtime capability and requires both explicit `streamMode: "eager-relay"`
* and a runtime proven to contain the fix.
*
* Prerelease conservatism: a version carrying a prerelease suffix (e.g.
* `1.4.0-canary.3`) is NEVER treated as fixed even when its numeric triple
Expand Down Expand Up @@ -91,8 +90,8 @@ export function decideEagerRelay(

/**
* Apply the two-platform eager-relay policy to the runtime/config capability.
* Windows preserves the decision for no-rewrite traffic. Darwin permits only
* explicit config opt-in; `auto` remains tee even on a future fixed runtime.
* Windows preserves the decision for no-rewrite traffic. Darwin requires an
* explicit config opt-in on a proven-fixed runtime; `auto` remains tee.
* Returns the normalized effective decision, or null when platform policy,
* rewrite needs, or a Darwin non-config-eager mode selects tee.
*/
Expand All @@ -109,7 +108,9 @@ export function selectEagerPath(

const decision = decideEagerRelay(mode, version, minFixed);
if (platform === "win32") return decision;
return decision.reason === "config-eager" ? decision : null;
return decision.reason === "config-eager" && bunHasAsyncPullCancelFix(version, minFixed)
? decision
: null;
}

/**
Expand Down
4 changes: 2 additions & 2 deletions src/types.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -632,8 +632,8 @@ export interface OcxConfig {
* Windows/macOS SSE passthrough stream shape (#314 mitigation).
* On Windows, "auto" (default) selects eager relay only on a runtime proven
* to carry the Bun#32111 fix. On macOS, "auto" always stays on legacy tee and
* eager relay is explicit-only. "eager-relay" opts into the new relay (and
* accepts #32111 crash risk on Bun 1.3.14); "legacy-tee" pins the tee path.
* eager relay requires both explicit opt-in and a runtime verified to carry
* the Bun#32111 fix. "legacy-tee" pins the tee path.
* Persisted in config.json so service users can select the stream shape.
* See src/lib/bun-stream-caps.ts.
*/
Expand Down
2 changes: 1 addition & 1 deletion structure/02_config-and-codex-home.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ matters for maintainers is which groups exist and who resolves them:
| Routing | `defaultProvider`, `providers`, per-provider `selectedModels` | Explicit `provider/model` wins over `defaultProvider`. |
| Catalog | `disabledModels`, `customModels`, `modelCacheTtlMs`, `providerContextCaps`, `contextCapValue` | Catalog state is derived; config only records intent. |
| Retained state | `appOwnedMemoryBudgetMb` | Process-wide eviction target for app-owned logs, caches, blobs, and continuation payloads. Default 256 MiB, valid 64..4096; pinned state may temporarily exceed the target, but every pin-capable store has a finite local cap and their documented aggregate stays below `APP_OWNED_WORST_CASE_PINNED_BYTES` (512 MiB). Neither value caps RSS or native runtime memory. |
| Transport | stream mode, timeouts, proxy settings, `websockets` | `streamMode` persists in config.json; Windows services need a persisted input, and macOS uses it for explicit eager-relay opt-in. |
| Transport | stream mode, timeouts, proxy settings, `websockets` | `streamMode` persists in config.json; Windows services need a persisted input, and macOS requires a proven-fixed runtime in addition to explicit eager-relay opt-in. |
| Credentials | `apiKeys` | Data-plane only; never admitted to `/api/*`. |
| Lifecycle | `codexAutoStart`, shim/start behavior, resume-history sync, storage cleanup | Startup safety reads these; see [`05_gui-and-management-api.md`](05_gui-and-management-api.md). |

Expand Down
5 changes: 3 additions & 2 deletions structure/04_transports-and-sidecars.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,8 +49,9 @@ Native passthrough SSE has TWO shapes, selected per request in
`legacy-tee` and known-bad-runtime `auto` on tee as documented. When selected,
`response.completed` closes the client stream even if upstream keeps HTTP/SSE
alive. Darwin uses it for no-client-rewrite traffic only (neither image-gen
aliases nor item-id repair) and is explicit-only: `auto` stays tee even after
a future threshold bump. One eager reader + byte-bounded
aliases nor item-id repair), but requires both explicit config and a
proven-fixed runtime: `auto` stays tee even after a future threshold bump.
One eager reader + byte-bounded
client queue + post-cancel bounded discard-drain replaces the tee and goes
directly to the response without a JS rewrite wrapper, preserving the full
inspection side-effect set (shared `createSseInspector` factory in `relay.ts`)
Expand Down
2 changes: 1 addition & 1 deletion structure/05_gui-and-management-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ this document owns is which module holds which area and what invariant that area

| Endpoint area | Responsibility |
| --- | --- |
| Config/settings | Read safe config/settings views; mutate supported settings only. Full `PUT /api/config` is disabled so masked secrets are not round-tripped. `PUT /api/settings` accepts `codexAutoStart`, `streamMode`, and/or integer `appOwnedMemoryBudgetMb` (64..4096; each optional, at least one required). Budget changes synchronously enforce the process-wide evictable retained-state cap; this is separate from RSS/native memory. `streamMode` persists the #314 stream-shape selection in config.json (Windows services need persisted input; macOS eager relay is explicit-only). |
| Config/settings | Read safe config/settings views; mutate supported settings only. Full `PUT /api/config` is disabled so masked secrets are not round-tripped. `PUT /api/settings` accepts `codexAutoStart`, `streamMode`, and/or integer `appOwnedMemoryBudgetMb` (64..4096; each optional, at least one required). Budget changes synchronously enforce the process-wide evictable retained-state cap; this is separate from RSS/native memory. `streamMode` persists the #314 stream-shape selection in config.json (Windows services need persisted input; macOS eager relay requires explicit config and a proven-fixed runtime). |
| Startup safety | `GET /api/startup-health` reports whether injected Codex routing is restart-safe, with secret-free service/shim diagnostics. `POST /api/startup-action` provides allowlisted one-click installation for the background service or launcher shim. On Windows a healthy script shim is CLI-only; Codex Desktop requires the background service for full protection. |
| Windows tray | `GET/POST /api/windows-tray` controls an owned, per-user HKCU login tray. The tray delegates fixed actions to the CLI and is never a proxy supervisor or restart-protection signal. |
| Updates | `GET /api/update/check`, `POST /api/update/run`, and `GET /api/update/status` own dashboard self-update state. A launched worker PID is persisted in `update-job.json`; dead PIDs recover immediately, while legacy active records without a PID recover only after ten minutes. Live PIDs remain exclusive regardless of record age. `GET /api/update/badge` backs the sidebar badge: it reports that an update exists and links to the update surface rather than gating other actions. |
Expand Down
8 changes: 6 additions & 2 deletions tests/bun-stream-caps.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -113,8 +113,12 @@ describe("selectEagerPath (platform policy matrix)", () => {
.toEqual({ useEagerRelay: true, reason: "auto-fixed-runtime" });
});

test("darwin + no rewrite + config-eager → eager", () => {
expect(selectEagerPath("darwin", false, "eager-relay", "1.3.14", null))
test("darwin + no rewrite + config-eager + known-bad runtime → tee", () => {
expect(selectEagerPath("darwin", false, "eager-relay", "1.3.14", null)).toBeNull();
});
Comment on lines +116 to +118

@coderabbitai coderabbitai Bot Aug 7, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Exercise the configured version boundary.

minFixed is null in this known-bad case. The assertion therefore exercises the “no threshold configured” branch. It does not prove that selectEagerPath rejects 1.3.14 when the fixed threshold is 1.4.0. Pass "1.4.0" as minFixed.

As per path instructions: a behavior change in src/ must have a focused regression test near the existing tests for that subsystem. This test should exercise the version gate, not only the unset-threshold fallback.

Proposed test correction 
-    expect(selectEagerPath("darwin", false, "eager-relay", "1.3.14", null)).toBeNull();
+    expect(selectEagerPath("darwin", false, "eager-relay", "1.3.14", "1.4.0")).toBeNull();
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
test("darwin + no rewrite + config-eager + known-bad runtime → tee", () => {
expect(selectEagerPath("darwin", false, "eager-relay", "1.3.14", null)).toBeNull();
});
test("darwin + no rewrite + config-eager + known-bad runtime → tee", () => {
expect(selectEagerPath("darwin", false, "eager-relay", "1.3.14", "1.4.0")).toBeNull();
});
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/bun-stream-caps.test.ts` around lines 116 - 118, Update the test case
around selectEagerPath to pass the configured fixed-version threshold "1.4.0"
instead of null, while preserving the existing inputs and null expectation so it
specifically verifies that version 1.3.14 is rejected by the version gate.

Source: Path instructions


test("darwin + no rewrite + config-eager + fixed runtime → eager", () => {
expect(selectEagerPath("darwin", false, "eager-relay", "1.4.0", "1.4.0"))
.toEqual({ useEagerRelay: true, reason: "config-eager" });
});

Expand Down
Loading