Scaling codeguard timeout dynamically based on file count and complexity (lines changed, AST depth) will eliminate SessionEnd flush failures while keeping average timeout below 5 seconds for typical sessions

Hypothesis

Scaling codeguard timeout dynamically based on file count and complexity (lines changed, AST depth) will eliminate SessionEnd flush failures while keeping average timeout below 5 seconds for typical sessions

Changelog

Date	Summary
2026-04-06	Audited: chain fixed (standalone, chain_prev null), domain tag ops, last_audited stamped
2026-04-04	Initial creation

---

Hypothesis

The SessionEnd timeout pitfall documented that Claude Code kills hooks after 1.5 seconds by default. The log buffer requeue and session header write mode pitfalls show that flush operations can lose data when timeouts are too aggressive. The current fix is a static CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=10000, but this is a blunt instrument: most sessions need <2 seconds, while complex sessions with many changed files need 8-10 seconds.

The hypothesis is that an adaptive timeout (base 2s + 0.5s per changed file + 1s per AI review call) will eliminate flush failures while keeping median timeout under 5 seconds.

Method

1. Instrumentation: add timing logs to codeguard’s processing loop. For each PostToolUse and SessionEnd invocation, record: file count, total lines changed, AI review calls made, actual processing time.
2. Data collection: collect 50+ sessions of timing data under the current static 10s timeout.
3. Regression: fit a linear model: timeout = a + b * file_count + c * ai_calls + d * total_lines. Determine coefficients from historical data.
4. Adaptive formula: implement the regression formula with a 2x safety margin (double the predicted time) as the dynamic timeout. Minimum 2s, maximum 15s.
5. Buffer requeue fix: regardless of timeout, implement the requeue pattern from the buffer requeue pitfall: on flush failure, prepend failed entries back to the buffer for the next cycle. This provides a safety net even if the timeout is too short.
6. Session header fix: implement the write-then-append mode from the session header pitfall: writeFileSync for first flush (creates header), appendFileSync for subsequent flushes.
7. Measurement: compare flush success rate (100% target) and average timeout (target <5s) against the static 10s baseline.

Results

Pending. Will measure:

• Flush success rate: before (static 10s) vs after (adaptive)
• Average timeout duration: static vs adaptive
• Data loss incidents: before vs after
• Regression model R-squared (how well file count predicts processing time)

Findings

Pending.

Next Steps

If the adaptive formula works, integrate it into the peon-dispatch hook system so all hook timeouts scale with workload. This could replace the static environment variable approach entirely.