luna/oh-my-opencode
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(known-issues): document delegate-task empty-history fallback (BLOCKER-4)

Browse Source 
PR #3825's fac90d69f introduced a shared bootstrap context to fix delegated child-session fallback when the first prompt fails before any session history is persisted. PR #4044 reverted that fix because its own regression test failed on a clean root suite (6828 pass / 1 fail). The bug remains unaddressed in v4.2.0; reland is deferred.

This commit documents the symptom, history, workaround, and tracking issue so users have visibility.

Closes BLOCKER-4 via Path B (documentation).

Refs PR #3825, PR #4044, issue #4059.
This commit is contained in:
YeonGyu-Kim
2026-05-16 01:29:16 +09:00
parent 0941ffe7f3
commit 38732b426e
1 changed files with 16 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/reference/known-issues.md
+16 -6
View File
@@ -1,19 +1,29 @@
# Known Issues
## v4.2.0 - Delegate-task early-failure-fallback (BLOCKER-4, deferred from PR #3825)
Tracks bugs that are present in the current release but have been intentionally deferred. Each entry should explain the symptom, the history, any workaround, and the planned resolution.
## v4.2.0 - Delegated child-session early-failure fallback (PR #3825 deferred)
### Symptom
Delegated child sessions that fail on their first `promptAsync` call, for example when the provider rejects the request before any session history is persisted, may not advance to the configured fallback models. The session ends in early failure instead of retrying with the next fallback in the chain.
A delegated child session that fails on its very first `promptAsync` call (for example, the provider rejects the request before any session history is persisted) may not advance to the configured fallback models. The session ends in early failure instead of retrying with the next fallback in the chain.
This affects subagents launched via the delegate-task tool (background or sync) where the first provider call fails immediately and `session.messages` is still empty.
### History
PR #3825 (`fix/delegated-child-session-early-failure-fallback`, merged as `cd33f3a39` and later as `fac90d69f` on 2026-05-07) introduced a shared bootstrap context (`src/shared/delegated-child-session-bootstrap.ts`) to capture the retry payload before the first prompt dispatch so empty-history failures could still retry. After the merge landed on `dev`, the PR's own regression test (`delegated child-session empty-history fallback retries with captured bootstrap prompt` in `src/hooks/runtime-fallback/index.test.ts`) failed on a clean root `bun test --timeout 30000` run (`6828 pass / 1 fail`). PR #4044 reverted the merge on 2026-05-15 to keep `dev` green. The fix will be re-attempted in v4.2.1 after the regression test is stabilized against the post-#4032 schema and prompt-async-gate timing semantics.
PR #3825 (`tw-yshuang/fix/delegated-child-session-early-failure-fallback`, merged as commit `fac90d69f` on 2026-05-07) introduced a shared bootstrap context (`src/shared/delegated-child-session-bootstrap.ts`) to capture the retry payload before the first prompt dispatch, so empty-history failures could still retry with the fallback chain.
After the merge landed on `dev`, the PR's own regression test (`delegated child-session empty-history fallback retries with captured bootstrap prompt` in `src/hooks/runtime-fallback/index.test.ts`) failed on a clean root `bun test --timeout 30000` run (6828 pass / 1 fail). PR #4044 (`code-yeongyu/revert/3825-delegated-bootstrap`, merged on 2026-05-15) reverted the merge to keep `dev` green (6823 pass / 0 fail / 6 skip across 709 files).
The original failure-mode the PR targets remains in v4.2.0.
### Workaround
For delegated subagents, configure fallback models conservatively, or avoid delegating to providers that frequently fail on the first prompt call. The existing runtime-fallback persisted-history retry path still works after the subagent has produced any history.
- For delegated subagents, prefer providers that succeed reliably on the first call (rarely fail with auth/quota errors at request time).
- Configure fallback models conservatively in `categories[].fallback_models` and accept that the very first failure may not auto-retry.
- The existing runtime-fallback persisted-history retry path still works after the subagent produces any history.
### Tracking
### Planned Resolution
A follow-up issue will track the reland with stabilized regression coverage targeting v4.2.1.
Reland will target v4.2.1 once the regression test is stabilized against the post-#4032 schema-compatible synthetic tool result shape and the prompt-async-gate's dispatch timeout + post-dispatch hold semantics. A follow-up issue will be filed to track this work.