(fix) cap emergency nudge injections per user turn (closes #108)

[ranxianglei]

Closes #108.

Problem

When context pressure stays above the emergency threshold (engine default 0.85), every agent step re-injects a full emergency nudge, and each nudge is appended as a durable user/message event. If the pressure does not come down (the model no-ops, picks the wrong range, or the content is protected), the nudge's own tokens push usage even higher — a positive feedback loop that never stops. billion-context-pi hit the same failure mode (#223: retry prompt re-injected ~400×/hour, eventually removed) and fixed it with a per-user-turn cap (commit 414acd1).

Cause

src/nudge.ts dedups only normal nudges per user turn (lastNudgeTurn); the emergency path bypassed the dedup entirely (!emergency && …). No attempt counter, cap, or cooldown existed anywhere in the repo.

Fix

• EMERGENCY_NUDGE_MAX_PER_TURN = 3 (hardcoded — a safety mechanism, not a tuning knob): emergency nudges are capped at 3 injections per user turn, tracked in a per-session emergencyNudges map ({ turn, count }). The budget resets when the user turn advances (same semantics as the normal dedup).
• Normal nudges are unchanged: still at most one per user turn, and a normal nudge does NOT consume the emergency budget.
• When the kernel still wants an emergency nudge but the budget is spent, the engine logs a warn (emergency nudge suppressed — per-turn budget of 3 spent …) so operators can see WHY the model stops receiving nudges (issue [compression] emergency nudge 无上限逐 step 重注入，且缺少 compress attempt 断路器 #108 review).
• Docs updated in the same PR: README zh/en config table, config comments, AGENTS.md module map.

Scope note: this PR implements proposal #1 from the issue (the per-turn cap), which bounds the unbounded re-injection loop — the token-leak part. The compress-attempt circuit breaker (proposals #2/#3) is a follow-up; the kernel-side minPressureBenefit gate lands with the acp-kernel ≥0.0.54 bump planned in #116.

Review follow-up (2026-09-08)

Applied from the review on #108:

• Cap regression test rewritten with explicit per-call assertions: calls 1–3 inject, call 4 returns null, later calls stay null; the cap-hit hook fires for every suppressed call.
• New test: the cap resets on a new user turn.
• New test: same-turn normal + emergency mix — a normal nudge does not consume the emergency budget.
• logger.warn on cap hit (in the agent/pre-step handler, src/index.ts).
• Cap stays hardcoded at 3 (not exposed as a config knob).
• Branch rebased onto current main (v0.2.21 + e2e harness); no dist/ changes carried — per the current policy the dist-bot refreshes main after the merge.
• Title renamed to the (fix) … form required by the pr-title CI check (the old fix(nudge): … form fails scripts/check-pr-title.mjs).

Verification

• npm run typecheck — clean
• npm test — 216/216 pass (including the three [compression] emergency nudge 无上限逐 step 重注入，且缺少 compress attempt 断路器 #108 tests above)
• npm run build — clean (local check only; dist/ not committed)

[ranxianglei]

我来协助看一下这个问题,请分析并回复处理结果。