# Upgrade Guide — vNEXT

<!-- assembled-by: assemble-next-md -->
<!-- bump: patch -->

## What Changed

Context-wall recovery escalation — when a session is genuinely stuck at the
context wall ("Context limit reached · /compact or /clear to continue" /
"conversation too long"), recovery now presses `/compact` for it FIRST,
preserving the conversation, before falling back to the destructive fresh
respawn.

Grounded diagnosis of "still sometimes having trouble recovering from
compaction": the deployed code already suppresses false-death floods (a 100%
session still producing work is deferred, not falsely killed) and #935 fixed
recovery verification across UUID rotation. But the logs showed ZERO real
context-exhaustion recoveries ever fired, and the one recovery action that
exists is destructive — kill + respawn FRESH, losing the conversation.
**Nothing ever pressed `/compact`** — the exact button the wall asks for, and
the one that preserves the conversation.

`SessionRecovery.recoverFromContextExhaustion` now has a two-rung ladder:
rung 1 presses `/compact` (gated to a genuinely idle session — a working
session at 100% is left alone) and verifies the wall cleared; rung 2 (the
pre-existing kill + fresh respawn) is reached only if `/compact` is
unavailable, declined, or can't clear the wall. The new `attemptCompaction`
dep is optional — absent ⇒ unchanged behavior.

## What to Tell Your User

When a long session of mine hits the memory wall, I now try to compact it in
place first — squashing the conversation smaller so it can keep going WITHOUT
losing what we were doing. A from-scratch restart only happens if compaction
genuinely can't help. So "trouble recovering from compaction" should now far
more often end in "compacted and kept going" rather than "restarted fresh."

## Summary of New Capabilities

- `SessionRecovery.attemptCompaction` rung — non-destructive `/compact`
  escalation before the fresh respawn, gated to genuinely-idle stuck sessions,
  verified via `detectContextExhaustion`. Conversation preserved on success.
- server.ts wires it to `injectMessage('/compact')` + a bounded verify poll.
- CLAUDE.md "Context-wall recovery escalation" note so an agent can answer
  "did I lose the conversation when my session restarted?"

## Evidence

Grounded in the 2026-06-06 logs (zero real recoveries; all detections
deferred) + the user's screenshot ("Context limit reached", "100% context
used"). 8 new unit tests both sides of every boundary (compact-clears →
preserved + no kill/respawn; compact-fails → fresh respawn; working session →
deferred not compacted; no-dep back-compat; throw → non-fatal) + a server.ts
wiring dead-code guard + migrator add/patch/idempotent. tsc clean; preflight
PASS; recovery neighbor suites green.
