On high-traffic conversations, evaluateLeafTrigger() fires every turn
because raw tokens outside the fresh tail constantly exceed
leafChunkTokens. Each leaf pass creates a depth-0 summary that
resequences all ordinals, invalidating the Anthropic prompt cache
prefix. Cache hit dropped from 90%+ to 22% on large conversations.

Add two skip guards to evaluateLeafTrigger(), evaluated only when the
basic threshold IS exceeded:

1. Cache-aware skip: if estimated reduction is <5% of total assembled
   tokens, the cache invalidation cost exceeds the compression gain.

2. Budget headroom skip: if assembled tokens are below 80% of
   contextThreshold × tokenBudget, there is no budget pressure.

Both are configurable: leafSkipReductionThreshold (default 0.05) and
leafBudgetHeadroomFactor (default 0.8).

Fixes Martian-Engineering#282

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…er cache skip

Adversarial review found that the cache-aware skip could permanently
suppress leaf compaction in large contexts (e.g., 700K of 750K ceiling)
because the 5% relative threshold scales with total assembled tokens.

Fix: evaluate budget headroom FIRST. When over the headroom ceiling
(budget pressure), bypass the cache-aware skip entirely — compaction
fires regardless of cache impact. The cache-aware skip only applies
when there is genuine headroom (no budget pressure).

Also clamp leafBudgetHeadroomFactor to max 1.0 to prevent
misconfiguration from silently disabling compaction.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Addresses Copilot review round 2:

1. estimatedReduction was using rawTokensOutsideTail (all raw tokens)
   but a leaf pass only compacts one chunk capped at leafChunkTokens.
   Now uses Math.min(rawTokensOutsideTail, threshold) so the estimate
   reflects actual per-pass reduction.

2. Added leafSkipReductionThreshold and leafBudgetHeadroomFactor to
   openclaw.plugin.json configSchema (which has additionalProperties:
   false) so users can set them via plugin config, not just env vars.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Adds 16 new unit tests covering all paths through the cache-aware
and budget-headroom skip logic, plus 5 config resolution tests:

Skip logic tests (lcm-integration.test.ts):
- Basic threshold: below/above leafChunkTokens
- Budget headroom: skip when under ceiling, compact when over
- Budget headroom: bypassed when tokenBudget undefined
- Cache-aware: skip when reduction tiny relative to total context
- Cache-aware: compact when reduction large enough
- Budget pressure overrides cache skip (anti-starvation)
- Edge cases: empty conversation, negative reduction
- Config escape hatches: threshold=0 and factor=0 disable skips
- Factor clamped to 1.0 (misconfiguration protection)
- Orchestrator vs sub-agent: different budgets, different decisions
- Per-pass chunk size estimate uses min(raw, threshold)

Config tests (config.test.ts):
- Default values: 0.05 and 0.8
- Plugin config override
- Env var override
- Schema entries in manifest

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…st fixes

Addresses 5 Copilot review comments:

1. leafBudgetHeadroomFactor=0 now correctly disables the headroom
   check (headroomEnabled=false) instead of creating false budget
   pressure that bypassed the cache-aware skip.

2. Config values clamped to [0,1] in resolveLcmConfig via clamp01().

3. Removed wasteful "x".repeat(summaryTokens*4) in test — mock store
   uses tokenCount directly, not content length.

4. Fixed leafChunkTokens=0 test — resolveLeafChunkTokens() normalizes
   non-positive to default. Use default threshold instead.

5. Updated factor=0 test comment to match corrected semantics.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…nfo logging

Three hardening improvements from adversarial review:

1. Token accuracy: evaluateLeafTrigger now accepts optional
   liveContextTokens param and uses max(stored, live) for headroom
   decisions. Stored token counts can lag after rapid ingestion;
   the live estimate from afterTurn provides a more accurate floor.

2. Structured telemetry: LeafTriggerResult now includes a `context`
   field with all decision inputs (totalAssembledTokens, budgetCeiling,
   budgetPressure, estimatedReduction, reductionThreshold, headroomFactor).
   Enables machine-parseable diagnostics and config tuning.

3. Observability: Skip and fire decisions logged at info level (not
   debug). Compaction fires include assembled/pressure context.
   Volume is at most 1 log per turn — negligible.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

The comment described when the cache-aware skip is applied but
did not precisely reflect the budgetPressure gate semantics after
the headroom refactor. Updated to accurately describe: budget
pressure is only true when headroom is enabled AND ceiling is
breached; otherwise cache-aware skip can fire.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Adds documentation for the cache-aware compaction feature across all
doc layers:

New: docs/compaction-tuning.md — standalone deep-dive covering:
  - TLDR quick-setup with copy-paste configs per model tier
  - Compaction model selection guide (why fast models matter)
  - Full lifecycle diagrams (Mermaid)
  - Cache-aware decision flowchart
  - Economics tables (cache miss penalty, break-even formula)
  - Gateway stall timing per model
  - Debugging guide for common issues

Updated: docs/architecture.md
  - Cache-aware skip guards section with Mermaid diagram
  - Budget pressure priority explanation
  - Prompt cache impact description

Updated: docs/configuration.md
  - leafSkipReductionThreshold and leafBudgetHeadroomFactor reference
  - Compaction model selection table
  - Per-tier preset summary with link to tuning guide

Updated: skills/lossless-claw/references/config.md
  - Added both new config fields to skill reference

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

The code uses totalAssembledTokens < budgetCeiling for headroom
(strict less-than), so budget pressure fires at >= budgetCeiling.
Docs said 'exceed' which implies strict greater-than. Fixed to
'reach or exceed' across all 5 files.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Thread observed token counts through leaf and threshold compaction workers so stale persisted counts do not suppress needed compaction after the outer trigger has already detected budget pressure. Add regression coverage for both the engine plumbing and the compaction engine stale-count path, correct the Sonnet 4.6 tuning guide to reflect its 1M context tier, and add the missing patch changeset.

Regeneration-Prompt: |
  Address review findings on PR 289 in the PR worktree without changing unrelated behavior. The bug is that afterTurn/evaluation can use a live current token estimate, but the actual compactLeaf and compactFullSweep worker paths re-check leaf trigger conditions using only stored DB token counts, which can lag ingestion and incorrectly skip compaction under real budget pressure. Thread the observed token count through those worker calls and add tests that prove stale stored counts no longer suppress leaf or threshold sweeps. Also fix the compaction tuning docs so Sonnet 4.6 is described consistently with the documented 1M context window, and add a patch changeset because the PR changes user-facing runtime behavior and docs.