fix(cli): bound the goal-runtime startup wait and skip the no-op Bun memory relaunch

[chiga0]

What this PR does

Two small startup-path robustness fixes on the default (ink) renderer path. First, the goal-runtime readiness wait at startup is now bounded by a 5-second timeout; when the runtime cannot settle in time the TUI continues with goal features degraded instead of hanging. Second, the automatic memory-flag relaunch is skipped entirely under Bun, where the flag has no effect.

Why it's needed

The goal runtime signals readiness through a session-writer lease. When the lease is contended — a crashed or sibling process still holding it — the readiness promise never settles, and startup blocks before the command registry is populated. The result is a TUI where every slash command, including /quit, answers "Unknown command" and the only escape is killing the process. Bounding the wait trades degraded goal features for a usable CLI, which is the strictly better outcome for the user. Separately, Bun accepts --max-old-space-size but ignores it (its heap limit starts small and adapts dynamically), so the memory-configuration relaunch under Bun only wastes a process hop on every startup.

Both fixes are extracted from the OpenTUI migration work (#8677), where they were reviewed and regression-tested; they land here standalone because they benefit the current ink renderer immediately and carry no dependency on the migration batches tracked in #8662.

Reviewer Test Plan

How to verify

1. The timeout path is covered by three new unit tests (timeout fires on a never-settling promise; normal settle still returns true; a late rejection after the timeout cannot become unhandled). Run: cd packages/cli && npx vitest run src/ui/utils/goal-runtime.test.ts src/ui/AppContainer.test.tsx src/gemini.test.tsx — 239 tests pass.
2. The other two call sites of the wait helper (branch/resume commands) pass no timeout and keep the original unbounded semantics; the signature change is backwards compatible (Promise<boolean> return may be ignored).
3. Reproducing the hang manually requires holding the session-writer lease with a crashed sibling process; the unit test simulates the same never-settling promise instead.

Evidence (Before & After)

N/A (no user-visible rendering change; behavior change is only on the previously-hung path, where the CLI now starts with goal features degraded and logs a warning)

Tested on

OS	Status
🍏 macOS	✅
🪟 Windows	⚠️
🐧 Linux	⚠️

Environment (optional)

npm run build, npm run typecheck, unit tests under Node 22.23.1.

Risk & Scope

• Main risk or tradeoff: under genuine lease contention the startup gate now proceeds after 5s with goal features degraded instead of hanging forever; a debug warning marks the degraded path.
• Not validated / out of scope: the branch/resume command wait paths remain unbounded by design (user-initiated waits, different UX); Bun behavior verified by code inspection of Bun's flag handling, not a Bun E2E run.
• Breaking changes / migration notes: none.

Linked Issues

Part of the incremental landing tracked in #8662 (originally scheduled with the renderer-activation batch; pulled forward because both fixes benefit the ink renderer directly).

中文说明

本 PR 做了什么

两个启动路径上的健壮性小修复，都在默认（ink）渲染器路径上。其一，启动时等待 goal runtime 就绪增加 5 秒超时上限：超时后 TUI 以 goal 功能降级的方式继续启动，而不是永久挂起。其二，在 Bun 下完全跳过内存参数重启流程，因为该参数在 Bun 下无效。

为什么需要

goal runtime 通过 session-writer 租约通知就绪状态。当租约被争用——例如崩溃的或并行的兄弟进程仍持有租约——就绪 promise 永不落定，启动会卡在命令注册表填充之前。结果就是整个 TUI 里所有斜杠命令（包括 /quit）都返回 "Unknown command"，唯一出路是杀进程。给等待设上限，是用 goal 功能降级换取可用的 CLI，对用户是严格更优的结果。另外，Bun 接受 --max-old-space-size 但实际忽略它（其堆上限从很小起步并动态自适应），所以 Bun 下的内存配置重启每次启动都白白浪费一次进程跳转。

两个修复都提取自 OpenTUI 迁移工作（#8677），在那里已经过评审和回归测试；这里单独落地，因为它们立即惠及当前的 ink 渲染器，且不依赖 #8662 跟踪的任何迁移批次。

评审测试计划

如何验证

1. 超时路径由三个新增单测覆盖（永不落定的 promise 触发超时；正常就绪仍返回 true；超时后的迟到 reject 不会变成 unhandled rejection）。运行：cd packages/cli && npx vitest run src/ui/utils/goal-runtime.test.ts src/ui/AppContainer.test.tsx src/gemini.test.tsx——239 个测试通过。
2. 等待 helper 的另外两个调用点（branch/resume 命令）不传超时，保持原有无界语义；签名变更向后兼容（Promise<boolean> 返回值可忽略）。
3. 手工复现挂起需要用崩溃的兄弟进程持有 session-writer 租约；单测用等价的永不落定 promise 模拟了同样场景。

前后对比证据

N/A（无用户可见渲染变化；行为变化只发生在原先挂起的路径上——现在 CLI 会以 goal 功能降级启动并打印一条 warning 日志）

测试环境

操作系统	状态
🍏 macOS	✅
🪟 Windows	⚠️
🐧 Linux	⚠️

环境（可选）

Node 22.23.1 下的 npm run build、npm run typecheck、单元测试。

风险与范围

• 主要风险或权衡：真正的租约争用下，启动门禁现在会在 5 秒后以 goal 功能降级继续，而不是永久挂起；降级路径有 debug warning 标记。
• 未验证 / 范围外：branch/resume 命令的等待路径按设计保持无界（用户主动发起的等待，UX 语义不同）；Bun 行为依据其对标志的处理方式做了代码走查，未做 Bun E2E 运行。
• 破坏性变更 / 迁移说明：无。

关联 Issue

属于 #8662 跟踪的增量落地的一部分（原计划随 renderer-activation 批次落地；因两个修复都直接惠及 ink 渲染器而提前）。

[qwen-code-ci-bot]

✅ Qwen Triage finished — CI landed green on 89fd723 and the deferred approval was posted. finalize run

✅ Qwen Triage 已完成 —— 89fd723 的 CI 全绿，延迟审批已提交。查看 finalize 运行

[qwen-code-ci-bot]

Thanks for the PR!

Template looks good ✓

Problem: The failure mode is real in shape: AppContainer awaits getGoalRuntimeReady() before setConfigInitialized(true), so if that readiness chain ever stalls, the TUI boots into a state where the command registry is never populated — every slash command, /quit included, answers "Unknown command". That said, I could not trace the specific trigger described (lease contention) on current main: a dead holder's lease is reclaimed via the stale-detection path (bounded, 8 attempts), and a live holder throws SessionWriterConflictError, so config.initialize() rejects rather than hangs. So this reads as defense-in-depth against the stall class on a brand-new startup gate (the goal runtime landed on main only days ago) rather than a fix for a reproduced hang — no linked issue or user report exists, and manual reproduction would need a stalled lease. The risk asymmetry makes the bound worth having anyway: worst case with the timeout is goal features degrading after 5s with a debug breadcrumb, versus a TUI that needs kill -9. Also worth noting: the identical change already lives on the OpenTUI migration branch (feat/opentui-migrate), where the "Unknown command" startup window is a known symptom class — this is a faithful extraction of reviewed work, not a new invention.

Direction: aligned — startup robustness on the default ink path, extracted standalone from the in-flight migration work per #8662 so it benefits the current renderer now. The Bun half is independently verifiable: Bun is not V8, --max-old-space-size is accepted but ignored, and v8.getHeapStatistics() under Bun doesn't describe a V8 heap — so computing and passing that flag there is pure noise.

Size: no core-module paths touched (all packages/cli/src/ui/** plus gemini.tsx): ~77 production lines + ~54 test lines across 4 files. Core gate not applicable.

Approach: minimal and backwards compatible — the options bag keeps the branch/resume call sites unbounded by design, getGoalRuntimeReady() is still called exactly once, and the Bun guard is a two-line early return. Nothing to cut.

Risk: no high-risk paths matched (Stage 1e check ran clean). No elevated risk signals.

Moving on to code review. 🔍

中文说明

感谢贡献！

模板完整 ✓

问题： 故障形态是真实的：AppContainer 在 setConfigInitialized(true) 之前等待 getGoalRuntimeReady()，如果该就绪链卡住，TUI 会停在命令注册表未填充的状态——所有斜杠命令（包括 /quit）都返回 "Unknown command"。不过，我未能在当前 main 上追踪到描述的具体触发条件（租约争用）：死亡持有者的租约会经由 stale 检测路径被回收（有界，8 次尝试），存活持有者会抛 SessionWriterConflictError，使 config.initialize() 失败而非挂起。所以这更像是对一个全新启动门禁（goal runtime 几天前才落地 main）的卡死类问题的防御性加固，而非修复一个已复现的挂起——没有关联 issue 或用户报告，手工复现需要一个卡住的租约。风险不对称性使这个上限值得加：超时的最坏结果是 goal 功能降级、5 秒后继续（带 debug 日志），而对立面是需要 kill -9 的 TUI。另外：同样的改动已在 OpenTUI 迁移分支（feat/opentui-migrate）上存在，那里 "Unknown command" 启动窗口是已知症状类——这是对已评审工作的忠实提取，不是新发明。

方向： 对齐——默认 ink 路径的启动健壮性，按 #8662 从进行中的迁移工作里单独提取落地，使当前渲染器立即受益。Bun 部分可独立验证：Bun 不是 V8，--max-old-space-size 被接受但被忽略，Bun 下 v8.getHeapStatistics() 描述的也不是 V8 堆——所以在那里计算并传递该标志纯属噪音。

规模： 未触及核心模块路径（全部为 packages/cli/src/ui/** 加 gemini.tsx）：4 个文件约 77 生产行 + 约 54 测试行。核心门禁不适用。

方案： 最小且向后兼容——options 参数使 branch/resume 调用点按设计保持无界，getGoalRuntimeReady() 仍只被调用一次，Bun 守卫是两行提前返回。没有可砍的部分。

风险： 未命中高风险路径（Stage 1e 检查通过）。无升级风险信号。

进入代码审查 🔍

— Qwen Code · qwen3.8-max

_{Reviewed at 89fd7231b79b96126e8df6d7c2a36a4ff4f30341 · re-run with @qwen-code /triage}

[qwen-code-ci-bot]

Code review

I wrote down my own proposal before reading the diff: for the hang, wrap the startup wait in a Promise.race against an unref'd timer that degrades instead of throwing, keep the helper's original semantics (swallow GoalPersistenceUnavailableError, rethrow everything else), and leave the other call sites unbounded; for Bun, early-return no memory args when process.versions.bun is set. The PR does exactly this — no simpler path was missed.

The implementation details check out: getGoalRuntimeReady() is invoked exactly once (a test asserts it), Promise.race keeps a handler on the losing promise so a late rejection cannot escape as unhandled (also tested), the timer is cleared in finally and unref()'d so it never holds the process open on its own, and timeoutMs <= 0 falls back to the original unbounded semantics. The branch/resume call sites pass no timeout and keep their current behavior — the signature change (Promise<boolean>) is backwards compatible for them.

Two non-blocking notes:

1. The degraded path logs via debugLogger.warn only — invisible without QWEN_CODE_DEBUG=1. If a user hits this in the wild they get a working-but-goal-less TUI with no hint why. Routing it through mergeStartupWarnings like other degraded-startup conditions would make it self-explanatory. Fine to defer; debug-channel logging matches this file's existing convention for startup issues.
2. Minor framing nit on the Bun comment: the one-process relaunch is architecturally unconditional (relaunchAppInChildProcess always spawns the restartable child), so this change stops passing a no-op V8 flag into the relaunch/sandbox child rather than eliminating a hop. Outcome is right either way; the comment slightly overstates the saving.

Nothing blocking.

Testing

CI on the reviewed commit, read through the API (PR code is never executed in triage): the ubuntu Node 22 unit suite is green, precheck / secret scan / CVE audit / Desktop Shell (ubuntu + windows) all pass, zero failed checks. The macOS/Windows unit legs and the CLI integration tests were skipped by the CI profile classifier, and the web-shell E2E smoke is still in flight under the Qwen Code CI run. The table below is updated in place by the finalize workflow once CI settles.

Final CI results for 89fd723 (auto-updated by the triage finalize job after CI completed):

Check	Conclusion
Classify PR	✅ success
Dependency CVE audit	✅ success
Desktop Shell (ubuntu-22.04)	✅ success
Desktop Shell (windows-2022)	✅ success
Secret scan (TruffleHog)	✅ success
Test (ubuntu-latest, Node 22.x)	✅ success
web-shell E2E Smoke (ubuntu-latest, Node 22.x)	✅ success

_{One row per check name (latest run); skipped checks omitted; failures sort first. / 每个检查名一行（取最新一次运行），省略 skipped，失败项排在最前。}

The three new unit tests pin the mechanism itself: a never-settling readiness promise resolves false after the timeout, a normal settle still resolves true, and a post-timeout rejection cannot become an unhandled rejection. They fail without the diff, so the suite is load-bearing for the change. The author's report of 239 passing tests across the three affected suites is their own run, not independently re-run here.

What the suite does not settle: that the TUI actually continues into a usable command registry after the timeout fires — the unit tests stop at the helper returning false, and no AppContainer test covers the degraded continuation. Sandboxed verification would settle this: @qwen-code /verify — an A/B against the base build proving healthy startup is unchanged and the degraded path reaches a working slash-command registry. (The contention trigger itself can't be exercised there either — it needs a stalled lease, which is the part that remains inferred rather than observed on current main.)

中文说明

代码审查

读 diff 前我先独立写下方案：挂起问题用 Promise.race 包一个 unref 定时器，超时降级而非抛错，保留 helper 原语义（吞掉 GoalPersistenceUnavailableError、其余重抛），其他调用点保持无界；Bun 问题在 process.versions.bun 时提前返回空内存参数。PR 的实现与此一致——没有错过更简路径。

实现细节正确：getGoalRuntimeReady() 只调用一次（有测试断言），Promise.race 对输掉的 promise 保留 handler，超时后的迟到 reject 不会逃逸为 unhandled rejection（同样有测试），定时器在 finally 中清理且 unref()、不会独自拖住进程，timeoutMs <= 0 回退到原有无界语义。branch/resume 调用点不传超时，行为不变——签名变更（Promise<boolean>）对它们向后兼容。

两个非阻塞意见：

1. 降级路径只走 debugLogger.warn——不开 QWEN_CODE_DEBUG=1 就看不见。用户真遇到时会得到"能用但 goal 失效"的 TUI 而毫无线索。若像其他启动降级状态一样并入 mergeStartupWarnings 会更自解释。可以后续再做；debug 通道记录与本文件现有惯例一致。
2. Bun 注释的小瑕疵：一次性进程中转在架构上无条件发生（relaunchAppInChildProcess 总会派生可重启子进程），所以此改动实际是停止向中转/沙箱子进程传递无效的 V8 标志，而非省掉一次中转。结果正确，注释略微夸大了收益。

无阻塞问题。

测试

审查提交上的 CI，经 API 读取（triage 从不执行 PR 代码）：ubuntu Node 22 单测套件绿，precheck、密钥扫描、CVE 审计、Desktop Shell（ubuntu + windows）全部通过，无任何失败检查。macOS/Windows 单测腿和 CLI 集成测试被 CI profile 分类器跳过，web-shell E2E smoke 仍在 Qwen Code CI 运行中。下表由 finalize workflow 在 CI 落定后就地更新。

三个新单测钉住了机制本身：永不落定的就绪 promise 在超时后解析为 false，正常就绪仍解析 true，超时后的迟到 reject 不会变成 unhandled rejection。没有 diff 这些测试会失败，因此套件对改动是有效的。作者报告的三个套件 239 个测试通过是其自述结果，未在此独立复跑。

套件未覆盖的是：超时触发后 TUI 是否真正继续到可用的命令注册表——单测止步于 helper 返回 false，AppContainer 没有覆盖降级续行的测试。沙箱验证可以补齐：@qwen-code /verify——与 base build 做 A/B，证明正常启动不受影响且降级路径能到达可用的斜杠命令注册表。（争用触发条件本身在那里也无法演练——它需要卡住的租约，这部分在当前 main 上仍是推断而非观测。）

— Qwen Code · qwen3.8-max

_{Reviewed at 89fd7231b79b96126e8df6d7c2a36a4ff4f30341 · re-run with @qwen-code /triage}

[qwen-code-ci-bot]

Confidence: 4/5 — minimal, well-tested robustness fix whose direction is corroborated by the maintainer's own migration branch; the one open question (whether the lease-contention hang actually fires on current main) is noted, not blocking.

Stepping back: this PR does two small things and does them right. The bounded goal-runtime wait is exactly the shape I'd have chosen — race against an unref'd timer, degrade instead of fail, original semantics preserved for the callers that opt out, and a test suite that fails without the diff. The worst outcome of adding the bound is a 5-second degraded start with a debug breadcrumb; the worst outcome of not having it is a TUI where /quit doesn't work and the only exit is kill -9. On a startup gate that landed on main only days ago, that asymmetry is enough for me — even though I couldn't trace the exact contention trigger on current main (dead holders get reclaimed by the stale path, live holders throw a conflict error). The Bun skip is independently correct: the flag is a no-op there, so stop computing and passing it.

The diff carries nothing beyond the stated goal — no drive-bys, no churn. Both fixes are identical to what already went through review on the OpenTUI migration branch, and landing them now benefits the ink renderer directly, as claimed.

Reservations, stated plainly: (1) the trigger premise (lease contention → permanent hang) is inferred, not observed — I'd like to see a real-world report eventually, but the defensive bound is cheap insurance either way; (2) the degraded continuation after the timeout has no AppContainer-level test; (3) the degraded state is silent without debug logging. None of these block merge; (2) is the part a maintainer-triggered @qwen-code /verify would pin down with load-bearing proof if they want it before merge.

CI is not fully settled at review time (the unit suite is green; the web-shell E2E smoke is still in flight under Qwen Code CI), so approval is deferred until CI lands green on the reviewed commit — the finalize workflow performs the commit-pinned approval if everything comes back green.

中文说明

置信度：4/5 —— 最小化、测试良好的健壮性修复，方向由维护者自己的迁移分支佐证；唯一的疑问（租约争用挂起是否真的会在当前 main 上触发）已注明，不构成阻塞。

退一步看：这个 PR 做了两件小事，都做对了。有界的 goal-runtime 等待正是我会选择的形态——与 unref 定时器赛跑、降级而非失败、为不传超时的调用点保留原语义，且测试套件在没有 diff 时会失败。加上界的最坏结果是带 debug 日志的 5 秒降级启动；不加界的最坏结果是 /quit 都失效、只能 kill -9 的 TUI。对于一个几天前才落地 main 的启动门禁，这个不对称性足以支持合入——尽管我没能在当前 main 上追踪到确切的争用触发路径（死亡持有者由 stale 路径回收，存活持有者抛冲突错误）。Bun 跳过独立成立：该标志在那里无效，所以不再计算和传递。

diff 没有超出既定目标的任何内容——没有顺手改动，没有无关噪音。两个修复与已在 OpenTUI 迁移分支上通过评审的版本一致，现在落地确实如所述直接惠及 ink 渲染器。

保留意见，直说：(1) 触发前提（租约争用 → 永久挂起）是推断而非观测——希望将来看到真实报告，但这个防御性上限无论如何都是便宜的保险；(2) 超时后的降级续行没有 AppContainer 级测试；(3) 降级状态在不开 debug 日志时无任何提示。这些都不阻塞合入；(2) 是维护者若想在合入前拿到有效证据时值得触发 @qwen-code /verify 的部分。

审查时 CI 尚未完全落定（单测套件已绿；web-shell E2E smoke 仍在 Qwen Code CI 中运行），因此批准推迟到 CI 在审查提交上落绿——若全部转绿，finalize workflow 会执行提交绑定的批准。

— Qwen Code · qwen3.8-max

_{Reviewed at 89fd7231b79b96126e8df6d7c2a36a4ff4f30341 · re-run with @qwen-code /triage}

[qwen-code-ci-bot]

LGTM, looks ready to ship — CI landed green after the review. ✅

[chiga0]

Thanks for the thorough triage — both non-blocking notes are now addressed in f8c01dc377:

1. Degraded-path visibility: the startup timeout now routes through mergeStartupWarnings, so a goal-degraded startup surfaces a visible warning ("Goal features are degraded: the goal runtime did not settle within 5000ms at startup.") without QWEN_CODE_DEBUG=1.
2. Bun comment framing: reworded to state that the one-process relaunch is unconditional and the guard only stops forwarding a no-op V8 flag into the relaunch/sandbox child.

goal-runtime (6) and AppContainer (157) unit suites pass locally; typecheck clean.

[yiliang114]

Reviewed at head f8c01dc:

• waitForGoalRuntime timeout race is correct: Promise.race keeps a handler on the losing promise (a late rejection of the goal-runtime promise cannot become unhandled — pinned by test), the timer is unrefed and cleared in finally, and omitting timeoutMs preserves the original unbounded semantics for the resume/branch call sites.
• Degraded-startup path is visible: a startup warning is surfaced when the goal runtime does not settle within 5s.
• Bun: 'bun' in process.versions short-circuits getNodeMemoryArgs before the os/v8 reads; the relaunch itself is unconditional, so this only stops forwarding a no-op flag.
• Verified locally: vitest run packages/cli/src/ui/utils/goal-runtime.test.ts — 6/6 passed; full monorepo build passes. CI green; PR body matches the template.

[qqqys]

Approving. Independent review at this head (f8c01dc3) found no blocking (Critical) issues: the goal-runtime startup gate is correctly bounded (single getGoalRuntimeReady() call raced against an unref'd timer, Promise.race preventing unhandled late rejections, timeout cleared in finally), the no-timeout path preserves the original unbounded semantics for other callers, and a timed-out startup degrades gracefully with a surfaced warning instead of leaving the TUI unusable; the Bun relaunch change only stops forwarding a no-op flag. Tests pin the settle/never-settles/late-rejection paths. A maintainer (admin) has approved at this head and all ran CI lanes are green; concur.

[qwen-code-ci-bot]

Released in v0.22.3.