From d706587e1e64c7c6dde24a9d4ea96d3ec9fe656c Mon Sep 17 00:00:00 2001 From: YeonGyu-Kim Date: Sat, 16 May 2026 01:25:58 +0900 Subject: [PATCH] docs(known-issues): document delegate-task early-failure-fallback deferral PR #3825 introduced a delegated child-session bootstrap to capture first-prompt retry payloads before history is persisted, addressing the empty-history fallback gap. After merge the PR's own regression test failed on clean root bun test (6828 pass / 1 fail), so PR #4044 reverted it. Ship v4.2.0 with the bug documented and a workaround so users have an explicit story for the unfixed delegated child-session early-failure path. Reland will target v4.2.1. Closes BLOCKER-4 (Path B - reland deferred to v4.2.1) --- docs/reference/known-issues.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 docs/reference/known-issues.md diff --git a/docs/reference/known-issues.md b/docs/reference/known-issues.md new file mode 100644 index 000000000..50f89470a --- /dev/null +++ b/docs/reference/known-issues.md @@ -0,0 +1,19 @@ +# Known Issues + +## v4.2.0 - Delegate-task early-failure-fallback (BLOCKER-4, deferred from PR #3825) + +### 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. + +### 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. + +### 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. + +### Tracking + +A follow-up issue will track the reland with stabilized regression coverage targeting v4.2.1.