feat(coding-agent): add staged context compaction

[minpeter]

Summary

• keep the existing one-shot compaction path, then fall back to staged recovery only when the summary request or resulting checkpoint would overflow
• add a pure planner that selects the largest token-budgeted contiguous prefix of complete oldest turns while retaining the newest turn and preserving tool-call/result grouping
• append every accepted stage as a normal durable compaction checkpoint, carrying the previous accepted summary into the next stage
• expose additive optional stage metadata on existing compaction events so current consumers remain compatible
• replace speculative summarizer retries that silently removed old messages without moving the checkpoint boundary with a structured staged-recovery handoff

Why

The current overflow retry makes a single summary request over one large old prefix. If that summary request itself exceeds the model context, or if the resulting checkpoint still exceeds the active-context budget, no durable progress can be made. The previous speculative fallback also removed messages from summary input while retaining the original checkpoint boundary, which could claim history was summarized when it was not.

Safety and bounds

• maximum 8 staged summary calls after the existing one-shot attempt
• maximum 5 minutes for the staged sequence
• each accepted cursor must advance; non-progress fails explicitly
• an oldest complete turn that cannot fit one stage fails explicitly without slicing the turn
• intermediate checkpoints are append-only and restart-safe
• later-stage failure or abort preserves the last accepted checkpoint
• the original provider prompt is retried only after a final stage is below budget
• the last allowed stage is not appended if it still leaves context oversized

Validation

• npm run build
• npm run check
• compaction regression selection: 34 files, 278 tests passed
• focused staged/planner/speculative/rejection tests: 4 files, 35 tests passed
• repository QA RPC self-test: 4/4 passed, real auth unchanged
• repository QA mock-provider agent loop: passed with local evidence
• git diff --check

Known baseline issue

packages/coding-agent/test/suite/agent-session-compaction.test.ts has 34 passing tests and one existing characterization failure: does not consume the overflow compact-and-retry attempt when compaction fails before retrying. The same failure was reproduced from clean upstream commit 38bd3a3cf8a47c1201969117b1a82a5af7daac9c; that harness uses no configured auth and does not persist the synthetic messages into SessionManager, so no overflow compaction start is emitted. This PR does not change that unrelated test.

---

Summary by cubic

Adds staged context compaction to packages/coding-agent, keeping the existing one-shot path and falling back to a bounded, durable staged sequence when a compaction or its summary would overflow. This makes overflow recovery reliable, restart-safe, and prevents silent history drops.

• New Features

  • Core staged recovery in AgentSession: up to 8 stages or 5 minutes, each accepted stage writes a normal checkpoint; only the final stage triggers willRetry.
  • Planner planStagedCompactionChunk() selects the largest token-budgeted contiguous prefix of the oldest complete turns, retains the newest turn, and keeps tool-call/result pairs together.
  • Detects summary-input overflow with CompactionSummaryOverflowError and switches to staged recovery.
  • Rejections are explicit for non-advancing cursors, single oversized oldest turns, and summaries that leave no budget for the next checkpoint.
  • Optional stage metadata added to compaction events and extension hooks (index, maxStages, final).

• Bug Fixes

  • Replaces speculative “prune and retry” summary behavior that could drop old messages without moving the checkpoint; now surfaces would-overflow and hands off to staged recovery.
  • Compaction cap accounting in the builtin extension applies only at stage 1; later accepted stages complete the admitted compaction.

^{Written for commit 626210c. Summary will update on new commits.}