fix(compression): add hard message-count safety valve to TUI/CLI preflight path

[yingliang-zhang]

Summary

The gateway has had a hard message-count safety valve since #4750 (gateway/run.py), but the TUI/CLI preflight path (agent/turn_context.py) lacks an equivalent backstop.

When should_defer_preflight_to_real_usage() (#50762) keeps deferring compression because the last successful API call's prompt_tokens were below threshold, a TUI session can grow unbounded until the provider starts disconnecting — at which point no usage data is returned to update the compressor, creating an unrecoverable death spiral.

The death spiral

1. Session grows past the compression threshold
2. should_defer_preflight_to_real_usage() defers compression (last successful API call was below threshold, growth within 5% tolerance)
3. Session continues growing — API still succeeds (model context > threshold)
4. last_real_prompt_tokens exceeds threshold → should_defer returns False
5. should_compress() should fire, but anti-thrashing (_ineffective_compression_count >= 2) can block it if prior compressions were ineffective
6. Provider starts timing out / disconnecting → no usage data returned
7. No usage → last_prompt_tokens stays stale → compression never triggers
8. Every subsequent message repeats the cycle → session is unrecoverable

What this PR does

Layer	Change
ContextCompressor.__init__	New hygiene_hard_message_limit param (default 0 = disabled)
agent_init.py	Reads compression.hygiene_hard_message_limit from config, passes to constructor
turn_context.py preflight	When message count ≥ hard limit, bypasses deferral, cooldown, and anti-thrashing
should_compress()	New force param — bypasses anti-thrashing when hard limit triggered

How it works

The existing compression.hygiene_hard_message_limit config key (default 5000 in DEFAULT_CONFIG) was already used by the gateway hygiene layer. This PR extends it to the TUI/CLI preflight path — no new config key needed.

When the message count exceeds the hard limit:

• should_defer_preflight_to_real_usage() is bypassed (no more deferring)
• get_active_compression_failure_cooldown() is bypassed (no cooldown blocking)
• should_compress(force=True) bypasses anti-thrashing (no more ineffective-compression blocking)
• Compression fires immediately

Relationship to prior work

• Bug: Context compression fails to trigger on API disconnect, causing death spiral in gateway sessions #2153 / fix: prevent compression death spiral from API disconnects (#2153) #4750: Added the hard message-count safety valve to gateway/run.py (Layer 3). This PR extends the same concept to the TUI/CLI path.
• Bug: Context compression triggers repeatedly after fresh compress — last_prompt_tokens=-1 not updated until next API call #36718 / fix(agent): defer preflight compaction until real usage after a compaction (#23767, #36718) #50762: Added should_defer_preflight_to_real_usage() to prevent double-compression after a fresh compress. This PR adds an escape hatch when the session has grown too large.
• Preflight compression guard bypasses token threshold, causing silent context overflow on sessions with few messages but large total tokens #27405: Added the char-based preflight gate for few-huge-message sessions. This PR is orthogonal — it adds a count-based gate that fires regardless of token estimates.

Files changed

• agent/context_compressor.py — +15/-2 (hygiene_hard_message_limit field + force param)
• agent/turn_context.py — +38/-11 (hard-limit check in preflight)
• agent/agent_init.py — +9/-0 (config wiring)
• tests/agent/test_context_compressor.py — +45/-0 (5 new tests)

Test plan

	Result
TestShouldCompress (+2 force tests)	6 passed
TestHygieneHardMessageLimit (+3 new)	3 passed
TestPreflightDeferral (existing)	5 passed
TestUpdateFromResponse (existing)	2 passed
py_compile all 3 source files	OK
Full file test_context_compressor.py	130 passed

No existing tests modified — all additions are new test methods and a new test class.

[yingliang-zhang]

Rebased onto current main@444b5e96f and resolved the compression API conflicts while preserving the hard message-count preflight safety valve. New head: 0e36e0c43.

Post-rebase verification:

• full tests/agent/test_context_compressor.py + tests/agent/test_turn_context.py: 174 passed
• py_compile, Ruff, and git diff --check: PASS

The rebased delta remains one focused commit and does not duplicate the newer configurable tail-floor or durable rotation-lock work.

[teknium1]

Thanks for carrying the gateway safety-valve concept into the interactive path. The current main premise is real: agent/turn_context.py:368-434 has no count-based escape hatch, while the existing config is documented gateway-only at website/docs/user-guide/configuration.md:758.

Problems

• The new hard-limit branch still calls should_compress() (agent/turn_context.py:486 in the PR diff). Current agent/context_compressor.py:1288-1315 rejects both active summary-failure cooldowns and two ineffective compactions; the PR's added tests deliberately preserve those blocks. That does not recover the cooldown/anti-thrashing cases described in the PR.
• agent/conversation_loop.py:1012-1018 independently mirrors the same defer/cooldown/should_compress() chain for in-turn pre-API pressure, but the PR does not add the count valve there.
• The configuration docs still state this setting is gateway-only (website/docs/user-guide/configuration.md:758).

Suggested changes

• Specify and test the intended bounded recovery semantics for a count breach, including the cooldown and anti-thrashing cases.
• Cover the in-turn pre-API guard or explain its exclusion, and update the configuration docs.

Automated hermes-sweeper review.

[yingliang-zhang]

Follow-up CI compatibility fix pushed in 56f8f941e: ordinary token-pressure calls no longer pass a new force=False keyword to legacy/strict _compress_context implementations; only hard-limit breaches attempt force=True, with an exact unexpected-keyword fallback. Verified with the full affected matrix: tests/run_agent/test_run_agent_codex_responses.py, tests/agent/test_turn_context.py, and tests/run_agent/test_413_compression.py — 136 passed, 0 failed; Ruff and git diff --check passed.

[yingliang-zhang]

Rebased onto current main (d3630f8532, post-#102117 refactor) — ported with two adaptation decisions:

1. The preflight decision chain now lives in agent/turn_context_compaction.py (_preflight_compression), so the valve gates there; the compressor adds a force flag threaded through should_compress → _automatic_compression_blocked that bypasses the anti-thrash breaker — orthogonal to the existing ignore_cooldown (summary-LLM cooldown), which main added since the original PR.
2. Config key renamed to compression.preflight_hard_message_limit (default 0): main's gateway layer already owns compression.hygiene_hard_message_limit (default 5000) for its pre-agent hygiene pass — reusing that key would have silently enabled the agent-side valve at 5000 for every existing config, changing default TUI/CLI behavior. Distinct key = agent-side valve stays opt-in as the original PR intended.

5 tests ported (force semantics + ctor wiring); 157/157 in test_context_compressor locally.