feat: jev-scored context compaction — shadow-first, opt-in, fail-open (reference-faithful port)

[Emasoft]

Update 2 — deferred follow-ups implemented

All four follow-ups deferred at review time are now implemented, in f8fd137 (feat(compaction,tui): implement deferred follow-ups):

• History compaction honors the same GateConfig protections as the tool-output path. Per-kind score floors resolve through compaction.GateFloorFor instead of a flat threshold; the max-elide-fraction tripwire runs per message (a message whose elided fraction would exceed the gate's fraction keeps everything); tripped messages are recorded in the shadow log when one is threaded, and the run summary reports them as CompactionReport.Tripwires. A nil gate keeps the legacy flat-threshold walk.
• Expand results are never re-compacted. protectedHistoryTool = ProtectedTool || expand, so a tool result that came back from an expand call is skipped by the history walk exactly like the tool-output path's protected kinds.
• The auto-compact trigger watches the session it actually compacts. It fires on the ROOT agent's usage (event.ID == m.Root.ID()), not the focused agent's — the compaction pass always rewrites the root session's history, so a focused subagent's usage can neither fire nor suppress the trigger.
• Fast/slow token counters share one walk. The first-paint estimator and the slow counter go through the same shared calculateHistoryTokens walk over the same message fields, so the streaming estimate is structurally identical to the count the compaction decisions use.

docs/quickstart.md gained one line stating it: history compaction (/jev-compact-context, the auto-trigger, and the 413 recovery pass) honors the same protections — the same keep threshold and protected-kind floors, with the max-elide-fraction tripwire applied per message (a tripped message keeps everything). Full go test ./... -race -count=1 and golangci-lint v2.13.2 are green on the branch head.

---

Update 2026-09-25

Seven new commits since the original description, at 2fdfbc1:

• 413 payload-too-large handling + compaction-threshold knob + one-shot recovery (aa8e6cb) — a 413 is now a typed, never-retried error whose text says what to do; a one-shot compaction recovery fires on 413 when compaction is enabled (re-armed by /new); the elision score threshold is settable in config.json as compaction-threshold (flag > config, 0.35 default).
• Audit fixes (70aafe2) — atomic cut-paragraph elision, prose-only assistant protection, activate_skill 1.0 floor, and a sharper admit question that distinguishes progress noise from non-re-derivable facts.
• Durable late-errors.log + pathutil.LateDataDir unification (70aafe2, ace1ed3) — critical errors land in a durable late-errors.log (lazy-open hardened in ace1ed3), and all mutable data paths route through one pathutil.LateDataDir.
• Expiry-aware toasts + pipeline warning sink (397a6a4, 8ac3c7c) — a new DiagnosticMsg renders mid-session warnings as proper warning toasts instead of raw stderr over the alt-screen, stale toast ticks no longer clear newer toasts, and compaction's one-time notices route through the TUI pipeline warning sink.
• Protected sibling pins cut-group keep (ace1ed3) — the keep decision is deterministic and reproducible by -replay-shadow.
• Per-model jev-autocompact-percent override (2fdfbc1) — with models[] key validation.
• Scoped config-reference (131f4b0) — docs/config-reference.md scoped to this branch's schema.

---

Reference-faithful port of jev-scored context compaction, split out of #133 so the TUI work and compaction can be evaluated separately (per review). This body addresses the review comments head-on.

Separation from the TUI work

The only TUI surface in this PR is one slash command — /jev-compact-context — plus its status text. Every other TUI change from #133 (status bar agent type, todos pane, info bar + timestamps, config error surfacing) lives in separate PRs and is independently evaluable.

No mandatory, no automatic compaction

• compaction-mode defaults to shadow: tool outputs are segmented and scored, decisions are appended to the shadow log — and nothing else. Zero behavior change; no tool result is ever rewritten or dropped in shadow mode.
• jev-autocompact defaults to false. Automatic compaction only ever runs if the user turns it on (and tunes jev-autocompact-percent, default 99).
• enabled mode is strictly opt-in and still fail-open: a scorer outage (or any error) keeps the original output, nothing is ever deleted — elided text stays retrievable byte-for-byte through the expand tool. User messages are never compacted.

Investigation before hype — the tests the review asked for

Preflight, live against the real decisions endpoint. late -check-compaction runs three real stages — questions (a minimal score batch parses, every id returns a numeric score), gate (a real ~2KB tool output actually relocates into pointers + store records), expand (the pointer reconstructs byte for byte) — and exits 0/1. Live run against https://openrouter.ai/api/alpha/decisions, model ~typesafe/jev-latest:

$ late -check-compaction
late compaction preflight
  [ok  ] backend     0.00ms  backend "openrouter" url https://openrouter.ai/api/alpha/decisions model "~typesafe/jev-latest" (api key: env)
  [ok  ] questions    394ms  3/3 questions answered with numeric scores (noul protocol)
  [ok  ] gate         247ms  gate relocated 1 run(s) — 4 of 4 segments, 700 tokens — into 1 store record(s)
  [ok  ] expand      0.01ms  1 pointer(s) expanded back byte for byte (2106 bytes)
result: PASS (4/4 stages ok)
cost: n/a (the decisions client does not track token usage)

Read-only verified: the preflight left config.json and the state dirs byte/mtime-identical.

Replay with false-negative rate. late -replay-shadow 0.10,0.35,0.50 replays the recorded shadow log (5,000+ real scored decisions) at any thresholds — kept/relocated/tokens-saved/still-missed plus the false-negative rate (a segment elided at its own recorded threshold was later expanded). Read-only:

threshold  kept  relocated  tokens saved  still missed
0.10       5991  4          12            0
0.35       5885  110        15529         0
0.50       5821  174        23391         0

false-negative rate: 0.0%

Offline scripted scorer for evaluation. config.json "compaction-backend": "offline" swaps the scorer for a deterministic local scripted scorer — the whole flow and the preflight run with no API key and no network (the model URL is a dead port to prove it):

$ late -check-compaction
late compaction preflight
  [ok  ] backend     0.00ms  backend "offline" url none model "scripted-scorer" (api key: none — deterministic offline scorer; no network)
  [ok  ] questions   0.03ms  3/3 questions answered with numeric scores (noul protocol)
  [ok  ] gate          44ms  gate relocated 1 run(s) — 4 of 4 segments, 700 tokens — into 1 store record(s)
  [ok  ] expand      0.01ms  1 pointer(s) expanded back byte for byte (2106 bytes)
result: PASS (4/4 stages ok)
cost: n/a (the decisions client does not track token usage)

Typed error taxonomy. Scorer failures surface as auth / validation / budget / unavailable — never retried blindly, no retry storms, and always fail-open.

Prompt-cache safety. History compaction works on an append-only frozen prefix with a persisted high-water mark: the anchor is never mutated across runs, and a walk that would violate the prefix fails loudly (ErrFrozenPrefix) and changes nothing.

Durable pointers. A persistent file-backed record store means [[elided …]] pointers survive restarts and are shared with subagents.

Gate tripwires. max-elide-fraction (never elide more than that fraction of a run in one pass) and protected segment kinds — stacktraces and diffs carry a score floor, so a scorer's bad day can't erase the two things you usually need verbatim.

Wire contract. This port follows github.com/Waxmell114514/jev-compaction exactly — including the fix that made live scoring work: an earlier draft sent a score-batch payload the real endpoint rejected (400, missing questions.<id>.instructions); the preflight caught it before any integration use, and the request shape now matches the reference wire contract precisely.

The scorer is swappable by design — backend registry today: typesafe / openrouter / gateway (--api / JEV_API), plus the offline scripted scorer for evaluation.

What's in the box

Segmentation · scoring · shadow log · [[elided …]] pointers + expand tool · /jev-compact-context · jev-autocompact (opt-in) · retrieve() read-side injection (config-gated, off by default) · docs.

Testing

$ go test ./... -race -count=1
ok  	late/cmd/late	2.331s
?  	late/cmd/mcp-run	[no test files]
ok  	late/internal/agent	1.452s
?  	late/internal/assets	[no test files]
ok  	late/internal/client	2.213s
ok  	late/internal/common	6.203s
ok  	late/internal/compaction	5.914s
ok  	late/internal/config	3.224s
ok  	late/internal/executor	13.011s
ok  	late/internal/git	4.802s
ok  	late/internal/mcp	4.430s
ok  	late/internal/orchestrator	4.586s
?  	late/internal/pathutil	[no test files]
ok  	late/internal/plugin	14.096s
ok  	late/internal/session	4.158s
ok  	late/internal/skill	2.641s
ok  	late/internal/tool	5.453s
ok  	late/internal/tool/ast	4.058s
ok  	late/internal/tui	10.594s

exit 0 — all 19 packages green (16 ok, 3 without test files).

• gofmt -l on the touched files: no output (clean)
• go vet ./cmd/late ./internal/compaction ./internal/config ./internal/executor ./internal/orchestrator ./internal/session ./internal/tool ./internal/tui: clean
• Preflight and replay diagnostics quoted above are live runs of this exact branch (build from bc44df9); the offline preflight ran in a scratch home with a dead model URL.

[mlhher]

Thank you for doing it this way! I will take a careful look at this and test it a bit.

[Emasoft]

Thank you for doing it this way! I will take a careful look at this and test it a bit.

wait to merge, there are some bugs i'm fixing right now.. i will update this and other PRs with the fixes..