v0.8.59 execution roadmap: promoted provider, sub-agent, workflow, docs, and localization work

[Hmbown]

Problem

The v0.8.59 release line now includes work that was originally staged for v0.8.60: provider/model correctness, sub-agent architecture, WhaleFlow workflow authoring, README/site localization, and broader cleanup. Without an execution roadmap, this turns into a flat backlog where an agent can spend time on the wrong layer or accidentally start several heavy sub-agent/workflow changes before the current TUI reliability problems are contained.

This issue is the execution roadmap for the promoted v0.8.59 push.

Promotion note

On 2026-06-11, the open v0.8.60 issues were promoted to v0.8.59 and retitled where they had an explicit v0.8.60 prefix:

• v0.8.60: Add TypeScript/JavaScript workflow authoring for WhaleFlow-backed headless agents #3097 TypeScript/JavaScript workflow authoring for WhaleFlow-backed headless agents
• v0.8.61: Split sub-agents into a headless worker runtime with lightweight TUI projections #3096 Headless sub-agent worker runtime with lightweight TUI projections
• v0.8.59: Add next-wave README and website locales for Korean, Spanish, and Brazilian Portuguese #3093 Korean, Spanish, and Brazilian Portuguese README + website locales
• v0.8.59: Add Russian README and website localization with Cyrillic QA #3092 Russian README + website localization with Cyrillic QA
• v0.8.59: Bring the website to parity with existing Japanese and Vietnamese README locales #3091 Website parity with existing Japanese and Vietnamese README locales
• v0.8.59: Define README + website localization matrix, source text, and drift checks #3090 README + website localization matrix, source text, and drift checks
• v0.8.59 end-cap: Rewrite README with DeepSeek-TUI history, provider map, and factual onboarding #3087 README rewrite with DeepSeek-TUI history, provider map, and factual onboarding
• v0.8.59: Add a unified context-budget service for windows, output caps, compaction, and UI pressure #3086 Unified context-budget service for windows, output caps, compaction, and UI pressure
• v0.8.59: Build provider+model SKU pricing engine with provenance, unknown states, and UI integration #3085 Provider+model SKU pricing engine with provenance and UI integration
• v0.8.59: Introduce provider adapter contracts and conformance tests for capabilities, auth, and request dialects #3084 Provider adapter contracts and conformance tests
• v0.8.60: Group background tasks into workflows with phase summaries and collapsed Bash runs #3082 Workflow-style grouping for background tasks and Bash runs
• v0.8.65: Make web_search reliable with a SearXNG JSON backend, health checks, and visible agent status #3079 Reliable web_search via SearXNG JSON backend, health checks, and visible status
• v0.8.60: Add first-party MiniMax provider route #1310 First-party MiniMax provider route

This promotion does not mean every item is an equal release blocker. It means the v0.8.59 agent plan should pull these capability foundations forward and execute them in a sane order.

Operating rules for implementation agents

• Start with user-visible reliability and invalid defaults before architecture.
• Keep PRs narrow: one track or one coherent slice per branch.
• Do not launch large parallel sub-agent fanout until v0.8.59: Sub-agent fanout planning can leave the TUI stuck in provider wait with no backpressure or recovery #3095 and v0.8.59: API-timeout interrupted sub-agents can leave fanout UI and task handles stuck running #3080 have a recovery/backpressure path.
• README work belongs in v0.8.59 end-cap: Rewrite README with DeepSeek-TUI history, provider map, and factual onboarding #3087; do not rewrite README opportunistically in unrelated PRs.
• Workflow authoring in v0.8.60: Add TypeScript/JavaScript workflow authoring for WhaleFlow-backed headless agents #3097 must lower into typed WhaleFlow IR and Rust-owned execution; do not introduce arbitrary unsupervised Node/JS side effects.
• When a broad issue cannot be completed in one release-sized PR, land a documented contract, tests, and a compatibility path rather than a half-migration.
• Every PR should update the relevant issue with verification commands and remaining follow-up.

Roadmap

Track 0: Contain current v0.8.59 reliability and TUI breakage

Goal: make the app stop feeling stuck, misleading, or computer-heavy during normal usage.

Primary issues:

• v0.8.59: release tracker — TUI mouse-report leak, runtime safety, and current issue/PR queue #3063 release tracker
• v0.8.59: Sub-agent fanout planning can leave the TUI stuck in provider wait with no backpressure or recovery #3095 sub-agent fanout stuck in provider wait
• v0.8.59: API-timeout interrupted sub-agents can leave fanout UI and task handles stuck running #3080 interrupted sub-agents leave stale UI/task handles
• v0.8.59: Sidebar hover detail popovers are dropped during live turns #3088 sidebar hover detail popovers dropped during live turns
• Composer input corrupted by raw SGR mouse reports when mouse capture is disabled #3067 raw SGR mouse reports corrupt composer input
• Sidebar right-click shows "Paste" — should show sidebar-relevant actions #3065 sidebar right-click shows generic Paste
• Auto-clear completed sub-agent cards after completion to keep Activity sidebar tidy #3078 auto-clear completed sub-agent cards
• Stabilize resizable/collapsible sidebar controls from codewhale-rc for v0.8.59 #3077 resizable/collapsible sidebar controls
• Always stuck, I don't know the status of task! #1190 task status unclear/stuck
• SSE多智能体并行在windows11下依旧45s超时，并且还出现了UI错乱的问题 #1679 Windows SSE multi-agent timeout and UI corruption

Exit criteria:

• Long provider waits show actionable state, timeout, cancel, retry, and queued/running counts.
• Interrupted/cancelled sub-agents cannot leave stale running handles or fanout cards.
• Mouse capture, hover popovers, context menus, and composer input are verified together.
• Activity/sidebar cards do not grow into an unreadable wall during common multi-agent work.

Track 1: Make provider/model routing factual and API-backed

Goal: stop shipping invalid model IDs, stale provider claims, unknown pricing, and hard-coded model facts.

Primary issues:

• v0.8.59: OpenRouter Nemotron preset uses invalid model ID #3094 invalid OpenRouter Nemotron preset
• Introduce a model metadata registry instead of scattered hard-coded model facts #3071 model metadata registry
• Hydrate model catalog metadata from provider APIs with offline cache and provenance #3072 provider API hydration with offline cache/provenance
• Audit and migrate hard-coded model lists in picker, router, defaults, and prompt facts #3073 hard-coded model list audit/migration
• Provider-aware /model picker should search across model catalog and selectable providers #3075 provider-aware model picker search
• v0.8.59: Make /provider a capability and readiness dashboard, not just a hard-coded key picker #3083 provider dashboard/readiness surface
• v0.8.59: Introduce provider adapter contracts and conformance tests for capabilities, auth, and request dialects #3084 provider adapter contracts and conformance tests
• v0.8.59: Build provider+model SKU pricing engine with provenance, unknown states, and UI integration #3085 SKU pricing engine
• Cost tracking is dead for all non-DeepSeek models — pricing table needs expansion #3066 non-DeepSeek cost tracking
• OpenAI Codex/ChatGPT models need accurate context-window metadata and context pressure #3070 OpenAI Codex/ChatGPT context metadata
• Alphabetize provider ordering in model/provider UI to de-emphasize DeepSeek-first defaults #3076 provider ordering cleanup
• v0.8.60: Add first-party MiniMax provider route #1310 first-party MiniMax provider
• Feature Request: Provider fallback chain — auto-switch on API failure #2574 provider fallback chain
• v0.8.65: Make web_search reliable with a SearXNG JSON backend, health checks, and visible agent status #3079 reliable web_search backend/status

Suggested sequence:

1. Fix invalid presets and obvious route breakage first: v0.8.59: OpenRouter Nemotron preset uses invalid model ID #3094, Provider switch to OpenRouter can drop Authorization header after MiMo session #3064, v0.8.65: Make web_search reliable with a SearXNG JSON backend, health checks, and visible agent status #3079.
2. Establish a single registry/provenance model: Introduce a model metadata registry instead of scattered hard-coded model facts #3071, Hydrate model catalog metadata from provider APIs with offline cache and provenance #3072, Audit and migrate hard-coded model lists in picker, router, defaults, and prompt facts #3073.
3. Add provider conformance and readiness: v0.8.59: Introduce provider adapter contracts and conformance tests for capabilities, auth, and request dialects #3084, v0.8.59: Make /provider a capability and readiness dashboard, not just a hard-coded key picker #3083, Provider-aware /model picker should search across model catalog and selectable providers #3075.
4. Add pricing and context-window correctness: v0.8.59: Build provider+model SKU pricing engine with provenance, unknown states, and UI integration #3085, Cost tracking is dead for all non-DeepSeek models — pricing table needs expansion #3066, OpenAI Codex/ChatGPT models need accurate context-window metadata and context pressure #3070.
5. Add/verify MiniMax and fallback behavior: v0.8.60: Add first-party MiniMax provider route #1310, Feature Request: Provider fallback chain — auto-switch on API failure #2574.

Exit criteria:

• CodeWhale does not advertise OpenRouter model IDs absent from OpenRouter model metadata.
• Model picker, routing, docs, prompt facts, context windows, and pricing read from one documented metadata path or an explicitly generated cache.
• Unknown pricing/context states are displayed as unknown, not silently guessed.
• Provider readiness explains auth, endpoint, capabilities, model availability, and last metadata refresh.

Track 2: Unify context budgets, compaction, and stream pressure

Goal: make context/window pressure observable and consistent across model metadata, compaction, output caps, and UI state.

Primary issues:

• v0.8.59: Add a unified context-budget service for windows, output caps, compaction, and UI pressure #3086 unified context-budget service
• OpenAI Codex/ChatGPT models need accurate context-window metadata and context pressure #3070 context-window metadata
• There still seems to be some problems with cache hits缓存命中方面似乎还是有些问题 #1120 cache hit problems
• 报错：Stream stalled: no data received for 90s, closing stream。 #1060 stream stalled for 90s
• bug: thinking collapse - multiple root causes causing thinking blocks to freeze, truncate silently, or drop reasoning_content #861 thinking collapse/truncation/drop behavior

Exit criteria:

• Context windows, output caps, compaction thresholds, and UI pressure indicators share one budget service.
• Stalls/truncation/collapse paths expose clear user state and preserve model-readable recovery state.
• Tests cover small-window, large-window, unknown-window, compaction, and stalled-stream paths.

Track 3: Renovate sub-agents into headless workers and workflow orchestration

Goal: move from ad hoc fanout/TUI-shaped sub-agents to scheduler-owned workers, compact UI projections, and authorable workflows.

Primary issues:

• v0.8.59: Sub-agent fanout planning can leave the TUI stuck in provider wait with no backpressure or recovery #3095 immediate stuck fanout recovery
• v0.8.59: API-timeout interrupted sub-agents can leave fanout UI and task handles stuck running #3080 interrupted sub-agent cleanup
• v0.8.61: Split sub-agents into a headless worker runtime with lightweight TUI projections #3096 headless worker runtime
• v0.8.60: Group background tasks into workflows with phase summaries and collapsed Bash runs #3082 background task grouping/workflow summaries
• v0.8.60: Add TypeScript/JavaScript workflow authoring for WhaleFlow-backed headless agents #3097 TypeScript/JavaScript workflow authoring over WhaleFlow IR
• Proposal: universal PreToolUse/PostToolUse hook layer for Cancel/Pause/Resume across all action types #1917 universal hook layer for cancel/pause/resume
• Refactor command dispatch from monolithic match to modular strategy pattern #2791 modular command dispatch

Suggested sequence:

1. Add scheduler-visible states and backpressure around current sub-agent fanout: queued, starting, model_wait, running_tool, completed, failed, cancelled, interrupted.
2. Define AgentWorkerSpec / AgentWorkerEvent independent of Ratatui widgets.
3. Make TUI cards/sidebar consume worker events as a projection only.
4. Connect WhaleFlow leaves to the same worker contract rather than building a second scheduler.
5. Add JS/TS workflow authoring as a compile/lowering layer into typed WhaleFlow IR, not as an unsupervised Node runtime.

Exit criteria:

• A headless test can run worker lifecycle paths without constructing TUI cards.
• The user sees compact workflow progress rather than raw nested sub-agent rows.
• Cancellation/backpressure works before, during, and after model wait.
• JS/TS-authored workflows validate as typed IR before any worker launches.

Track 4: Clean up user-facing naming, legacy compatibility, and stale issue load

Goal: make the project look coherent after the DeepSeek-TUI -> CodeWhale rename without breaking compatibility.

Primary issues:

• v0.8.59: Show shell execution as Bash in user-facing UI, keep exec_shell internal #3081 show shell execution as Bash, keep exec_shell internal
• Rename DEEPSEEK_BLUE to WHALE_ACCENT_PRIMARY in consumer code #3069 rename DeepSeek color names in consumer code
• Audit and document legacy .deepseek/ compatibility paths — confirm migration status #3068 audit/document .deepseek/ compatibility paths
• Is it necessary to generate a .codewhale in every folder? #3058 clarify .codewhale per-folder behavior
• v0.8.66: Reactivate stale issue cleanup and consolidate duplicate pre-rename backlog #3089 stale issue cleanup and duplicate pre-rename backlog
• UI refactor needed #2766 UI refactor needed

Exit criteria:

• Normal UI does not expose implementation/tool IDs where a user-facing concept exists.
• Legacy DeepSeek paths are documented as compatibility, migrated, or intentionally retained.
• Stale issue automation exists before closing old issues in bulk.

Track 5: Docs, website, README, and localization endcap

Goal: make the public story match the product: DeepSeek-TUI history, CodeWhale rename, provider graph, supported/experimental/self-hosted routes, and real multilingual onboarding.

Primary issues:

• v0.8.59 end-cap: Rewrite README with DeepSeek-TUI history, provider map, and factual onboarding #3087 README rewrite
• v0.8.59: Define README + website localization matrix, source text, and drift checks #3090 localization matrix, source text, drift checks
• v0.8.59: Bring the website to parity with existing Japanese and Vietnamese README locales #3091 website parity with Japanese and Vietnamese README locales
• v0.8.59: Add Russian README and website localization with Cyrillic QA #3092 Russian README + website localization
• v0.8.59: Add next-wave README and website locales for Korean, Spanish, and Brazilian Portuguese #3093 Korean, Spanish, and Brazilian Portuguese locales
• Audit and document legacy .deepseek/ compatibility paths — confirm migration status #3068 legacy path docs
• Language has been configured to Chinese, but "thinking" outputs are still in English #1118 configured Chinese but thinking/status remains English
• 如何强制让模型推理的时候是特定语言的思考链路，而不是默认英文。 #683 force model reasoning language request

Exit criteria:

• README and website share a source localization matrix.
• Locales are grouped by support tier and verified for links, install commands, provider names, and screenshots/media references.
• Russian Cyrillic rendering is checked in README and website contexts.
• User-facing language settings affect app chrome/status where feasible, and model-language limitations are documented honestly.

Recommended first agent packet

If a single implementation agent starts now, execute in this order:

1. v0.8.59: Sub-agent fanout planning can leave the TUI stuck in provider wait with no backpressure or recovery #3095 + v0.8.59: API-timeout interrupted sub-agents can leave fanout UI and task handles stuck running #3080: contain stuck sub-agent/provider-wait behavior.
2. v0.8.59: OpenRouter Nemotron preset uses invalid model ID #3094: fix invalid OpenRouter model metadata immediately.
3. v0.8.59: Sidebar hover detail popovers are dropped during live turns #3088 + Composer input corrupted by raw SGR mouse reports when mouse capture is disabled #3067 + Sidebar right-click shows "Paste" — should show sidebar-relevant actions #3065: finish the mouse/sidebar input cleanup cluster.
4. Introduce a model metadata registry instead of scattered hard-coded model facts #3071 + Hydrate model catalog metadata from provider APIs with offline cache and provenance #3072 + Audit and migrate hard-coded model lists in picker, router, defaults, and prompt facts #3073: establish model metadata source of truth.
5. v0.8.59: Introduce provider adapter contracts and conformance tests for capabilities, auth, and request dialects #3084 + v0.8.59: Make /provider a capability and readiness dashboard, not just a hard-coded key picker #3083 + Provider-aware /model picker should search across model catalog and selectable providers #3075: provider conformance and user-facing readiness.
6. v0.8.59: Add a unified context-budget service for windows, output caps, compaction, and UI pressure #3086: context budget service, using metadata from the provider/model work.
7. v0.8.61: Split sub-agents into a headless worker runtime with lightweight TUI projections #3096 + v0.8.60: Group background tasks into workflows with phase summaries and collapsed Bash runs #3082: worker event contract and compact workflow projections.
8. v0.8.60: Add TypeScript/JavaScript workflow authoring for WhaleFlow-backed headless agents #3097: JS/TS workflow authoring layer lowered into WhaleFlow IR.
9. v0.8.59 end-cap: Rewrite README with DeepSeek-TUI history, provider map, and factual onboarding #3087 + v0.8.59: Define README + website localization matrix, source text, and drift checks #3090-v0.8.59: Add next-wave README and website locales for Korean, Spanish, and Brazilian Portuguese #3093: README/site/localization endcap.
10. v0.8.66: Reactivate stale issue cleanup and consolidate duplicate pre-rename backlog #3089: stale issue cleanup policy before any broad closure pass.

Verification

• gh issue list --state open --label v0.8.60 should remain empty unless maintainers intentionally reopen the v0.8.60 line.
• gh issue list --state open --label v0.8.59 should show all promoted issues and active release work.
• For code PRs: run the narrow package tests named in each linked issue, plus cargo test -p codewhale-tui or cargo test -p codewhale-whaleflow --locked when touching those areas.
• For docs/localization PRs: verify README links, website route links, provider/model naming, locale navigation, and install commands.
• For workflow/sub-agent PRs: manually run a multi-agent prompt and verify queued/running/done/cancelled states without an unreadable activity wall.

[Hmbown]

Contributor/PR triage update for v0.8.59:

Added #3099 as the release metadata cleanup issue and #3100 as the contributor-integration lane.

Recent user issue added to v0.8.59:

• feature: Per-theme accent/selection color override for dark themes #3074 — dark-theme selection/accent color override; user reports Signal Gold selection makes /sessions and /config unreadable in dark themes.

PRs now included in the v0.8.59 queue or metadata:

• fix: codewhale update error: GitHub release downloads may be blocked or slow on this network #3006 update reliability when GitHub downloads are blocked/slow
• feat(execpolicy): expose matched approval rule metadata #2971 exec-policy matched approval rule metadata
• fix(tui): normalize macOS SUPER (Cmd) to CONTROL for keyboard shortcuts (#2938) #2943 macOS Cmd/SUPER shortcut normalization
• i18n: localize Cmd command output messages (15 MessageIds) #2940/i18n: localize mode-picker messages #2932/i18n: localize pending-input preview messages #2929/i18n: localize onboard-welcome + app-mode-switch messages #2926/i18n: localize sidebar panel labels, status messages, and focus indicators #2921/feat(i18n): localize ConfigEdit labels and default values (11 MessageIds) #2919/feat(i18n): localize ConfigSection and ConfigScope labels (11 MessageIds) #2918/feat(i18n): localize ToolFamily labels (10 MessageIds) #2901/feat(i18n): localize SubAgents surface (19 MessageIds) #2899/feat(i18n): localize composer surface (16 MessageIds) #2894/feat: i18n Phase 1-4b wiring + rebase compile fixes #2239 i18n/localization surface work
• feat: build static linux x64 binaries with musl #2903 static Linux x64 binaries with musl
• fix(config): add separate siliconflow_cn provider config field with fallback #2895 separate siliconflow_cn provider config
• docs: align Hugging Face provider docs, errors, and tests with shipped route #2879 Hugging Face provider docs/errors/tests polish
• Refactor TUI command groups into focused implementations #2851 command strategy refactor draft, candidate for Refactor command dispatch from monolithic match to modular strategy pattern #2791
• feat(provider): complete provider fallback chain (#2574) #2773 provider fallback chain
• feat(runtime-api): add session save, undo/retry, and snapshot endpoints for GUI #2808 Runtime API session save/undo/retry/snapshot endpoints, promoted as a candidate but marked needs-human because lint/dirty state still needs resolution
• build(deps): bump actions/stale from 9 to 10 #2995 stale-action bump as cleanup support

Broad contributor PRs not pulled wholesale into v0.8.59, but tracked in #3100 for safe extraction/review:

• feat: hippocampal memory system, improved tool/subagent error messages, YOLO mode cleanup #2933 @cy2311 — extract YOLO verbosity/tool error/subagent error improvements first; defer SQLite memory unless maintainers explicitly want it in .59.
• Modernize toward latest Claude Code (prompts, hooks, skills, agents, UI) #2865 @lmclaw — broad Claude Code modernization; review slices for hooks (Proposal: universal PreToolUse/PostToolUse hook layer for Cancel/Pause/Resume across all action types #1917), sub-agent roles (v0.8.61: Split sub-agents into a headless worker runtime with lightweight TUI projections #3096/v0.8.60: Add TypeScript/JavaScript workflow authoring for WhaleFlow-backed headless agents #3097), prompts, and UI separately.
• Feat/whaleflow cost tracking #2486 @AdityaVG13 — WhaleFlow cost-tracking prior art; keep draft/v0.9 unless v0.8.59: Build provider+model SKU pricing engine with provenance, unknown states, and UI integration #3085/v0.8.60: Add TypeScript/JavaScript workflow authoring for WhaleFlow-backed headless agents #3097 extracts real accumulation/propagation.
• docs(contributing): harvest-credit close template + stewardship branch explanation #2986 — tiny docs/process PR, but failing Windows check; include only after check is explained or fixed.

Verification after sync:

• open v0.8.60 milestone queue is empty;
• open v0.8.59 label count and milestone count match at 59 issues;
• open PRs with v0.8.59 metadata are now milestoned as v0.8.59.

[Hmbown]

Added a Paulo-specific integration rule to #3101: review his work as a connected architecture stream, compare it seriously against current main, preserve the design intent when extracting staged PRs, and document any omitted pieces with concrete reasons.

[Hmbown]

Progress update (agent packet step 1):

• v0.8.59: API-timeout interrupted sub-agents can leave fanout UI and task handles stuck running #3080 — PR fix(tui): emit interrupted sub-agent lifecycle event and reconcile stale running cards (#3080) #3103 open, CI green: MailboxMessage::Interrupted emitted from the API-timeout path, new AgentLifecycle::Interrupted card state, and AgentList snapshot reconciliation so stale Running card slots can no longer pin sidebar/fanout running counts. Regression tests cover the mailbox envelope, card states, fanout count drop, and snapshot reconciliation.
• Next: v0.8.59: Sub-agent fanout planning can leave the TUI stuck in provider wait with no backpressure or recovery #3095 (fanout preflight states, footer provider/model + timeout budget, fanout backpressure guardrail, cancel recovery) as its own PR; the footer/stall-reason bullet from v0.8.59: API-timeout interrupted sub-agents can leave fanout UI and task handles stuck running #3080's acceptance will be handled there.