docs: clarify timeout 44% buffer is intentional (#26) - #56
Merged
Conversation
Closes #26. The prior comment advertised "+20% buffer" but the math actually applies 1.20 twice — once in the MAX_TURNS calculation and once in TIMEOUT_SECS = MAX_TURNS * 30 * 1.20, compounding to 1.44 × the raw turns-times-30s baseline. The compounding is INTENTIONAL: the two buffers protect against different failure modes. - The turn-side buffer protects against Claude using more turns than estimated — "exceeded turn limit" in the step error. - The wall-clock-side buffer protects against infrastructure flakes (backend latency, network stalls) that don't consume turns but still eat wall time. Before the AAR 2026-04-17, a single session saw three consecutive infra-flake timeouts on kebab-tax#1162 — extra wall-clock slack reduces that rate. Closes the docs-vs-code mismatch flagged in #26 by documenting the compound factor and the rationale. No code change — the intentional extra slack stays. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Local reviewer flagged that the preceding comment overstated the role of the floor and ceiling clamps. With MAX_TURNS bounded to [15, 40] by the estimator (PR #52) the computed timeout is always 9-24 minutes, so neither the 4 min floor nor the 30 min ceiling ever activates in normal operation. They are defensive against future parameter drift, not active bounds today. Closes #54. No code change. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Comment-only change documenting the compounded 1.44x timeout buffer and its rationale. No logic, security, or parsing-contract changes. VERDICT: PASS |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Two-commit doc-only PR. Closes #26.
5f6eb0e— documents that the timeout compounds two 20% buffers (1.20 × 1.20 = 1.44) and explains the rationale: turn-side buffer protects against turn exhaustion, wall-clock-side buffer protects against infra flakes.1468302— marks the 4m floor / 30m ceiling as defensive-only at currentMAX_TURNS ∈ [15, 40]bounds (computed timeout is always 9–24 min in that range). Closes Documented 30-min ceiling is unreachable at current bounds #54.Not changed
TIMEOUT_SECS = MAX_TURNS * 30 * 120 / 100— the actual math is unchanged. The 44% compound buffer is retained because it's genuinely useful against the infra-flake failure mode documented in the 2026-04-17 AAR.Re: #55 (filed by local reviewer on the second commit)
#55observes my "below 8" threshold for the 4-min floor is imprecise — the actual formula gives 4 min exactly atMAX_TURNS = 6, so the floor activates only atMAX_TURNS ≤ 5. Reviewer is right factually.Not fixing in this PR for session-scope reasons: the active range
[15, 40]is far from either clamp, so the exact-threshold-for-future-drift is cosmetic — a reader who cares about the exact clamp can compute it from the formula above. Will close #55 as accepted imprecision post-merge.Test plan
Closes
Closes #26. Closes #54.
🤖 Generated with Claude Code