feat(gateway): persist durable prompt deltas

[BYK]

Problem

Knowledge/LTM can change materially while a session is already relying on a warm prompt-cache prefix. Rewriting system[2] to surface those changes destroys cache stability, but transient one-turn delta messages are also incorrect: the agent is stateless, so once those bytes disappear they are as if they never existed, and their disappearance changes the cached prefix.

Closes #740. This implements the knowledge-delta channel proposed in #740, but with a durable/persisted model instead of a volatile one-turn delta (a volatile delta would itself bust the cache when it disappears).

Ground rules

• Cache stability is byte-identical prefix stability.
• Once Lore injects a delta into the conversation, it must remain at the same position with exactly the same bytes until an intentional cache reset.
• Deltas should only carry material updates/removals and stay capacity-limited.
• Exact selector/content must be persisted so process restarts reconstruct the same upstream request.

Design

Durable prompt deltas:

• Adds session_prompt_deltas with the minimal persisted shape:
  • session_id
  • seq
  • project_id
  • selector (JSON)
  • content (exact JSON message payload)
• Replays prompt deltas on every turn by applying selectors to the transformed upstream message array.
• For material LTM additions/updates after system[2] is pinned, keeps the old pinned system[2] bytes and appends a durable user-message prompt delta near the conversation tail.
• For deletion-only / removal-only LTM changes (including the normal non-emergency refresh path), keeps the old pinned system[2] bytes and appends a durable Superseded Long-term Knowledge delta listing removed short IDs.
• Bounds the delta via a token budget; entries that overflow are surfaced truncated under Additional Changed Knowledge (truncated) rather than silently dropped.
• Dedup-merged curator creates are surfaced as updates so warm sessions get the new bytes.
• Persists old ltm_cache_text/ltm_pin_text bytes while advancing ltm_pin_keys, so restart does not rewrite system[2].
• Persists and deterministically restores header→session mappings (reloaded on any known-header miss) so restart replays deltas against the same internal session.
• moveSessions() carries session_prompt_deltas to the target project.
• Removes the old transient ltm_delta_json / pending-queue path from the gateway.

Design questions from #740

1. Placement: synthetic trailing user message after the last cache breakpoint (selector {target:"messages", insertAt}).
2. Reconciliation: delta is explicitly labeled a Lore knowledge update; removals listed under Superseded Long-term Knowledge so the model ignores stale pinned IDs.
3. ID plumbing: entries referenced by short IDs ([019eb...]).
4. Dedup: only material changes are emitted; pinned block keeps its exact bytes and is not duplicated.
5. Bounding: capped by token budget; overflow surfaced truncated instead of dropped.

Verification

• Full test suite: 122 files, 2999 passed | 6 skipped.
• Core typecheck passes.
• Gateway typecheck has no errors from touched files; the known pre-existing script/build-binary-sea.ts ignoreNodeOptions type error remains outside this PR.
• Biome check on touched files passes.
• e2e cache-stability asserts mid-session create/update/remove changes only the conversation tail, never system[1]/system[2] bytes, and that durable deltas replay across a simulated gateway restart.
• Two independent subagent reviews were run; all blocker/should-fix findings were addressed.

[github-actions]

Codecov Results 📊

✅ Patch coverage is 86.88%. Project has 5707 uncovered lines.
✅ Project coverage is 64.43%. Comparing base (base) to head (head).

Files with missing lines (6)

File	Patch %	Lines
packages/gateway/src/pipeline.ts	84.72%	⚠️ 22 Missing and 23 partials
packages/core/src/ltm.ts	70.59%	⚠️ 5 Missing and 3 partials
packages/core/src/data.ts	83.33%	⚠️ 1 Missing and 1 partials
packages/core/src/curator.ts	100.00%	⚠️ 1 partials
packages/core/src/prompt.ts	100.00%	⚠️ 1 partials
packages/gateway/src/idle.ts	0.00%	⚠️ 1 Missing

Coverage diff

@@            Coverage Diff             @@
##          main       #PR       +/-##
==========================================
+ Coverage    64.28%    64.43%    +0.15%
==========================================
  Files          103       103         —
  Lines        15857     16045      +188
  Branches     10967     11093      +126
==========================================
+ Hits         10193     10338      +145
- Misses        5664      5707       +43
- Partials      1247      1254        +7

---

Generated by Codecov Action

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-06-13 00:40 UTC