Compaction Dual Paths & replaceGeneration

What problem it solves

Suppose you only have the proactive threshold path: measure before each request, pack when past 80%. Sounds enough — it isn’t. Token counts are estimates; estimates and the provider’s real count always diverge. A huge tool result can land suddenly — measurement hasn’t hit the threshold yet, but the request already exceeds the limit and the provider rejects it. With no recovery logic to take over, the turn dies with an error, and the user sees a baffling failure.

One miscount and you slam into the wall with no second line of defense. That’s the single-trigger problem.

What the idea is

DSH splits this into two independent triggers. Pack proactively when nearly full; recover passively after a wall hit. The two paths hang on different events, use different conditions, and have different failure semantics.

The pressure path hangs before each Step (one model request) starts. Measure total tokens; if past 0.8 of capacity, pack — leaving a 16% raw tail of recent dialogue. Failure semantics are loose: if packing errors mid-way, log a line and keep going; a failed early pack isn’t the end of the world.

The context-overflow path hangs after a request error, and only accepts the adapter-normalized code CONTEXT_WINDOW_EXCEEDED — other errors pass through. It ignores the threshold, zeros the reserve budget, and forces a real shrink. Failure semantics are strict: you must decide — retry, or keep and report the original error. Retry cap defaults to 1; each successful model reply resets the counter, so healthy sessions don’t get stuck.

Source:pressure listener at packages/compaction/compaction-basic/src/index.ts lines 147–165; overflow listener at lines 179–223; defaults 0.8 and 0.16 in the same package’s config.ts lines 20 and 23; retry cap default 1 at line 93 — all overridable per provider+model combo.

Why it lasts

Separating prevention from fallback is a reliability-engineering rule. Backup and restore are two systems; rate limiting and circuit breakers are two gates — same idea: the prevention path wants cheap, frequent, and failure-tolerant; the fallback path wants reliable, rare, and accountable on failure. Stuff both into one logic and they’ll compromise each other. So even if you rewrite the whole harness in another language, as long as models have context caps and tokens are estimated, you still need both triggers.

What problem it solves

After hitting the wall you pack once, then resend. The question: how do you know packing actually worked? Compaction is an open seam — third parties can plug in custom backends. Suppose a backend always reports success but never changes model-visible content: if you retry on return value alone, the request still overflows, errors again, compacts again, retries again — each lap burns API money for nothing until dawn.

What the idea is

DSH’s answer is a generation number. Background: surface is the live projection of model-visible events in the session log — the dialogue as the model sees it. replaceGeneration is a read-only counter on it for how many times that dialogue was replaced. Only one place in the whole codebase increments it: the moment old messages are truly replaced by a summary and truly flushed to disk. No API can shrink or reset it. So a forward generation number is mathematically equivalent to at least one real, persisted replacement.

Overflow recovery is three steps: snapshot the current value before packing; pack; compare the new value to the snapshot. Strictly greater → allow retry; otherwise pass through and report the original error as-is. What the plugin says doesn’t matter — whether the ledger number moved does.

There’s a reverse detail too. Even if packing throws mid-way, as long as free pruning already persisted and the generation advanced, that progress still qualifies a retry. Allow on evidence, refuse on evidence — same standard both ways.

Source:Snapshot and compare at packages/compaction/compaction-basic/src/index.ts line 191 and lines 218–222; retry on already-persisted progress after exception at lines 195–208; replaceGeneration defined in packages/core/session/src/surface.ts lines 136–142; the sole increment in the codebase at lines 361–371. The project’s Agent Note (.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md) explicitly rejected return-value-only checks, because a custom backend may report success without changing model-visible state.

Why it lasts

Proving state really changed with a monotonically increasing version number is a pattern databases have used for decades as optimistic locking; Git commit chains and distributed-system epochs are variants. The win: turn a trust problem into arithmetic — the executor can lie, the ledger can’t. As long as untrusted extension points exist, checking an immutable counter before retry is always the cheapest defense.

One comparison focus: does compaction failure loop and burn money? Claude Code counts failures and trips a circuit breaker at 3 — a loss limit calibrated from incident data: allow the problem a few times, then cap it. DSH doesn’t count; every retry must show generation advance — zero invalid retries allowed. That’s structural proof: invalid retries can’t leave the mechanism. Their 3 is fed by incidents; DSH’s 0 is deduced. Add orthogonal dual paths, and these two are DSH-unique among the three.