/gsd:manager's background execute-phase Task fails with
"Stream idle timeout - partial response received" on multi-plan phases
(Claude Code + Opus 4.7 at ~200K+ cache_read) because the long subagent
never emits tokens fast enough between large tool_results — the SSE layer
times out mid-assistant-turn and the harness retries hit the same TTFT
wall after prompt cache TTL expires.
Root cause: no orchestrator-level activity at wave/plan boundaries.
Fix (maintainer-approved A+B):
- A (wave boundary): execute-phase.md now emits a `[checkpoint]`
heartbeat before each wave spawns and after each wave completes.
- B (plan boundary): also emit `[checkpoint]` before each Task()
dispatch and after each executor returns (complete/failed/checkpoint).
Heartbeats are literal assistant-text lines (no tool call) with a
monotonic `{P}/{Q} plans done` counter so partial-transcript recovery
tools can grep progress even when a run dies mid-phase.
Docs: COMMANDS.md /gsd-manager section documents the marker format.
Tests: tests/bug-2410-stream-checkpoint-heartbeats.test.cjs (12 cases)
asserts the heartbeats exist at every boundary and in the right workflow
step. Full suite: 5422 node:test cases pass. Pre-existing vitest
failures on main are unrelated to this change.
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -336,6 +336,26 @@ CROSS_AI_TIMEOUT=$(gsd-sdk query config-get workflow.cross_ai_timeout 2>/dev/nul
|
||||
<step name="execute_waves">
|
||||
Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`, sequential if `false`.
|
||||
|
||||
**Stream-idle-timeout prevention — checkpoint heartbeats (#2410):**
|
||||
|
||||
Multi-plan phases can accumulate enough subagent context that the Claude API
|
||||
SSE layer terminates with `Stream idle timeout - partial response received`
|
||||
between a large tool_result and the next assistant turn (seen on Claude Code
|
||||
+ Opus 4.7 at ~200K+ cache_read). To keep the stream warm, emit short
|
||||
assistant-text heartbeats — **no tool call, just a literal line** — at every
|
||||
wave and plan boundary. Each heartbeat MUST start with `[checkpoint]` so
|
||||
tooling and `/gsd:manager`'s background-completion handler can grep partial
|
||||
transcripts. `{P}/{Q}` is the phase-wide completed/total plans counter and
|
||||
increases monotonically across waves. `{status}` is `complete` (success),
|
||||
`failed` (executor error), or `checkpoint` (human-gate returned).
|
||||
|
||||
```
|
||||
[checkpoint] phase {PHASE_NUMBER} wave {N}/{M} starting, {wave_plan_count} plan(s), {P}/{Q} plans done
|
||||
[checkpoint] phase {PHASE_NUMBER} wave {N}/{M} plan {plan_id} starting ({P}/{Q} plans done)
|
||||
[checkpoint] phase {PHASE_NUMBER} wave {N}/{M} plan {plan_id} {status} ({P}/{Q} plans done)
|
||||
[checkpoint] phase {PHASE_NUMBER} wave {N}/{M} complete, {P}/{Q} plans done ({wave_success}/{wave_plan_count} ok)
|
||||
```
|
||||
|
||||
**For each wave:**
|
||||
|
||||
1. **Intra-wave files_modified overlap check (BEFORE spawning):**
|
||||
@@ -374,7 +394,15 @@ Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZAT
|
||||
|
||||
2. **Describe what's being built (BEFORE spawning):**
|
||||
|
||||
Read each plan's `<objective>`. Extract what's being built and why.
|
||||
**First, emit the wave-start checkpoint heartbeat as a literal assistant-text
|
||||
line — no tool call (#2410). Do NOT skip this even for single-plan waves; it
|
||||
is required before any further reasoning or spawning:**
|
||||
|
||||
```
|
||||
[checkpoint] phase {PHASE_NUMBER} wave {N}/{M} starting, {wave_plan_count} plan(s), {P}/{Q} plans done
|
||||
```
|
||||
|
||||
Then read each plan's `<objective>`. Extract what's being built and why.
|
||||
|
||||
```
|
||||
---
|
||||
@@ -392,6 +420,13 @@ Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZAT
|
||||
|
||||
3. **Spawn executor agents:**
|
||||
|
||||
**Emit a plan-start heartbeat (literal line, no tool call) immediately before
|
||||
each `Task()` dispatch (#2410):**
|
||||
|
||||
```
|
||||
[checkpoint] phase {PHASE_NUMBER} wave {N}/{M} plan {plan_id} starting ({P}/{Q} plans done)
|
||||
```
|
||||
|
||||
Pass paths only — executors read files themselves with their fresh context window.
|
||||
For 200k models, this keeps orchestrator context lean (~10-15%).
|
||||
For 1M+ models (Opus 4.6, Sonnet 4.6), richer context can be passed directly.
|
||||
@@ -552,6 +587,16 @@ Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZAT
|
||||
|
||||
4. **Wait for all agents in wave to complete.**
|
||||
|
||||
**Plan-complete heartbeat (#2410):** as each executor returns (or is verified
|
||||
via spot-check below), emit one line — `complete` advances `{P}`, `failed`
|
||||
and `checkpoint` do not but still warm the stream:
|
||||
|
||||
```
|
||||
[checkpoint] phase {PHASE_NUMBER} wave {N}/{M} plan {plan_id} complete ({P}/{Q} plans done)
|
||||
[checkpoint] phase {PHASE_NUMBER} wave {N}/{M} plan {plan_id} failed ({P}/{Q} plans done)
|
||||
[checkpoint] phase {PHASE_NUMBER} wave {N}/{M} plan {plan_id} checkpoint ({P}/{Q} plans done)
|
||||
```
|
||||
|
||||
**Completion signal fallback (Copilot and runtimes where Task() may not return):**
|
||||
|
||||
If a spawned agent does not return a completion signal but appears to have finished
|
||||
@@ -830,6 +875,15 @@ Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZAT
|
||||
|
||||
6. **Report completion — spot-check claims first:**
|
||||
|
||||
**Wave-close heartbeat (#2410):** after spot-checks finish (pass or fail),
|
||||
before the `## Wave {N} Complete` summary, emit as a literal line:
|
||||
|
||||
```
|
||||
[checkpoint] phase {PHASE_NUMBER} wave {N}/{M} complete, {P}/{Q} plans done ({wave_success}/{wave_plan_count} ok)
|
||||
```
|
||||
|
||||
|
||||
|
||||
For each SUMMARY.md:
|
||||
- Verify first 2 files from `key-files.created` exist on disk
|
||||
- Check `git log --oneline --all --grep="{phase}-{plan}"` returns ≥1 commit
|
||||
|
||||
Reference in New Issue
Block a user