feat(gui): expose sub-agent fallback settings

[x3M3x]

Summary

Expose and improve sub-agent fallback settings in the dashboard, and add an explicit switch that makes the fallback chain use the configured subagentModels roster.

• Dashboard fallback chain editor: ordered add/remove/reorder controls for subagentModelFallback, availability polling interval, and save state via /api/subagent-model-fallback.
• New opt-in switch: subagentModelFallbackUseSubagentModels. When enabled for spawned sub-agents, subagentModels is the complete ordered fallback list; global, per-model, and legacy TOML fallback entries are ignored. An unset or empty roster produces no fallback.
• Encrypted V2 safety: encrypted V2 tasks still restrict candidates to canonical native ChatGPT targets, and the switch is opt-in because roster entries may use native ChatGPT credentials.
• API and docs: GET/PUT /api/subagent-model-fallback persists the boolean, with focused runtime/API/GUI coverage and updated configuration guidance.

Difference between the two lists

subagentModels is the featured ordered roster shown in the sub-agent picker. subagentModelFallback is the separately configured failover chain. With the switch enabled, the roster becomes the complete fallback chain for spawned sub-agents and the separate fallback settings are ignored.

Verification

• bun run typecheck — pass
• bun run build from gui — pass
• bun test ./gui/tests/subagents-fallback.test.ts --max-concurrency=1 — passed during focused validation; a later rerun was blocked by Bun's existing Windows user-lock contention
• git diff --check — pass
• Runtime fallback tests cover switch-on, switch-off, and empty/unset roster behavior. Windows can intermittently reproduce the repository's known atomic-write temp-file ENOENT race.

UI screenshot

The Subagents dashboard now shows the fallback chain as readable stacked rows with separate controls, an add-model row, polling interval, roster-reuse switch, and save action:

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed.
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults.
• Behavior changes in src/ and gui/src/ have focused regression tests.

Review readiness checklist

This PR stays in draft until every box below is ticked. Tick all four boxes once the requirements are met:

• All CI tests are green on my local testing.
• I pushed my PR to the latest dev commit.
• I resolved all correct Codex and CodeRabbit findings.
• My PR is ready for review.

[x3M3x]

This follow-up is the GUI half split from closed PR #3228. The runtime auto-native fallback remains reverted per #3242; this PR only exposes the existing /api/subagent-model-fallback configuration route in the dashboard.

The branch is based on the current dev tip and includes the required UI screenshot.

[github-actions]

⚠️ Deterministic hygiene checks failed.

• missing_regression_test — Behavior changed under src/ or gui/src/ without a test change. Add focused coverage or obtain test-exception-approved.

[github-actions]

⏳ DRAFT

• review readiness checklist open (2/4 boxes ticked).

What to do

• Tick all four boxes in the PR description once you're done (currently 2/4).

Review readiness checklist

• ⬜ All CI tests are green on my local testing.
• ✅ I pushed my PR to the latest dev commit.
• ✅ I resolved all correct Codex and CodeRabbit findings.
• ⬜ My PR is ready for review.

2/4 boxes ticked.

This PR stays in draft until every box above is ticked.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[lidge-jun]

리뷰 · 우선순위 47 / 80

이 PR은 서브에이전트 폴백 체인을 대시보드에서 편집하게 하고, 암호화 V2 네이티브 전용 경로에서 추천 로스터(subagentModels)를 폴백으로 재사용할지 고르는 옵트인 스위치를 더한다. 설정 키는 subagentModelFallbackUseSubagentModels이다. 기본값은 꺼짐이다. 지금 dev HEAD는 #3239–#3242 암호화 V2 서브에이전트 복구와 관련 Private Inference 스택을 이미 흡수한 상태다. 런타임 src/codex/subagent-model-fallback.ts의 applySubagentModelFallback은 nativeFallbackOnly일 때 명시 체인이 없으면 조용히 포기하는 쪽에 가깝다. 이 PR은 그 빈칸을 GUI·API·문서로 메우려 한다.

구성은 세 층이다. (1) GUI: gui/src/pages/Subagents.tsx와 SubagentDelegationSection.tsx에 순서 편집·폴링 간격·로스터 재사용 토글·저장. (2) API: GET/PUT /api/subagent-model-fallback에 useSubagentModels boolean. (3) 런타임: nativeFallbackOnly이고 옵트인이 켜져 있고 subagentModels가 있을 때만 normalizedChain(..., subagentModels)로 체인을 바꾼다. 문서(docs-site/.../agents.md, sub-agent-surface.md)와 9개 로케일 키도 같이 온다. 닫힌 #3228/#3253을 한 PR로 합친 형태다.

보안 방향은 HEAD의 #3242 결정과 맞다. 네이티브 ChatGPT 자격 증명을 쓰는 모델을 조용히 폴백에 넣지 않고, 대시보드에서 명시로 켠 때만 로스터를 쓴다. 로스터가 비어 있으면 합성 폴백을 만들지 않는다. 테스트도 스위치 on/off/unset 경로를 tests/subagent-model-fallback.test.ts와 API 테스트에 넣었다.

점수가 낮은 이유다. 첫째, src/types/config.ts와 src/config.ts에 필드를 추가한다. types/config 분할 캠페인과 겹치는 핫 파일이다. 작은 optional boolean이라 즉시 무효화까지는 아니지만, 분할 PR과 끼워 넣으면 충돌·리베이스 비용이 난다. 둘째, GUI 로드 경로에 상태 반영 구멍이 있다. 셋째, 아직 draft이고 화면/설정 표면이 커서 Fast·암호화 복구 직후 안정화 구간과 우선순위가 겹친다.

기능 자체는 암호화 V2 복구 열차의 자연스러운 후속이다. 다만 ‘지금 바로 넣어야 하는 작은 구멍’보다는 ‘옵트인 GUI + 설정 키’에 가깝다. 중복 원본(#3253)은 이미 닫혔고 이 PR이 통합본이므로 닫지 말고 다듬는 쪽이 맞다.

gui/src/pages/Subagents.tsx / loadSubagents - 서버에서 useSubagentModels를 읽어 next에는 넣지만 setUseSubagentModels(next.useSubagentModels)를 호출하지 않음. 캐시가 false이거나 이전 세션 값이면 토글이 서버 값과 어긋난 채 남을 수 있음
gui/src/pages/Subagents.tsx / saveFallback - if (d?.pollMs)는 0을 무시함(현재 최솟값 5000이라 실무 영향은 작음). useSubagentModels는 !== undefined로 잘 처리함
gui/src/i18n/en.ts / sub.fallbackUseRoster - 문구가 ‘추천 로스터를 폴백 목록으로 쓴다’처럼 일반 폴백 전체에 적용되는 느낌. 문서·런타임은 암호화 V2 native-only에만 적용. 라벨을 좁혀야 함
src/codex/subagent-model-fallback.ts - 옵트인 시 configuredFallbackChain / 명시 subagentModelFallback을 통째로 로스터로 교체함. 의도라면 주석·GUI 힌트에 ‘암호화 네이티브 전용이며 기존 폴백 체인을 이 경로에서 대체한다’고 더 분명히
src/types/config.ts / src/config.ts - 분할 캠페인 핫 파일에 키 추가. 지금은 close-don't-rebase 대상은 아니나 분할 열차와 끼우지 말 것
경로/심볼 - SubagentDelegationSection 이동/삭제 버튼이 한 줄 JSX로 뭉쳐 있어 리뷰·접근성 수정이 어려움
라인 - draft 체크리스트에 CI·ready 미체크

메인테이너의 판단이 필요한 지점

• types/config 분할 전에 이 키를 넣을지, 분할 랜딩 직후로 미룰지
• 로스터 재사용이 암호화 native-only에서 기존 subagentModelFallback을 완전히 대체하는 것이 제품 의도인지 (아니면 로스터를 앞에 붙이거나 비어 있을 때만 쓸지)
• fix: auto-fallback encrypted V2 spawns to native Codex #3228 계열 GUI만 먼저 넣고 런타임 스위치는 별도 PR로 나눌지

너의 추천
닫지 않는다. 통합본(#3253 대체)으로 유지한다. 머지 전에 (1) loadSubagents에 setUseSubagentModels 추가, (2) i18n 문구를 암호화 V2 native-only 범위로 수정, (3) types/config 분할 PR과 동시에 넣지 말 것을 요청한다. 그 다음 draft 해제·CI 그린 후 dev에 넣는다. 지금은 Fast/Private Inference/암호화 복구 직후라 급하지 않다. 라벨 유지, 자동 닫기 하지 않음.

이 댓글은 grok-bot이 작성했습니다

[x3M3x]

Implemented and pushed in 914aaaf.

• The switch now makes subagentModels the complete ordered fallback chain for spawned sub-agents; global, per-model, and TOML fallback entries are ignored while enabled. Empty/unset roster means no fallback.
• Restored the switch from the server response on every load.
• Tightened the UI label to state the exact behavior and kept the fallback editor in readable stacked rows.
• Updated docs and refreshed the PR screenshot/body.

Validation: typecheck, GUI build, focused GUI test (prior run), and diff check passed. The remaining local limitation is the known Windows Bun user-lock/atomic-write ENOENT race; CI checks currently pass.

[x3M3x]

Polished the fallback-chain editor in a7f7ddb: compact icon-only reorder/remove actions, improved spacing for the interval/toggle/save controls, and responsive stacking for narrow dashboard widths. Refreshed screenshot: docs-site/public/pr-screenshots/subagent-fallback-settings-v2.png.