pi-context-guard-jev 0.1.0 → 0.2.0

package/docs/TESTING.md

@@ -13,15 +13,17 @@ These need Node ≥ 22.18, which runs the `.ts` files directly. There is no netw
 
 | File | Covers |
 |---|---|
+| `checkpoint.test.ts` | Mid-run eligibility and age, the memo and candidate rules, later calls, notes, superseded detection (edits, re-reads, reruns), cache anchors (read point only from logged entries of the same model within the TTL, invalidated by later edits and compaction, parallel-call batches never split, early return without pending edits), refresh on read-through (same model, cacheRead clearly past the entry, unchanged prefix; trusted after 5 minutes once refreshed), the run baseline, the Anthropic rewrite estimate (from the trusted read point, else from the question), pending edits, the memo from records, the break-even rule, context size with summaries |
+| `items.test.ts` | Small outputs (size window, candidate rules, age, memo, stub length, superseded), exchange spans (custom messages, completed exchanges only, the current run and the recent exchanges never touched, already omitted, memo; images, foreign edits and foreign omissions skipped, our own markers allowed; system, `!` and custom messages; a compaction that cut an exchange; minimum size), stubs and edits, the small and exchange requests in both phases, batching, the shared limiter, `judgeItems` (parallel limit, failures keep, time budget), `processItems` (stubs, omissions, records with kinds, one `concurrency` across all kinds) |
 | `run.test.ts` | Run span (including image-only prompts), question/answer/notes, candidate rules (errors, images, excluded tools, short, already-distilled and other-extension-edited results), steering messages; history (last N exchanges, first request, compaction/branch summaries, image-only and steering prompts, clipping, `historyExchanges` 0) |
 | `chunk.test.ts` | grep detection, grouping by file, context lines and `--`, `-digits-` file names, split/merge rules, plain-text windows, segment limits |
-| `decide.test.ts` | Request shape, with and without `earlier_conversation` (state order, omitted parts, history wording vs. the unchanged single-run wording); the decision order (error, missing answers, `keep_whole`, strong/weak `whole`, chunks, `none`); `citedFiles` |
+| `decide.test.ts` | Checkpoint request shape and wording; run-end request shape, with and without `earlier_conversation` (state order, omitted parts, history wording vs. the unchanged single-run wording); the decision order (error, missing answers, `keep_whole`, strong/weak `whole`, chunks, `none`); `citedFiles` |
 | `distill.test.ts` | Skips, edits, `removed`, `not-worth`, failures, time budget (including a classifier that never answers and late answers), parent abort, concurrency limit, multi-segment outputs, oversize segments never sent, `keepCitedFiles`, usage sums |
 | `render.test.ts` | Labels, verbatim chunks with omission lines, `read` offsets, file lists, full removal |
-| `cache-pin.test.ts` | API-key and OAuth payloads, trailing system messages, TTL selection and `ttl-conflict`, string content, tool-result-only messages, over-budget restore |
-| `stats.test.ts` | Savings from the projection, run records, status texts and colours, cost format |
+| `cache-pin.test.ts` | Question pin: API-key and OAuth payloads, trailing system messages, TTL selection and `ttl-conflict`, string content, tool-result-only messages, over-budget restore. Anchors: question > read > write priority, read anchor inside a batch of tool_result blocks, breakpoint budget (identity and tools breakpoints dropped, then write, then read; the question survives a foreign breakpoint), not found / last message / already marked, normalized tool ids, TTL order, `markedToolResults` |
+| `stats.test.ts` | Savings from the projection, run records (checkpoints counted), status texts and colours, cost format |
 | `recall.test.ts` | Original output, pattern (length cap, 4,000-char match window, catastrophic-regex timeout), offset/limit, line and byte caps, oversized lines |
-| `config.test.ts` | Defaults, validation and ranges (incl. `historyExchanges` 0–10 integer), `provider/id` parsing, load/save round trip |
+| `config.test.ts` | Defaults, validation and ranges (incl. `historyExchanges` 0–10 integer and the `midRun*` settings), `provider/id` parsing, load/save round trip |
 | `extension.test.ts` | The real entry point (see below) |
 
 `extension.test.ts` loads `src/index.ts` through **Pi's own extension loader** (`loadExtensions` from the
@@ -29,7 +31,26 @@ These need Node ≥ 22.18, which runs the `.ts` files directly. There is no netw
 `PI_CODING_AGENT_DIR` and `PI_CONTEXT_GUARD_CONFIG` to a temporary directory, so `/guard on|off` never touches the real
 `~/.pi/agent/context-guard.json`. It checks that the handlers, tool and command are registered, that drafts
 are appended after other extensions' drafts, that unfinished runs and a missing model are ignored, that the
-pin applies only to `anthropic-messages`, that `recall` works, and that `/guard off|on` persists.
+pin applies only to `anthropic-messages`, that `recall` works, and that `/guard off|on` persists. For
+`turn_end` it checks that the final turn is skipped, that a batch below `midRunBatchChars` and a checkpoint
+that would not break even are skipped, that a due checkpoint appends edits and a `mid-run` record after other
+drafts (never `continue`), that nothing is judged twice once the record is committed, that drafts a later
+handler dropped (or Pi rejected) are judged again, that an unanswered output (error) is asked again, that the
+memo follows `/tree`, and that run end judges outputs kept mid-run again. On a `pi-claude-auth`-shaped
+payload (system prompt moved into the first user message) it checks the question pin on every request; on
+the first request after edits a write anchor, and a read point only at an entry this process sent earlier
+(also on a warming replay); a read point after run-end edits; and no read point for another model, after
+the TTL (mocked clock), after a reload, for an anchor dropped for the budget, or for history made with
+pinning off. Through `message_end` it checks that a response that read through a logged entry keeps it
+usable past 5 minutes, and that a short read or another model's response does not. For whole items it
+checks that run end omits an unrelated old exchange (stub on the prompt, `null` for the rest) and stubs a
+small output, that the next run judges the next eligible exchange, that `recall` on the stub returns the
+whole exchange, that `pruneExchanges: false` and `smallResultMinChars: 0` turn them off, and that the
+break-even rule drops exchanges from a checkpoint batch that would not pay off with them. The run-end
+exchange gate: a small omission is deferred and the accumulated batch is omitted at a later run end; a big
+early exchange in a short session is deferred, and omitted with `exchangeBreakEven: false`; on OpenAI Codex
+an exchange rides along when the pass edits something else and is deferred when it does not. The fake
+session uses Pi's projection shape (an omitted entry stays with no messages).
 
 Test through Pi's loader (or `pi -e`), not a plain Node import of the extension. Plain Node imports of
 `@earendil-works/pi-coding-agent` can fail with `ERR_PACKAGE_PATH_NOT_EXPORTED`, even though Pi loads the
@@ -41,7 +62,7 @@ This uses a real Pi, a real main model and real Jev requests. **It costs money o
 main-model requests per turn, plus a few Jev requests (under $0.001 per distilled run).
 
 ```bash
-node test/e2e/run-e2e.mjs --model <provider/id> [--ext <path>]... [--scenario badge|long|history] \
+node test/e2e/run-e2e.mjs --model <provider/id> [--ext <path>]... [--scenario badge|sequential|history|long|topics] \
   [--config '<JSON>'] [--no-guard] [--turns N] [--thinking level]
 ```
 
@@ -49,7 +70,7 @@ node test/e2e/run-e2e.mjs --model <provider/id> [--ext <path>]... [--scenario ba
 |---|---|---|
 | `--model` | (required) | Main model, e.g. `openai-codex/gpt-6-luna` or `anthropic/claude-sonnet-5-5` |
 | `--ext` | none | Extra extension to load; can be repeated (e.g. an auth extension) |
-| `--scenario` | `badge` | `badge`: 3 turns about `StatusBadge` usages. `long`: 2 turns with 10+ sequential tool calls, for the cache pin. `history`: 3 turns for the earlier-conversation feature (below). |
+| `--scenario` | `badge` | `badge`: 3 turns about `StatusBadge` usages. `sequential`: 2 turns with 10+ sequential tool calls, for the question pin. `history`: 3 turns for the earlier-conversation feature. `long`: one autonomous "fix all failing tests" run, for mid-run checkpoints. `topics`: 5 prompts on different topics, the last a follow-up on the first, for old exchanges (both below; use `--turns 5`). |
 | `--config` | `{}` | context-guard settings for this run, e.g. `'{"pinAnthropicCache":false}'` |
 | `--no-guard` | off | Control run without context-guard |
 | `--turns` | `3` | Turns to run (capped by the scenario) |
@@ -80,7 +101,10 @@ How it works:
 | turn 2 first request reads cache | `cacheRead` > 0 on the first request after the edit |
 | turn 3 quotes the removed line exactly | The model quoted line 3 of `src/api/jobStatus.ts` from the "first search" |
 | turn 3 used recall (line was distilled away) | Only when that line is missing from turn 3's payload: the model must have called `recall` |
-| long: turn 1 produced context edits / 10+ tool calls / 10+ model requests | The long scenario really was long and sequential |
+| sequential: turn 1 produced context edits / 10+ tool calls / 10+ model requests | The sequential scenario really was long and sequential |
+| long: the suite is green afterwards | `npm test` passes in the fixture after the run |
+| long: at least one mid-run checkpoint (forced) | Only with `midRunBreakEven: false` in `--config`: a `mid-run` record was written (a default run may rightly make none) |
+| long: request after the checkpoint at request N reads the cached prefix | Anthropic: the first request after each checkpoint reads at least what the run's first request read and wrote (system prompt and question) |
 | history: turn 2 produced context edits | The broad search in turn 2 was distilled |
 | history: turn 3 names exactly the clients that retry on 429 | The answer names the 9 clients whose fixture file has `=== 429`; a client named only to say it does *not* retry is allowed |
 | anthropic requests stay within 4 breakpoints | For `anthropic/…` models: the pin never exceeds the limit |
@@ -93,6 +117,47 @@ summary has a `history` block: `keptApiRetryLines` / `kept429Lines` (src/api ret
 distilled text), the turn-2 Jev results and ms, turn 3's tool calls and whether it used `recall`, and the
 clients turn 3 named. Results are in [JEV.md](JEV.md#earlier-conversation-historyexchanges).
 
+**`long` scenario.** `test/e2e/make-long-fixture.mjs` generates a small Node project (`ledgerly`: money
+in integer cents, business-day calendars, CSV, pricing, a ledger report; 182 tests). Ten bugs sit in
+different modules, in up to three layers: an import-time `ReferenceError` hides a whole test file, and two
+tests fail first because of one bug and then, once it is fixed, because of another. A full `npm test` prints
+12k characters when green and 25–30k with the failures, so every rerun is a large, quickly superseded tool
+output. The prompt asks the agent to fix one bug at a time and run the plain suite after every fix, without
+asking anything. (`--fixed` writes the bug-free version, `--bugs 1,4,…` a subset.) GPT-6 Luna needs 26–37
+requests; Claude Sonnet 5.5 needs 8–14, because it batches several fixes per command and pipes test output
+into `grep`/`head`. Load `--ext test/e2e/plain-test-runs.ts` for Claude to strip a pipe after `npm test`
+(it logs each rewrite to stderr), so its suite runs return full logs like GPT's.
+
+The summary gets a `long` block: per-request contexts (input + cacheRead + cacheWrite) and a sparkline,
+totals of input/cacheRead/cacheWrite/output and the main-model cost Pi reports, every `context-guard`
+record with its phase, saved characters, Jev ms and cost, and the request before and after it (context,
+cacheRead, cacheWrite), whether the suite is green, `recall` calls, and repeated non-suite tool calls (lost
+outputs searched again). Results are in the README ("Long autonomous runs") and in
+[CACHE.md](CACHE.md#mid-run-checkpoints).
+
+**`topics` scenario.** Five prompts in the generated StatusBadge repo: which API clients retry on 503; a
+README paragraph for `StatusBar`; a count of HTTP 500 log lines; where `StatusBadge` is used; and "back to
+the API clients that retry on 503: which of them also retry on 502?". The summary gets a `topics` block:
+the context of each prompt's first request and its usage, the exchange results (phase, prompt, outcome,
+P), the small-output results, the last prompt's tool calls and whether it used `recall`, and whether its
+answer names exactly the clients whose file has both `=== 503` and `=== 502` (a crude check: it fails on
+answers that also list clients to say they do not qualify). Results are in the README (example D) and in
+[CACHE.md](CACHE.md#old-exchanges).
+
+**API-shape probe.** `CG_OMIT_AT_TURN=2 node test/e2e/run-e2e.mjs --model … --no-guard --ext
+test/e2e/omit-probe.ts` omits the session's first exchange after turn 2 the way the guard does, so turn 3
+sends a stub user message right before the next user message, without the omitted assistant and
+tool-result messages. Both GPT-6 Luna and Claude Sonnet 5.5 (`pi-claude-auth`) accepted it and answered.
+
+**Whole-item probe.** `node test/e2e/probe-items.mjs [--reps 2] [--sessions <topics no-guard run dir>]…`
+sends the hand-written exchanges and small outputs in `test/e2e/probe-data/` (and the `topics` exchanges)
+to Jev and prints P per item and the accuracy per threshold (results in [JEV.md](JEV.md#old-exchanges)).
+
+**Anthropic TTL experiment.** `node test/e2e/ttl-probe.mjs [--arms refresh,control,ttl1h,idle,idle1h]`
+runs `test/e2e/ttl-probe.ts` with Claude: does a cache entry stay alive while later requests read a longer
+prefix, and does it expire when nothing reads it for 6 minutes? About 9 minutes and roughly $0.9 at list price for all five arms.
+Results: [CACHE.md](CACHE.md#do-cache-entries-on-the-read-path-stay-alive-measured).
+
 With the guard on, the badge scenario has 9 checks, plus 1 for Anthropic models. Most guard checks are
 skipped with `--no-guard`.
 
@@ -118,24 +183,31 @@ the runner disables installed extensions:
 
 ```bash
 node test/e2e/run-e2e.mjs --model anthropic/claude-sonnet-5-5 --ext ~/.pi/agent/npm/node_modules/pi-claude-auth
-node test/e2e/run-e2e.mjs --model anthropic/claude-sonnet-5-5 --ext ~/.pi/agent/npm/node_modules/pi-claude-auth --scenario long
-node test/e2e/run-e2e.mjs --model anthropic/claude-sonnet-5-5 --ext ~/.pi/agent/npm/node_modules/pi-claude-auth --scenario long --config '{"pinAnthropicCache":false}'
+node test/e2e/run-e2e.mjs --model anthropic/claude-sonnet-5-5 --ext ~/.pi/agent/npm/node_modules/pi-claude-auth --scenario sequential
+node test/e2e/run-e2e.mjs --model anthropic/claude-sonnet-5-5 --ext ~/.pi/agent/npm/node_modules/pi-claude-auth --scenario sequential --config '{"pinAnthropicCache":false}'
 node test/e2e/run-e2e.mjs --model openai-codex/gpt-6-luna
 node test/e2e/run-e2e.mjs --model openai-codex/gpt-6-luna --no-guard
 node test/e2e/run-e2e.mjs --model openai-codex/gpt-6-luna --scenario history
 node test/e2e/run-e2e.mjs --model openai-codex/gpt-6-luna --scenario history --config '{"historyExchanges":0}'
+# mid-run checkpoints (up to 4 in parallel)
+node test/e2e/run-e2e.mjs --model openai-codex/gpt-6-luna --scenario long --no-guard
+node test/e2e/run-e2e.mjs --model openai-codex/gpt-6-luna --scenario long --config '{"midRun":false}'
+node test/e2e/run-e2e.mjs --model openai-codex/gpt-6-luna --scenario long
+node test/e2e/run-e2e.mjs --model anthropic/claude-sonnet-5-5 --ext ~/.pi/agent/npm/node_modules/pi-claude-auth --ext test/e2e/plain-test-runs.ts --scenario long
 ```
 
-### Results so far (Pi 1.0.3)
+### Results (Pi 1.0.3)
 
 | Run | Result |
 |---|---|
 | GPT-6 Luna, badge | 36,113 → 1,501 chars, 2 Jev requests, 550 ms, $0.00083; turn 3 used `recall` with a regex; 9/9 checks pass |
 | Claude Sonnet 5.5, badge | 36,113 → 3,066 chars, 2 Jev requests, 1.18 s, $0.00084; turn 2 cacheRead 5,777 / cacheWrite 2,036; turn 3 used `recall`; 10/10 checks pass |
-| Claude Sonnet 5.5, long, with / without pin | first request after the run: cacheRead 5,810 / 1,693, cacheWrite 8,913 / 13,068 |
+| Claude Sonnet 5.5, sequential, with / without pin | first request after the run: cacheRead 5,810 / 1,693, cacheWrite 8,913 / 13,068 |
 | GPT-6 Luna, badge, with / without guard | turn 2 cacheRead 2,560 / 13,824 |
-| GPT-6 Luna, badge, after the history feature | 36,113 → ~2.3k chars; 9/9 checks pass (an earlier run in parallel with 4 others had one OpenAI cache miss on turn 2: 8/9) |
+| GPT-6 Luna, badge, with history (default) | 36,113 → ~2.3k chars; 9/9 checks pass (a run in parallel with 4 others had one OpenAI cache miss on turn 2: 8/9) |
 | GPT-6 Luna / Claude Sonnet 5.5, history on / off | See [JEV.md](JEV.md#earlier-conversation-historyexchanges): 2 rounds × 4 runs |
+| GPT-6 Luna / Claude Sonnet 5.5, long (mid-run checkpoints) | See the README, "Long autonomous runs"; all suites green, no `recall` |
+| GPT-6 Luna / Claude Sonnet 5.5, topics, guard on / off | See the README, example D |
 
 See [CACHE.md](CACHE.md) for what the cache numbers mean.
 
@@ -159,7 +231,7 @@ node test/e2e/examples.mjs --jobs 2
 
 Each run gets its own workspace, session id and `PI_CONTEXT_GUARD_CONFIG` file (defaults). The Pi package is
 public (npm); nothing private is sent to OpenRouter. Example B also records the test log's size
-(`testLogChars`, which must be ≥ 8,000 to be a fair example; it was 14.4k).
+(`testLogChars`, which must be ≥ 8,000 to be a fair example; it was 14.4–15.8k).
 
 Output: `test/e2e/out/examples-<stamp>/` with `results.md` (the table), `results.json`, and one directory per
 run (`A-claude-on`, …) holding `summary.json` (per turn: tool calls, tool-result sizes, edits with kept/total
@@ -171,17 +243,15 @@ model saw.
 Pi from list prices (most of it Claude in example A; GPT runs used a subscription). About 5 minutes with 4
 parallel jobs.
 
-**Findings of the first full run** (details in the README):
-
-- Next-request context, on / off: A Claude 15.5k / 28.2k tokens, A GPT 11.5k / 34.3k, C GPT 9.2k / 35.3k;
-  all follow-ups correct, none needed `recall`.
-- The first request after an edit cost more with the guard on (cache rewrite): A Claude $0.033 / $0.016.
-- B was not distilled at all: the failing test command is an error result, which context-guard then never
-  edited. Fixed by `distillErrors` (default on); a rerun distilled the log 15.8k → 8.6k chars, keeping the
-  3 failures with their assertion messages, and turn 2 still fixed the bug.
-- In C, `read` outputs carry Pi's two-line "[Showing lines …]" note, so omission ranges at the end of a piece
-  named two line numbers past the file lines (e.g. "lines 466–502" of a 1–500 read). Fixed: ranges are now
-  clamped to the file lines and a removed note gets no omission line.
+**Findings** (details in the README):
+
+- Next-request context, on / off: A Claude 15.5k / 28.2k tokens, A GPT 11.5k / 34.3k, C GPT 9.2k / 35.3k,
+  B GPT 5.7k / 7.5k; all follow-ups correct, none needed `recall`.
+- The first request after an edit costs more with the guard on (cache rewrite): A Claude $0.033 / $0.016.
+- B: the failing test log (an error result, distilled because `distillErrors` is on) went 15.8k → 8.6k
+  chars, keeping the 3 failures with their assertion messages.
+- C: `read` outputs end with Pi's "[Showing lines …]" note; omission ranges are clamped to the file lines
+  and a removed note gets no omission line.
 
 ## Manual TUI check (tmux)
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-context-guard-jev",
-  "version": "0.1.0",
-  "description": "Keep big tool outputs from bloating your Pi context: after each run, the Jev classifier keeps only the lines your work still needs, verbatim and recallable, with savings in the status bar. Claude + OpenAI, cache-aware.",
+  "version": "0.2.0",
+  "description": "Keep your Pi context lean: the Jev classifier trims big tool outputs to the lines your work still needs, drops stale small outputs and unrelated old exchanges, at run end and during long autonomous runs. Verbatim, recallable, cache-aware, savings in the status bar.",
   "type": "module",
   "license": "MIT",
   "author": "alandarev",

package/src/cache-pin.ts

@@ -120,3 +120,173 @@ export function pinQuestionBreakpoint(payload: unknown): PinResult {
 	}
 	return "pinned";
 }
+
+// ---------------------------------------------------------------------------------------------
+// Read-point anchors after context edits (docs/CACHE.md → Mid-run checkpoints)
+// ---------------------------------------------------------------------------------------------
+
+/** Pi's Anthropic provider rewrites tool call ids like this (pi-ai anthropic-messages.js). */
+export const normalizeToolUseId = (id: string): string => id.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 64);
+
+export interface GuardBreakpointOptions {
+	/** Tool call ids that get a read anchor, highest priority first (after the question). */
+	anchors: readonly string[];
+	/** Tool call ids that get a breakpoint only to write a cache entry (lowest priority). */
+	writeAnchors?: readonly string[];
+	/** Pin the previous user question. It has the highest priority: it is the floor every edit falls back to. */
+	pinQuestion: boolean;
+}
+
+export interface GuardBreakpointResult {
+	/** Anchors placed (ids from `anchors` and `writeAnchors`). */
+	anchored: string[];
+	/** Anchors that could not be placed, with the reason. */
+	skipped: { id: string; reason: "not-found" | "in-last-message" | "already" | "over-budget" | "ttl-conflict" }[];
+	question: PinResult | "off";
+	/** Breakpoints Pi placed that were removed to make room. */
+	removed: string[];
+}
+
+function findToolResult(messages: Json[], id: string, before: number): { index: number; block: Json } | undefined {
+	const ids = new Set([id, normalizeToolUseId(id)]);
+	for (let i = 0; i < messages.length; i++) {
+		const content = messages[i]?.content;
+		if (!Array.isArray(content)) continue;
+		const block = content.find((b: Json) => b?.type === "tool_result" && ids.has(b.tool_use_id));
+		if (block) return i < before ? { index: i, block } : { index: -1, block };
+	}
+	return undefined;
+}
+
+/** Index of `target` among the cacheable blocks of the payload (prefix order). */
+function positionOf(payload: Json, target: Json): number {
+	let n = 0;
+	let found = -1;
+	const visit = (value: unknown) => {
+		if (found >= 0) return;
+		if (Array.isArray(value)) value.forEach(visit);
+		else if (value && typeof value === "object") {
+			if (value === target) {
+				found = n;
+				return;
+			}
+			n++;
+			for (const [key, child] of Object.entries(value)) if (key !== "cache_control") visit(child);
+		}
+	};
+	visit([payload.tools, payload.system, payload.messages]);
+	return found;
+}
+
+/** All blocks carrying cache_control, in prefix order (tools → system → messages). */
+function breakpointBlocks(payload: Json): Json[] {
+	const out: Json[] = [];
+	const visit = (value: unknown) => {
+		if (Array.isArray(value)) value.forEach(visit);
+		else if (value && typeof value === "object") {
+			if ((value as Json).cache_control) out.push(value as Json);
+			for (const [key, child] of Object.entries(value)) if (key !== "cache_control") visit(child);
+		}
+	};
+	visit([payload.tools, payload.system, payload.messages]);
+	return out;
+}
+
+/**
+ * Place the previous-question pin, read anchors and write anchors on an Anthropic Messages payload,
+ * in place, in that priority. Respects the 4-breakpoint limit (dropping, in this order, the redundant
+ * OAuth identity breakpoint, the tools breakpoint when the system prompt has one, then the
+ * lowest-priority guard marks) and the TTL order (anchors use the rolling breakpoint's TTL; a mark that
+ * cannot keep longer TTLs first is skipped).
+ */
+export function placeGuardBreakpoints(payload: unknown, options: GuardBreakpointOptions): GuardBreakpointResult {
+	const result: GuardBreakpointResult = { anchored: [], skipped: [], question: options.pinQuestion ? "no-question" : "off", removed: [] };
+	if (!payload || typeof payload !== "object") return { ...result, question: options.pinQuestion ? "not-anthropic" : "off" };
+	const body = payload as Json;
+	const messages = body.messages;
+	if (!Array.isArray(messages)) return result;
+	const rolling = lastCacheControl(messages);
+	if (!rolling) return { ...result, question: options.pinQuestion ? "no-cache" : "off" };
+	let last = messages.length - 1;
+	while (last >= 0 && messages[last]?.role === "system") last--;
+
+	// 1. Targets, highest priority first: question, read anchors, write anchors.
+	const marks: { id: string; block: Json; kind: "question" | "anchor" | "write" }[] = [];
+	if (options.pinQuestion) {
+		let target = -1;
+		for (let i = last - 1; i >= 0; i--) {
+			if (messages[i]?.role === "user" && hasText(messages[i])) {
+				target = i;
+				break;
+			}
+		}
+		if (target >= 0) {
+			const question = messages[target];
+			if (typeof question.content === "string") question.content = [{ type: "text", text: question.content }];
+			const block = question.content.findLast((b: Json) => b?.type === "text" && typeof b.text === "string" && b.text.trim());
+			if (block?.cache_control) result.question = "already";
+			else if (block) marks.push({ id: "question", block, kind: "question" });
+		}
+	}
+	const addAnchor = (id: string, kind: "anchor" | "write") => {
+		const found = findToolResult(messages, id, last);
+		if (!found) result.skipped.push({ id, reason: "not-found" });
+		else if (found.index < 0) result.skipped.push({ id, reason: "in-last-message" });
+		else if (found.block.cache_control || marks.some((m) => m.block === found.block)) result.skipped.push({ id, reason: "already" });
+		else marks.push({ id, block: found.block, kind });
+	};
+	for (const id of options.anchors) addAnchor(id, "anchor");
+	for (const id of options.writeAnchors ?? []) addAnchor(id, "write");
+
+	// 2. Apply with TTL order: the rolling TTL if it fits, else the other one, else skip.
+	const applied: typeof marks = [];
+	const { ttl: _rollingTtl, ...rollingRest } = rolling;
+	for (const mark of marks) {
+		const position = positionOf(body, mark.block);
+		const others = breakpointBlocks(body).filter((b) => b !== mark.block);
+		const before = others.filter((b) => positionOf(body, b) < position);
+		const after = others.filter((b) => positionOf(body, b) > position);
+		const fits = (ttl: number) => before.every((b) => ttlMinutes(b.cache_control) >= ttl) && after.every((b) => ttlMinutes(b.cache_control) <= ttl);
+		const ttl = [ttlMinutes(rolling), ttlMinutes(rolling) === 60 ? 5 : 60].find(fits);
+		if (ttl === undefined) {
+			if (mark.kind === "question") result.question = "ttl-conflict";
+			else result.skipped.push({ id: mark.id, reason: "ttl-conflict" });
+			continue;
+		}
+		mark.block.cache_control = ttl === 60 ? { ...rollingRest, ttl: "1h" } : { ...rollingRest };
+		applied.push(mark);
+	}
+
+	// 3. Budget.
+	const system = body.system;
+	if (countBreakpoints(body) > ANTHROPIC_MAX_BREAKPOINTS && Array.isArray(system) && system.length > 1 && system[0]?.cache_control && system.slice(1).some((b: Json) => b?.cache_control)) {
+		delete system[0].cache_control;
+		result.removed.push("system[0]");
+	}
+	const tools = Array.isArray(body.tools) ? body.tools : [];
+	if (countBreakpoints(body) > ANTHROPIC_MAX_BREAKPOINTS && Array.isArray(system) && system.some((b: Json) => b?.cache_control)) {
+		const toolBlock = tools.findLast((b: Json) => b?.cache_control);
+		if (toolBlock) {
+			delete toolBlock.cache_control;
+			result.removed.push("tools");
+		}
+	}
+	while (countBreakpoints(body) > ANTHROPIC_MAX_BREAKPOINTS && applied.length > 0) {
+		const dropped = applied.pop() as (typeof applied)[number];
+		delete dropped.block.cache_control;
+		if (dropped.kind === "question") result.question = "over-budget";
+		else result.skipped.push({ id: dropped.id, reason: "over-budget" });
+	}
+	for (const mark of applied) {
+		if (mark.kind === "question") result.question = "pinned";
+		else result.anchored.push(mark.id);
+	}
+	return result;
+}
+
+/** Tool-use ids of the tool_result blocks that carry a breakpoint in the final payload. */
+export function markedToolResults(payload: unknown): string[] {
+	const messages = (payload as Json | undefined)?.messages;
+	if (!Array.isArray(messages)) return [];
+	return messages.flatMap((m: Json) => (Array.isArray(m?.content) ? m.content.filter((b: Json) => b?.type === "tool_result" && b.cache_control).map((b: Json) => String(b.tool_use_id)) : []));
+}