[aw-failures] [fix] Documentation Unbloat: investigate & fix exit-code-7 agent crash (0 turns, dev-server lifecycle)

[github-actions]

Problem Statement

The Documentation Unbloat workflow (unbloat-docs) crashed with exit code 7 (Claude Code report_incomplete) after completing all pre-agent setup steps (Astro docs build, Playwright install, dev server start). The agent completed 0 turns, meaning it never processed any prompt.

Affected run: §25510316635 · 2026-05-07T17:01:42Z
Auto-alert issue: #30868
Parent investigation: (this issue's parent)

---

Root Cause

Exit code 7 from Claude Code = report_incomplete. With 0 turns, the agent exited immediately at initialization — before any prompt was sent. This points to one of:

1. Dev server not ready: The Astro dev server (localhost:4321) was started via nohup but may not have been reachable when the agent tried to connect (race condition in the docs-server-lifecycle shared step)
2. Pre-flight check false-negative: The activation check passed, but a deeper pre-flight assertion inside the shared docs-server-lifecycle.md component triggered report_incomplete
3. Firewall block on dev server health check: If the agent or shared step attempted to fetch (localhost/redacted) and got a connection error, this could trigger report_incomplete`

Confirmed from logs:

• Astro build completed ✅
• Dev server was live at cleanup (orphan processes: npm run dev, esbuild)
• Exit code 7 appeared ~2s after OTEL endgroup, before any agent turns

Side effect: All 5 subsequent runs of unbloat-docs are now permanently skipped because #30868 satisfies the skip-if-match: is:pr is:open is:draft label:doc-unbloat condition (the auto-created failure issue has the wrong label). The workflow won't run again until this is resolved.

---

Proposed Remediation

1. Add readiness check: In the docs-server-lifecycle.md shared component (or the activation step for unbloat-docs), add a `curl --retry 10 --retry-delay 3 (localhost/redacted) health check with a proper wait loop before launching the agent. This prevents the race condition where the dev server hasn't fully started.

2. Fix skip-if-match interference: Close issue [aw] Documentation Unbloat failed #30868 (or remove the doc-unbloat label from it) so that the skip-if-match condition no longer blocks future scheduled runs.

3. Clarify exit code 7 cause: Add logging before the claude CLI invocation that captures the result of the dev server readiness check and any pre-agent validation. This will make future failures easier to diagnose.

---

Success Criteria

• unbloat-docs completes successfully (conclusion: success, turns > 0) in the next scheduled run
• The dev server readiness check passes before the agent starts
• Issue [aw] Documentation Unbloat failed #30868 is closed, unblocking future scheduled runs
• No recurrence of exit code 7 / 0-turn failures in unbloat-docs over the next 7 days

---

References:

• §25510316635 (failed run)
• §25516906282 (this investigator run)

Generated by [aw] Failure Investigator (6h) · ● 740.3K · ◷

• expires on May 14, 2026, 7:32 PM UTC