auto-model-router 0.2.8 → 0.2.10

package/.omp-plugin/marketplace.json

@@ -7,14 +7,14 @@
   },
   "metadata": {
     "description": "auto-model-router: a local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter",
-    "version": "0.2.8",
+    "version": "0.2.10",
     "pluginRoot": "."
   },
   "plugins": [
     {
       "name": "auto-model-router",
       "description": "Local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter. Runs in-process, routes per turn by price and task complexity, with budget caps, mid-stream escalation, and cache-aware hysteresis.",
-      "version": "0.2.8",
+      "version": "0.2.10",
       "author": {
         "name": "drewappling",
         "email": "drewappling@gmail.com"

package/README.md

@@ -620,6 +620,13 @@ shows which model produced which turn. Those messages feed back into the next
 `context_assemble`, so the model you switch *to* inherits what the model you
 switched *from* actually did.
 
+A recorded turn is the whole **user-visible** turn, not one record per upstream
+request. An agentic turn is a loop of dispatches — each tool round-trip finishes
+with `tool_calls` and emits almost no text, and the last user message does not
+move while the loop runs. So the router buffers the assistant's narration across
+the loop and writes it once, together with the closing synthesis, when the
+assistant actually yields back to the user.
+
 Write-backs are queued, bounded, and never awaited: agentdox is an enrichment,
 not a dependency. If it is unreachable the turn routes and dispatches normally,
 and a pinned block keeps being served.

package/docs/AGENTDOX-BRIDGE.md

@@ -1,7 +1,7 @@
 # agentdox bridge — handoff
 
-**Status:** implemented, typechecks clean, 409 tests pass, injection verified end-to-end
-through omp. **One open bug** in the write-back path (§5). Pick up there.
+**Status:** implemented, typechecks clean, 438 tests pass, injection verified end-to-end
+through omp. The write-back bug in §5 is **fixed**; `context.recordTurns` is safe to enable.
 
 Design rationale (why it is built this way):
 `E:/projects/agentdox/docs/architecture/router-context-bridge.md`.
@@ -86,44 +86,56 @@ Two more traps hit during this work:
 - Long-running interactive omp sessions hold their own embedded routers from whenever they
   started. Check `Get-Process omp` before trusting a result.
 
-## 5. OPEN BUG — assistant text is under-captured on the omp path
-
-**Verified working:** injection reaches the model through omp. The dispatched system message
-was confirmed to contain the block (`containsBlock=true`), and on a direct
-`/v1/chat/completions` dispatch the model answered *from* the injected memory, verbatim:
-
-> "The router pins one agentdox context block per conversation, refreshing it only on model
-> switches, retries, or TTL."
-
-**Broken:** through omp, the recorded assistant turn is near-empty — `assistantChars=4`
-(literally `" high"`) while omp displayed several paragraphs. The session and the model
-attribution (`refs: ["model:…", "tier:…"]`) are written correctly; only the assistant
-*content* is wrong.
-
-`assistantText` is accumulated in `src/server/turn.ts` from `ev.type === "text"` deltas
-inside the chunk loop. Leads, roughly in order of suspicion:
-
-1. **omp issues more than one upstream request per visible turn** (e.g. a title/summary call
-   on the `smol` role, which also resolves to `auto` → the router). The 4-char record may be
-   an auxiliary request, with the real answer on a different conversation key. Check by
-   logging `conversationKey` alongside the record line and counting turns per omp invocation.
-2. **Content arrives as `reasoning` deltas, not `text`**, for reasoning-capable models — the
-   accumulator deliberately ignores `reasoning`. If so, decide whether the transcript should
-   capture reasoning (probably not) or whether `text` is arriving under a chunk shape the
-   interpreter is not mapping to a `text` event.
-3. **Escalation resets the buffer.** `assistantText` is declared per attempt; if a turn
-   commits on a later attempt the earlier text is correctly dropped, but verify the committed
-   attempt is the one being recorded.
-
-Start by adding `conversationKey` and `attempt` to the `agentdox record turn` debug line and
-running one omp invocation — that distinguishes lead 1 from the others immediately.
+## 5. FIXED — one record per dispatch, not per turn
+
+**Symptom:** through omp the recorded assistant turn was near-empty —
+`assistantChars=4` (literally `" high"`) while omp displayed several paragraphs. Session and
+model attribution (`refs: ["model:…", "tier:…"]`) were always correct; only the assistant
+*content* was wrong.
+
+**Root cause — none of the three leads originally listed here.** The text was not
+under-captured; the *wrong requests* were being recorded. A user-visible turn is not one
+upstream request, it is a whole tool loop of them. Live ledger proof, one conversation key,
+`wasted=0` and `attempt=0` on every row:
+
+| dispatch | `finish_reason` | `toolLoopDepth` | completion tokens |
+| --- | --- | --- | --- |
+| 1 | `tool_calls` | 0 | 339 |
+| 2–6 | `tool_calls` | 2, 4, 6, 8, 10 | 91, 68, 198, 78, 44 |
+| 7 | **`stop`** | 12 | **596** |
+| 8 | `tool_calls` | 0 *(next turn)* | 167 |
+
+Each tool round-trip is its own dispatch, finishing with `tool_calls` and emitting almost no
+`text` — the payload is tool calls. `" high"` was a stray word of preamble, a *complete*
+record of a fragment rather than a truncated answer. Only the final `stop` dispatch carries
+the synthesis. `recordTurn` fired on all ~13, and the last writer won.
+
+The same root cause explains the §6 pollution: `lastUserText` walks back to the last `user`
+message, which does **not** move while a tool loop runs, so the identical user text was
+appended once per round-trip too.
+
+**Fix.** `TurnRecord` gained `turnEnded` (`finishReason !== "tool_calls"`, set in
+`src/server/turn.ts`). The bridge buffers assistant fragments per conversation in a
+process-local map and flushes **once**, when the assistant yields back to the user, writing
+the loop's narration plus the closing synthesis as one message. Bounded by
+`MAX_PENDING_CHARS` / `MAX_PENDING_CONVERSATIONS`, since a turn that dies without a terminal
+dispatch never flushes. The terminal dispatch is appended past the char cap, so the model's
+actual answer is never what gets dropped.
+
+Covered by `test/context-bridge.test.ts` (loop records one turn; a running loop writes
+nothing; interleaved conversations buffer independently) and `test/turn.test.ts` (the
+`tool_calls` → `turnEnded=false` wiring). All four were verified to FAIL against the old
+behavior. `tools/agentdox-e2e.ts` step 6 proves it against a live server: four dispatches →
+exactly one user and one assistant message.
 
 ## 6. Also worth doing
 
 - **Context pollution.** `context_assemble` includes recent session messages, so recorded
-  test turns feed back into the next block (already observed: the block contained
-  `assistant:: high` from a prior run). Real usage is fine, but noisy test turns compound.
-  Consider a `sessionLimit` override for the bridge, or excluding router-authored sessions.
+  test turns feed back into the next block (observed: a block containing `assistant:: high`
+  from a prior run). The §5 fix removes the ~13×-per-turn duplication that made this acute,
+  but noisy *test* turns still compound — `tools/agentdox-e2e.ts` writes real sessions into
+  the scope every run. Consider a `sessionLimit` override for the bridge, or excluding
+  router-authored sessions.
 - **`context.timeoutMs` is 3000ms** and failures degrade silently at `debug` level by design.
   If agentdox is cold this can no-op invisibly. Consider logging the first failure at `warn`.
 - **Four copies of this project exist** on this machine: this repo, the research checkout,

package/docs/context-optimization.md

@@ -55,10 +55,12 @@ These are hard; the design is shaped by them.
   result without its call, nor an assistant tool_call without its result, nor
   reorder the pair.
 - **Never touch:** system/developer messages (they carry the system prompt and the
-  agentdox-injected block), the **volatile tail** (newest user-authored run, or the
-  trailing tool-result run of the current loop — the same window
-  `features.ts`/`cache-control.ts` treat as fresh), and image parts (they are
-  capability-relevant; see Edge cases).
+  agentdox-injected block), the **protected tail** (newest user-authored run, or the
+  trailing tool-result run of the current loop — the same window `features.ts`
+  treats as fresh), and image parts (they are capability-relevant; see Edge cases).
+  Note that `cache-control.ts` deliberately does **not** treat that tail as fresh:
+  a conversation is append-only, so the tail is exactly what the *next* turn will
+  read back out of the cache, and it gets a breakpoint (see Prompt cache below).
 - **Determinism.** `auto-model-router explain` replays a past decision offline.
   Phase 1 is a pure function of `(messages, target budget, model window)` →
   replayable. Phase 2 breaks this unless the summary is **pinned and persisted**
@@ -67,10 +69,19 @@ These are hard; the design is shaped by them.
   The governing law is already stated for the agentdox bridge
   (`src/context/bridge.ts`): *the same bytes are re-injected verbatim and the cache
   survives; a refresh rides on a cache miss that was happening anyway.* Compaction
-  obeys it — Phase 1 rules are **stable** (identical input → identical elision each
-  turn), so a message elided last turn is elided byte-identically this turn and the
-  prefix does not churn; Phase 2 summaries are pinned per conversation and refreshed
-  only when the cache is already cold.
+  obeys it in two ways: rules are **stable** (identical input → identical elision
+  each turn) *and* the truncation set is **monotone** (rule 3 below: oldest-first,
+  so it only extends forward and never rewrites an already-cached prefix). Phase 2
+  summaries are pinned per conversation and refreshed only when the cache is
+  already cold.
+- **Breakpoints must be reproducible.** A `cache_control` breakpoint only pays off
+  when a later turn asks to read the exact same byte prefix, so
+  `planCacheBreakpoints` places them where the next turn will place them again:
+  the system prefix, byte **milestones** at fixed multiples of
+  `cache.milestoneTokens` (default 20k) measured over *post-compaction* sizes, and
+  the **tail**. A boundary at "roughly 75% of history" — the pre-v0.2.9 behaviour —
+  drifts by one index per appended message, so every turn wrote a fresh cache entry
+  and read none of them.
 
 ## Precedent to reuse
 
@@ -184,8 +195,19 @@ A pure function `compact(messages, target, protectFrom) → { messages, saved, n
    fetch is authoritative.
 3. **Truncate large stale results** (`maxToolResultBytes`): remaining tool results
    outside the protected window whose content exceeds `maxToolResultBytes` are
-   reduced to `keepHeadBytes` + breadcrumb + `keepTailBytes`. Applied to the
-   **largest/oldest first** until under `target` or exhausted.
+   reduced to `keepHeadBytes` + breadcrumb + `keepTailBytes`. Applied **oldest
+   first** until under `target` or exhausted.
+
+   Oldest-first is a **prompt-cache requirement**, not an aesthetic. The selected
+   set is then always an index-ordered prefix of the eligible results, so across
+   turns it only ever extends forward: an existing edit keeps its index and keep
+   bytes, and new edits land after every previous one — leaving the cached prefix
+   byte-identical. Selecting largest-first instead inserts new edits at arbitrary
+   early indices on later turns, rewriting history the upstream had already
+   cached. Measured under largest-first: 61% cache read (bimodal 44%/90%, with
+   `cachedTokens` pinned at the system prefix on half the requests) against
+   76–82% on comparable pre-compaction sessions. `test/compaction.test.ts`
+   ("the edit set only ever extends forward") pins the property.
 4. **Age-drop assistant reasoning:** reasoning fields on assistant messages outside
    the protected window are dropped. (Largely redundant with the model-driven
    `stripAssistantReasoning`; matters only for reasoning-replay authors.)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auto-model-router",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "private": false,
   "description": "Local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter",
   "type": "module",

package/src/config/defaults.ts

@@ -144,6 +144,10 @@ export const DEFAULT_CONFIG: RouterConfig = {
 		// Anthropic allows 4 breakpoints; OpenRouter translates for other vendors.
 		maxBreakpoints: 4,
 		minPromptTokens: 2_048,
+		// One slot for the system prefix, one for the tail, leaving two milestones
+		// live at 4 breakpoints. 20k spacing keeps them coarse enough that a
+		// milestone survives many turns of appended tool output.
+		milestoneTokens: 20_000,
 	},
 	context: {
 		// Off until an agentdox URL + token are configured. Enabling this changes

package/src/config/schema.ts

@@ -127,6 +127,7 @@ const cache = z.strictObject({
 	injectBreakpoints: z.boolean().optional(),
 	maxBreakpoints: z.number().int().positive().optional(),
 	minPromptTokens: z.number().int().nonnegative().optional(),
+	milestoneTokens: z.number().int().positive().optional(),
 });
 
 const context = z.strictObject({

package/src/config/types.ts

@@ -286,6 +286,13 @@ export interface CacheConfig {
 	maxBreakpoints: number;
 	/** Skip injection below this prompt-token estimate; small prompts cannot cache. */
 	minPromptTokens: number;
+	/**
+	 * Spacing of the stable mid-history breakpoints, in prompt tokens. Boundaries
+	 * land at fixed multiples of this size, so the same prefix recurs turn after
+	 * turn and each turn reads what the last one wrote. Smaller = finer recovery
+	 * after a history rewrite, at the cost of more breakpoint slots.
+	 */
+	milestoneTokens: number;
 }
 
 export interface BudgetConfig {

package/src/context/bridge.ts

@@ -49,6 +49,29 @@ function renderBlock(raw: string, maxChars: number): string {
 	].join("\n");
 }
 
+/**
+ * Cap on assistant text buffered for one in-flight turn, chars. A memory guard
+ * only, not a quality knob: a 200-round-trip loop must not buffer without
+ * limit. The dispatch that ENDS the turn is appended past this cap, so the
+ * model's actual answer is never the thing that gets dropped.
+ */
+const MAX_PENDING_CHARS = 64_000;
+
+/**
+ * Cap on conversations buffering fragments at once. A turn that dies without a
+ * terminal dispatch (client disconnect, upstream error) leaves its buffer
+ * behind, so this map is bounded rather than trusted to drain.
+ */
+const MAX_PENDING_CONVERSATIONS = 64;
+
+/** Appends a mid-loop fragment, bounded. Blank-line joined: separate thoughts. */
+function appendFragment(prior: string, next: string): string {
+	if (next === "") return prior;
+	if (prior === "") return next.slice(0, MAX_PENDING_CHARS);
+	if (prior.length >= MAX_PENDING_CHARS) return prior;
+	return `${prior}\n\n${next}`.slice(0, MAX_PENDING_CHARS);
+}
+
 export function createContextBridge(opts: BridgeOptions): ContextBridge {
 	const { client, store, log, maxStalenessMs, maxBlockChars, recordTurns, maxQueue } = opts;
 
@@ -57,6 +80,10 @@ export function createContextBridge(opts: BridgeOptions): ContextBridge {
 	let queue: Promise<void> = Promise.resolve();
 	let queued = 0;
 	let closed = false;
+	// Assistant text buffered across an in-flight tool loop, keyed by
+	// conversation. Process-local by design: a turn never spans a restart, and
+	// losing a buffer whose turn already died costs nothing.
+	const pending = new Map<string, string>();
 
 	const shouldRefresh = (input: ContextResolveInput, pin: ContextPin | null): boolean => {
 		if (pin === null) return true;
@@ -115,7 +142,34 @@ export function createContextBridge(opts: BridgeOptions): ContextBridge {
 
 		recordTurn(rec: TurnRecord) {
 			if (!recordTurns || closed || rec.scope === "") return;
-			if (rec.userText === "" && rec.assistantText === "") return;
+
+			// Mid-loop dispatch: keep the fragment and wait for the turn to end.
+			// Writing here is what produced ~13 near-empty assistant messages per
+			// turn plus ~13 copies of an unchanged user message, which both lost
+			// the real answer and poisoned later context assembly.
+			if (!rec.turnEnded) {
+				if (rec.assistantText === "") return;
+				const prior = pending.get(rec.conversationKey);
+				if (prior === undefined && pending.size >= MAX_PENDING_CONVERSATIONS) {
+					log.debug("agentdox pending transcript budget full; dropping fragment", { conversations: pending.size });
+					return;
+				}
+				pending.set(rec.conversationKey, appendFragment(prior ?? "", rec.assistantText));
+				return;
+			}
+
+			// Turn over. Flush the whole loop's narration plus this dispatch's
+			// synthesis as ONE assistant message, attributed to the served model.
+			const buffered = pending.get(rec.conversationKey) ?? "";
+			pending.delete(rec.conversationKey);
+			const assistantText =
+				buffered === ""
+					? rec.assistantText
+					: rec.assistantText === ""
+						? buffered
+						: `${buffered}\n\n${rec.assistantText}`;
+
+			if (rec.userText === "" && assistantText === "") return;
 			if (queued >= maxQueue) {
 				log.debug("agentdox write-back queue full; dropping turn record", { queued });
 				return;
@@ -134,7 +188,7 @@ export function createContextBridge(opts: BridgeOptions): ContextBridge {
 					// every turn shows WHICH model produced it.
 					const refs = [`model:${rec.slug}`, `tier:${rec.tier}`];
 					if (rec.userText !== "") await client.append(sessionId, "user", rec.userText, []);
-					if (rec.assistantText !== "") await client.append(sessionId, "assistant", rec.assistantText, refs);
+					if (assistantText !== "") await client.append(sessionId, "assistant", assistantText, refs);
 				})
 				.catch((err: unknown) => {
 					log.debug("agentdox write-back failed", { error: err instanceof Error ? err.message : String(err) });
@@ -150,6 +204,7 @@ export function createContextBridge(opts: BridgeOptions): ContextBridge {
 
 		close() {
 			closed = true;
+			pending.clear();
 		},
 	};
 }

package/src/context/types.ts

@@ -49,10 +49,23 @@ export interface TurnRecord {
 	/** Title used if this is the first turn and a session must be created. */
 	title: string;
 	userText: string;
+	/** Text THIS dispatch produced. Fragments are joined across a tool loop. */
 	assistantText: string;
 	/** The slug that actually served the turn — the model attribution. */
 	slug: string;
 	tier: string;
+	/**
+	 * Whether the assistant yielded control back to the user — i.e. the upstream
+	 * finish reason was NOT `tool_calls`.
+	 *
+	 * A user-visible turn is many dispatches: every tool round-trip is its own
+	 * request, and only the last carries the model's synthesis. The intermediate
+	 * ones are almost pure tool calls with a few stray words of text, and the
+	 * last *user* message does not move while the loop runs. False therefore
+	 * means "buffer this fragment, the turn is still running" — recording it as
+	 * a turn would write a near-empty answer and re-append the same user text.
+	 */
+	turnEnded: boolean;
 }
 
 export interface ContextBridge {

package/src/router/cache-control.ts

@@ -2,15 +2,39 @@
  * Cache-breakpoint placement (Anthropic-style `cache_control: ephemeral`;
  * OpenRouter translates these to OpenAI/Google cache primitives, so one
  * mechanism covers every target). Returns message indices to mark.
+ *
+ * Placement is chosen for REUSE ACROSS TURNS, not for a single request. A
+ * breakpoint only pays off when a LATER turn asks to read the exact same byte
+ * prefix, so every boundary here must be one the next turn will reproduce:
+ *
+ *  - the system prefix, which never moves;
+ *  - byte MILESTONES at fixed multiples of `cache.milestoneTokens`, which land
+ *    on the same message every turn for as long as the prefix is unchanged
+ *    (a boundary at "roughly 75% of history" drifts with every appended
+ *    message, so it writes a fresh entry each turn and never reads one);
+ *  - the tail, so the whole of this turn's prompt becomes the entry the NEXT
+ *    turn reads. A conversation is append-only: nothing already in the array
+ *    can change later, so there is no "volatile tail" to keep out of the
+ *    cache. Walking back over an agent loop's trailing tool run instead left
+ *    everything the loop had accumulated permanently uncached.
+ *
+ * Milestones are measured over POST-compaction sizes, so the boundaries match
+ * the bytes actually dispatched.
  */
 
 import type { CatalogModel } from "../catalog/types.ts";
 import type { RouterConfig } from "../config/types.ts";
 import { priceAt } from "../cost/forecast.ts";
 import { estimateTokens } from "../tokens/estimate.ts";
-import type { NormMessage, NormRequest } from "../wire/types.ts";
+import type { CompactionEdit, NormRequest } from "../wire/types.ts";
+import { compactedBytes } from "./compaction.ts";
 
-export function planCacheBreakpoints(req: NormRequest, model: CatalogModel, cfg: RouterConfig): number[] {
+export function planCacheBreakpoints(
+	req: NormRequest,
+	model: CatalogModel,
+	cfg: RouterConfig,
+	compactionPlan: readonly CompactionEdit[] = [],
+): number[] {
 	if (!cfg.cache.injectBreakpoints) return [];
 	const promptTokens = estimateTokens(req.promptBytes, model.tokenizer, null);
 	// Small prompts cannot amortize cache-write cost.
@@ -19,6 +43,8 @@ export function planCacheBreakpoints(req: NormRequest, model: CatalogModel, cfg:
 	if (priceAt(model, Math.max(1, promptTokens)).cacheRead === undefined) return [];
 
 	const messages = req.messages;
+	if (messages.length === 0) return [];
+
 	const picks: number[] = [];
 
 	// 1. End of the last system message: the most stable, usually largest prefix.
@@ -30,28 +56,33 @@ export function planCacheBreakpoints(req: NormRequest, model: CatalogModel, cfg:
 		}
 	}
 
-	// 2. End of the last message before the volatile tail — the newest
-	//    user-authored content, or the trailing tool-result run of an agent
-	//    loop. Caches everything the model has already seen, leaving only the
-	//    fresh tail uncached.
-	const tail = messages[messages.length - 1];
-	if (tail !== undefined) {
-		let pred: (m: NormMessage) => boolean;
-		if (tail.role === "user") pred = (m) => m.role === "user";
-		else if (tail.role === "tool") pred = (m) => m.role === "tool" || (m.role === "assistant" && m.toolCalls.length > 0);
-		// An assistant tail has no fresh human content; the whole history is prefix.
-		else pred = () => false;
-		let i = messages.length - 1;
-		while (i >= 0) {
-			const m = messages[i];
-			if (m === undefined || !pred(m)) break;
-			i--;
+	// 2. The tail: everything this turn sent, cached for the next turn to read.
+	picks.push(messages.length - 1);
+
+	// 3. Stable byte milestones through the history, newest first so the slots
+	//    left over by 1 and 2 cover the largest readable prefixes.
+	const editByIndex = new Map<number, CompactionEdit>();
+	for (const e of compactionPlan) editByIndex.set(e.index, e);
+	const bytesPerToken = req.promptBytes / Math.max(1, promptTokens);
+	const milestoneBytes = Math.max(1, Math.floor(cfg.cache.milestoneTokens * bytesPerToken));
+	const milestones: number[] = [];
+	let cumulative = 0;
+	let nextMilestone = milestoneBytes;
+	for (let i = 0; i < messages.length - 1; i++) {
+		const m = messages[i];
+		if (m === undefined) continue;
+		cumulative += compactedBytes(m.textBytes, editByIndex.get(i));
+		if (cumulative >= nextMilestone) {
+			milestones.push(i);
+			// Skip past every milestone this message already crossed, so one huge
+			// message cannot claim a run of adjacent boundaries.
+			while (cumulative >= nextMilestone) nextMilestone += milestoneBytes;
 		}
-		if (i >= 0) picks.push(i);
 	}
-
-	// 3. Stable prefix boundary at roughly 75% of history.
-	if (messages.length > 1) picks.push(Math.floor((messages.length - 1) * 0.75));
+	for (let i = milestones.length - 1; i >= 0; i--) {
+		const idx = milestones[i];
+		if (idx !== undefined) picks.push(idx);
+	}
 
 	// Dedupe preserving priority order, cap, return ascending indices.
 	const seen = new Set<number>();

package/src/router/compaction.ts

@@ -26,6 +26,17 @@ const EMPTY: CompactionResult = { edits: [], savedBytes: 0 };
 /** Approximate byte cost of an elision breadcrumb; savings are net of it. */
 const BREADCRUMB_BYTES = 120;
 
+/**
+ * Byte size a message ends up with once `edit` is applied — the size that
+ * actually reaches the upstream. Cache-breakpoint placement walks these rather
+ * than the raw `textBytes`, so its boundaries match the dispatched bytes.
+ */
+export function compactedBytes(originalBytes: number, edit: CompactionEdit | undefined): number {
+	if (edit === undefined) return originalBytes;
+	const kept = edit.mode === "stub" ? BREADCRUMB_BYTES : edit.keepHead + edit.keepTail + BREADCRUMB_BYTES;
+	return Math.min(originalBytes, kept);
+}
+
 /**
  * First string value in a tool call's argument JSON — a schema-agnostic proxy
  * for the resource a call operates on (a `path`, `id`, `query`, ...). Used to
@@ -73,9 +84,18 @@ interface ToolResult {
 /**
  * Plans compaction for a turn's messages toward `targetBytes` of total prompt.
  * Duplicate and superseded elisions (pure stale-data wins) are always applied;
- * large-result truncation (more lossy) runs largest-first only until the target
+ * large-result truncation (more lossy) runs OLDEST-first only until the target
  * is met. `promptBytes` is the whole prompt (messages + system + tool schemas),
  * so the target is compared against the real dispatched size.
+ *
+ * Oldest-first is a prompt-cache requirement, not a preference. The truncated
+ * set is then always an index-ordered PREFIX of the eligible results, so as a
+ * conversation grows and the target tightens the set only ever EXTENDS FORWARD:
+ * an edit already made keeps the same index and the same keep bytes, and a new
+ * edit lands after every previous one. Selecting largest-first instead inserts
+ * fresh edits at arbitrarily early indices on later turns, rewriting history
+ * the upstream had already cached and collapsing cache reads to the system
+ * prefix (measured: 61% cache read, bimodal, vs 76-82% before compaction).
  */
 export function planCompaction(
 	messages: readonly NormMessage[],
@@ -145,11 +165,11 @@ export function planCompaction(
 		}
 	}
 
-	// Rule 3: truncate large stale results, largest first, until under target.
+	// Rule 3: truncate large stale results, OLDEST first, until under target.
+	// `tools` is already in message order, so the filter alone yields that order
+	// and the selected set stays an extend-forward prefix across turns.
 	const keepBudget = cfg.keepHeadBytes + cfg.keepTailBytes + BREADCRUMB_BYTES;
-	const truncatable = tools
-		.filter((t) => !done.has(t.index) && t.bytes > cfg.maxToolResultBytes && t.bytes > keepBudget)
-		.sort((a, b) => b.bytes - a.bytes || a.index - b.index);
+	const truncatable = tools.filter((t) => !done.has(t.index) && t.bytes > cfg.maxToolResultBytes && t.bytes > keepBudget);
 	for (const t of truncatable) {
 		if (promptBytes - saved <= targetBytes) break;
 		edits.push({ index: t.index, mode: "truncate", keepHead: cfg.keepHeadBytes, keepTail: cfg.keepTailBytes, note: `large ${t.name || "tool"} result` });

package/src/router/select.ts

@@ -390,8 +390,9 @@ export function select(args: SelectArgs): Decision {
 		if (fallbacks.length >= 2) break;
 	}
 
-	// 7. Cache breakpoints.
-	const cacheBreakpointMessageIndices = planCacheBreakpoints(req, chosen.model, cfg);
+	// 7. Cache breakpoints, measured over post-compaction sizes so the
+	//    boundaries match the bytes that actually get dispatched.
+	const cacheBreakpointMessageIndices = planCacheBreakpoints(req, chosen.model, cfg, compactionPlan);
 
 	// 8. Guarded probe: only tiers configured for probing, and only when a
 	//    strictly higher tier exists inside the profile envelope to escalate into.

package/src/server/turn.ts

@@ -448,22 +448,28 @@ export async function runTurn(
 
 		// Record the settled turn into agentdox, attributed to the model that
 		// actually served it. Queued and never awaited: the transcript is an
-		// artifact of the turn, not a precondition for finishing it.
+		// artifact of the turn, not a precondition for finishing it. A
+		// `tool_calls` finish means the assistant is still working, so the bridge
+		// buffers the fragment rather than writing a near-empty turn.
 		if (doxActive) {
+			const userText = lastUserText(req);
+			const turnEnded = finishReason !== "tool_calls";
 			log.debug("agentdox record turn", {
-				userChars: lastUserText(req).length,
+				conversationKey: req.conversationKey.slice(0, 8),
+				userChars: userText.length,
 				assistantChars: assistantText.length,
-				messages: req.messages.length,
-				roles: req.messages.map((m) => m.role).join(","),
+				finishReason,
+				turnEnded,
 			});
 			bridge.recordTurn({
 				scope: doxScope,
 				conversationKey: req.conversationKey,
 				title: sessionTitle(req),
-				userText: lastUserText(req),
+				userText,
 				assistantText,
 				slug: servedSlug ?? decision.slug,
 				tier: decision.tier,
+				turnEnded,
 			});
 		}
 

package/test/cache-control.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, test } from "bun:test";
+
+import { normalizeCatalogModel } from "../src/catalog/openrouter-catalog.ts";
+import type { CatalogModel } from "../src/catalog/types.ts";
+import { loadConfig } from "../src/config/load.ts";
+import type { RouterConfig } from "../src/config/types.ts";
+import { priceAt } from "../src/cost/forecast.ts";
+import { planCacheBreakpoints } from "../src/router/cache-control.ts";
+import { planCompaction } from "../src/router/compaction.ts";
+import { parseChatRequest } from "../src/wire/openai/request.ts";
+import type { NormRequest } from "../src/wire/types.ts";
+
+const FIXTURE = (await Bun.file("test/fixtures/openrouter-models.json").json()) as { data: unknown[] };
+const MODELS: CatalogModel[] = FIXTURE.data.map(normalizeCatalogModel).filter((m): m is CatalogModel => m !== null);
+// Breakpoints are only planned for models that publish a cache-read price.
+const CACHING = MODELS.find((m) => priceAt(m, 100_000).cacheRead !== undefined);
+if (CACHING === undefined) throw new Error("fixture has no model with a published cache-read price");
+const MODEL: CatalogModel = CACHING;
+
+const BASE = loadConfig({});
+function cfg(over: Partial<RouterConfig["cache"]> = {}): RouterConfig {
+	return { ...BASE, cache: { ...BASE.cache, ...over } };
+}
+
+const RESULT_BYTES = 8_000;
+const result = (turn: number): string => `result ${turn}:${"x".repeat(RESULT_BYTES)}`;
+
+/** A tool-loop conversation: system, one user ask, then `turns` call/result pairs. */
+function loop(turns: number): NormRequest {
+	const messages: Record<string, unknown>[] = [
+		{ role: "system", content: `You are a coding agent.${"!".repeat(4_000)}` },
+		{ role: "user", content: "find the bug" },
+	];
+	for (let t = 0; t < turns; t++) {
+		messages.push({
+			role: "assistant",
+			content: null,
+			tool_calls: [{ id: `c${t}`, type: "function", function: { name: "read", arguments: `{"path":"f${t}.ts"}` } }],
+		});
+		messages.push({ role: "tool", tool_call_id: `c${t}`, content: result(t) });
+	}
+	return parseChatRequest({ model: "auto", messages }, new Headers());
+}
+
+describe("planCacheBreakpoints", () => {
+	test("marks the tail so the next turn can read this turn's whole prompt", () => {
+		const req = loop(12);
+		const picks = planCacheBreakpoints(req, MODEL, cfg());
+		expect(picks).toContain(req.messages.length - 1);
+	});
+
+	test("marks the system prefix", () => {
+		const req = loop(12);
+		const picks = planCacheBreakpoints(req, MODEL, cfg());
+		expect(picks).toContain(0);
+	});
+
+	test("mid-history boundaries are stable as the conversation grows", () => {
+		// Uncapped so the comparison is about placement, not slot eviction.
+		const uncapped = cfg({ maxBreakpoints: 64, milestoneTokens: 4_000 });
+		const mid = (turns: number): number[] => {
+			const req = loop(turns);
+			const tail = req.messages.length - 1;
+			return planCacheBreakpoints(req, MODEL, uncapped).filter((i) => i !== 0 && i !== tail);
+		};
+		const early = mid(10);
+		expect(early.length).toBeGreaterThan(1);
+		for (const turns of [11, 12, 13, 20]) {
+			// Every boundary the earlier turn wrote is still a boundary later, so
+			// the later turn reads what the earlier one paid to write.
+			expect(mid(turns)).toEqual(expect.arrayContaining(early));
+		}
+	});
+
+	test("boundaries are spaced by the milestone size, not by message position", () => {
+		const req = loop(30);
+		const tail = req.messages.length - 1;
+		const coarse = planCacheBreakpoints(req, MODEL, cfg({ maxBreakpoints: 64, milestoneTokens: 20_000 })).filter(
+			(i) => i !== 0 && i !== tail,
+		);
+		const fine = planCacheBreakpoints(req, MODEL, cfg({ maxBreakpoints: 64, milestoneTokens: 4_000 })).filter(
+			(i) => i !== 0 && i !== tail,
+		);
+		expect(fine.length).toBeGreaterThan(coarse.length);
+	});
+
+	test("keeps the system prefix and the tail when slots are scarce", () => {
+		const req = loop(30);
+		const picks = planCacheBreakpoints(req, MODEL, cfg({ maxBreakpoints: 2, milestoneTokens: 4_000 }));
+		expect(picks).toEqual([0, req.messages.length - 1]);
+	});
+
+	test("milestones follow post-compaction sizes", () => {
+		const req = loop(30);
+		const tail = req.messages.length - 1;
+		const plan = planCompaction(req.messages, BASE.compaction, req.promptBytes * 0.3, req.promptBytes);
+		expect(plan.edits.length).toBeGreaterThan(0);
+		const options = cfg({ maxBreakpoints: 64, milestoneTokens: 4_000 });
+		const raw = planCacheBreakpoints(req, MODEL, options).filter((i) => i !== 0 && i !== tail);
+		const compacted = planCacheBreakpoints(req, MODEL, options, plan.edits).filter((i) => i !== 0 && i !== tail);
+		// Shrinking early results pushes each byte milestone later in the history.
+		expect(compacted.length).toBeLessThan(raw.length);
+		expect(Math.min(...compacted)).toBeGreaterThan(Math.min(...raw));
+	});
+
+	test("injects nothing below the minimum prompt size, or when disabled", () => {
+		const small = parseChatRequest({ model: "auto", messages: [{ role: "user", content: "hi" }] }, new Headers());
+		expect(planCacheBreakpoints(small, MODEL, cfg())).toEqual([]);
+		expect(planCacheBreakpoints(loop(12), MODEL, cfg({ injectBreakpoints: false }))).toEqual([]);
+	});
+});

package/test/compaction.test.ts

@@ -99,6 +99,43 @@ describe("planCompaction", () => {
 		const b = planCompaction(msgs, CFG, 1, 10_000);
 		expect(a).toEqual(b);
 	});
+
+	// The prompt-cache contract: an edit, once made, keeps its index and its keep
+	// bytes for the rest of the conversation, and every later edit lands AFTER
+	// it. Anything else rewrites already-cached history and forces a full
+	// re-read of the prefix on the next turn.
+	test("the edit set only ever extends forward as the conversation grows", () => {
+		// Sizes GROW with age-descending order (newest results are the biggest), so
+		// a size-ordered planner selects newest-first and its later additions move
+		// BACKWARD into already-cached history. Equal-sized results would make
+		// every ordering identical and the assertions vacuous.
+		const loop = (pairs: number): NormMessage[] => {
+			const msgs: NormMessage[] = [user("go")];
+			for (let i = 0; i < pairs; i++) {
+				const content = `R${i}:${"x".repeat(200 + i * 40)}`;
+				msgs.push(asst(`c${i}`, "read", `{"path":"f${i}.ts"}`), toolMsg(`c${i}`, "read", content));
+			}
+			return msgs;
+		};
+		let previous: number[] = [];
+		for (let pairs = 4; pairs <= 24; pairs++) {
+			const msgs = loop(pairs);
+			const promptBytes = msgs.reduce((n, m) => n + m.textBytes, 0);
+			// A target the plan can hit with a handful of edits: this is where the
+			// selection ORDER decides which results get truncated. A saturating
+			// target would truncate everything and hide the difference.
+			const indices = planCompaction(msgs, CFG, Math.floor(promptBytes * 0.8), promptBytes).edits.map((e) => e.index);
+			// Nothing already compacted may be dropped...
+			expect(indices).toEqual(expect.arrayContaining(previous));
+			// ...and anything new lands after every existing edit.
+			const added = indices.filter((i) => !previous.includes(i));
+			if (previous.length > 0 && added.length > 0) {
+				expect(Math.min(...added)).toBeGreaterThan(Math.max(...previous));
+			}
+			previous = indices;
+		}
+		expect(previous.length).toBeGreaterThan(4);
+	});
 });
 
 describe("renderUpstreamBody applies compaction", () => {

package/test/context-bridge.test.ts

@@ -3,7 +3,7 @@ import { describe, expect, test } from "bun:test";
 import type { AgentDoxClient } from "../src/context/agentdox.ts";
 import { createContextBridge } from "../src/context/bridge.ts";
 import { createContextStore } from "../src/context/store.ts";
-import type { ContextResolveInput } from "../src/context/types.ts";
+import type { ContextResolveInput, TurnRecord } from "../src/context/types.ts";
 import { createLogger } from "../src/util/log.ts";
 import { openDb } from "../src/util/sqlite.ts";
 import { injectForTest } from "./helpers/inject.ts";
@@ -246,6 +246,7 @@ describe("context bridge write-back", () => {
 				assistantText: "done",
 				slug: "anthropic/claude-haiku-4.5",
 				tier: "simple",
+				turnEnded: true,
 			});
 			bridge.recordTurn({
 				scope: "ashlands",
@@ -255,6 +256,7 @@ describe("context bridge write-back", () => {
 				assistantText: "ok",
 				slug: "anthropic/claude-opus-4.5",
 				tier: "hard",
+				turnEnded: true,
 			});
 			await bridge.flush();
 
@@ -280,6 +282,7 @@ describe("context bridge write-back", () => {
 				assistantText: "a",
 				slug: "x",
 				tier: "simple",
+				turnEnded: true,
 			});
 			await bridge.flush();
 			expect(client.appended).toHaveLength(0);
@@ -287,6 +290,96 @@ describe("context bridge write-back", () => {
 			db.close();
 		}
 	});
+
+	/** One dispatch of a turn; `turnEnded` marks the one that yields to the user. */
+	function mkRecord(over: Partial<TurnRecord> & { turnEnded: boolean }): TurnRecord {
+		return {
+			scope: "ashlands",
+			conversationKey: "k1",
+			title: "movement fix",
+			userText: "fix movement",
+			assistantText: "",
+			slug: "z-ai/glm-5.3-flash",
+			tier: "simple",
+			...over,
+		};
+	}
+
+	test("a tool loop records one turn, not one record per dispatch", async () => {
+		const client = mkClient();
+		const { bridge, db } = mkBridge(client);
+		try {
+			// One user-visible turn: five tool round-trips, then the synthesis.
+			// Every dispatch carries the SAME unchanged user text — recording per
+			// dispatch appended it once per round-trip and buried the real answer
+			// under near-empty assistant messages.
+			for (const assistantText of ["let me look", "", "checking the ledger", "", "almost there"]) {
+				bridge.recordTurn(mkRecord({ assistantText, turnEnded: false }));
+			}
+			bridge.recordTurn(mkRecord({ assistantText: "fixed: the damping was inverted.", turnEnded: true }));
+			await bridge.flush();
+
+			expect(client.sessionsCreated).toBe(1);
+			const users = client.appended.filter((m) => m.role === "user");
+			const assistants = client.appended.filter((m) => m.role === "assistant");
+			expect(users).toHaveLength(1);
+			expect(assistants).toHaveLength(1);
+			// The loop's narration AND the closing synthesis survive, in order.
+			expect(assistants[0]?.content).toBe(
+				"let me look\n\nchecking the ledger\n\nalmost there\n\nfixed: the damping was inverted.",
+			);
+			expect(assistants[0]?.refs).toEqual(["model:z-ai/glm-5.3-flash", "tier:simple"]);
+		} finally {
+			db.close();
+		}
+	});
+
+	test("a tool loop still running writes nothing", async () => {
+		const client = mkClient();
+		const { bridge, db } = mkBridge(client);
+		try {
+			bridge.recordTurn(mkRecord({ assistantText: "let me look", turnEnded: false }));
+			await bridge.flush();
+			// The assistant has not answered yet. Writing here is what produced the
+			// 4-char transcripts, so mid-loop must stay silent.
+			expect(client.appended).toHaveLength(0);
+			expect(client.sessionsCreated).toBe(0);
+		} finally {
+			db.close();
+		}
+	});
+
+	test("interleaved conversations buffer independently", async () => {
+		const client = mkClient();
+		const { bridge, db } = mkBridge(client);
+		try {
+			bridge.recordTurn(mkRecord({ conversationKey: "k1", assistantText: "k1 narration", turnEnded: false }));
+			bridge.recordTurn(mkRecord({ conversationKey: "k2", assistantText: "k2 narration", turnEnded: false }));
+			bridge.recordTurn(mkRecord({ conversationKey: "k2", assistantText: "k2 answer", turnEnded: true }));
+			bridge.recordTurn(mkRecord({ conversationKey: "k1", assistantText: "k1 answer", turnEnded: true }));
+			await bridge.flush();
+
+			const assistants = client.appended.filter((m) => m.role === "assistant");
+			expect(assistants).toHaveLength(2);
+			expect(assistants[0]?.content).toBe("k2 narration\n\nk2 answer");
+			expect(assistants[1]?.content).toBe("k1 narration\n\nk1 answer");
+		} finally {
+			db.close();
+		}
+	});
+
+	test("a silent turn still records the user message", async () => {
+		const client = mkClient();
+		const { bridge, db } = mkBridge(client);
+		try {
+			bridge.recordTurn(mkRecord({ assistantText: "", turnEnded: true }));
+			await bridge.flush();
+			expect(client.appended.filter((m) => m.role === "user")).toHaveLength(1);
+			expect(client.appended.filter((m) => m.role === "assistant")).toHaveLength(0);
+		} finally {
+			db.close();
+		}
+	});
 });
 
 describe("context injection into the wire body", () => {

package/test/failover.test.ts

@@ -68,7 +68,7 @@ function mkConfig(escalation: Partial<EscalationConfig> = {}): RouterConfig {
 		},
 		hysteresis: { holdTurns: 2, holdTurnsAfterEscalation: 4, switchMargin: 1.5, cacheWarmTtlMs: 600_000, maxDowngradePerTurn: 1 },
 		exploration: { enabled: false, rates: {}, stickyPolicy: "never", holdTurns: { enabled: false, values: [2, 3, 4] } },
-		cache: { injectBreakpoints: true, maxBreakpoints: 4, minPromptTokens: 1024 },
+		cache: { injectBreakpoints: true, maxBreakpoints: 4, minPromptTokens: 1024, milestoneTokens: 20_000 },
 		context: { enabled: false, baseUrl: "", token: "", defaultScope: "", timeoutMs: 3_000, maxStalenessMs: 900_000, maxBlockChars: 24_000, recordTurns: false, maxQueue: 64 },
 		compaction: { enabled: false, budgetTokens: 40_000, fitToWindow: true, protectRecentTurns: 4, maxToolResultBytes: 4_096, keepHeadBytes: 512, keepTailBytes: 512, elideSupersededReads: true, collapseDuplicateResults: true },
 		budget: { onExceeded: "downgrade" },

package/test/turn.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { createDisabledBridge } from "../src/context/bridge.ts";
+import type { ContextBridge, TurnRecord } from "../src/context/types.ts";
 import type { CatalogSource } from "../src/catalog/types.ts";
 import type { EscalationConfig, RouterConfig } from "../src/config/types.ts";
 import { EMPTY_USAGE, type Ledger, type LedgerEntry, type UsageCounts } from "../src/cost/types.ts";
@@ -68,7 +69,7 @@ function mkConfig(escalation: Partial<EscalationConfig> = {}): RouterConfig {
 		},
 		hysteresis: { holdTurns: 2, holdTurnsAfterEscalation: 4, switchMargin: 1.5, cacheWarmTtlMs: 600_000, maxDowngradePerTurn: 1 },
 		exploration: { enabled: false, rates: {}, stickyPolicy: "never", holdTurns: { enabled: false, values: [2, 3, 4] } },
-		cache: { injectBreakpoints: true, maxBreakpoints: 4, minPromptTokens: 1024 },
+		cache: { injectBreakpoints: true, maxBreakpoints: 4, minPromptTokens: 1024, milestoneTokens: 20_000 },
 		context: { enabled: false, baseUrl: "", token: "", defaultScope: "", timeoutMs: 3_000, maxStalenessMs: 900_000, maxBlockChars: 24_000, recordTurns: false, maxQueue: 64 },
 		compaction: { enabled: false, budgetTokens: 40_000, fitToWindow: true, protectRecentTurns: 4, maxToolResultBytes: 4_096, keepHeadBytes: 512, keepTailBytes: 512, elideSupersededReads: true, collapseDuplicateResults: true },
 		budget: { onExceeded: "downgrade" },
@@ -553,3 +554,53 @@ describe("exploration reaches the ledger", () => {
 		expect(entries[0]?.exploredFrom).toBeNull();
 	});
 });
+
+describe("agentdox write-back sees the shape of the turn", () => {
+	function mkRecordingBridge(): { bridge: ContextBridge; records: TurnRecord[] } {
+		const records: TurnRecord[] = [];
+		return {
+			records,
+			bridge: {
+				enabled: true,
+				resolve: () => Promise.resolve(null),
+				recordTurn: (rec) => {
+					records.push(rec);
+				},
+				flush: () => Promise.resolve(),
+				close: () => {},
+			},
+		};
+	}
+
+	test("a tool_calls finish is a fragment; only a yielding finish ends the turn", async () => {
+		// A user-visible turn is many dispatches. The orchestrator must tell the
+		// bridge which one actually handed control back, or the transcript records
+		// a near-empty answer per tool round-trip and re-appends the same user
+		// text every time.
+		const { router } = mkRouter([
+			mkDecision("simple", "cheap/model", { escalateTo: null }),
+			mkDecision("simple", "cheap/model", { escalateTo: null }),
+		]);
+		const { upstream } = mkUpstream([
+			{ kind: "chunks", chunks: [startChunk("cheap/model"), textChunk("let me look"), finishChunk("tool_calls"), usageChunk({}, 0.0001)] },
+			{ kind: "chunks", chunks: [startChunk("cheap/model"), textChunk("all done"), finishChunk("stop"), usageChunk({}, 0.0001)] },
+		]);
+		const { ledger } = mkLedger();
+		const { store } = mkConversations();
+		const { sink, errors } = mkSink();
+		const { bridge, records } = mkRecordingBridge();
+		// doxActive needs a scope; the request header supplies it.
+		const req: NormRequest = { ...mkReq(), agentdoxScope: "proj" };
+		const deps = { config: mkConfig({ enabled: false }), router, upstream, ledger, conversations: store, catalog, context: bridge };
+
+		await runTurn(req, sink, deps, new AbortController().signal);
+		await runTurn(req, sink, deps, new AbortController().signal);
+
+		expect(errors).toHaveLength(0);
+		expect(records).toHaveLength(2);
+		expect(records[0]?.turnEnded).toBe(false);
+		expect(records[0]?.assistantText).toBe("let me look");
+		expect(records[1]?.turnEnded).toBe(true);
+		expect(records[1]?.assistantText).toBe("all done");
+	});
+});

package/tools/agentdox-e2e.ts

@@ -93,6 +93,7 @@ bridge.recordTurn({
 	assistantText: "yes - refs carry model: and tier:.",
 	slug: "anthropic/claude-haiku-4.5",
 	tier: "simple",
+	turnEnded: true,
 });
 await bridge.flush();
 
@@ -118,6 +119,52 @@ if (mine !== undefined) {
 	);
 }
 
+// 6. A tool loop must record ONE turn, not one record per dispatch. This is the
+//    regression that made transcripts useless: every tool round-trip is its own
+//    dispatch, finishing with `tool_calls` and carrying an UNCHANGED last user
+//    message, so recording per dispatch wrote a near-empty assistant message
+//    and a duplicate user message per round-trip.
+const loopKey = `${conversationKey}-loop`;
+const loopTitle = `bridge e2e loop ${loopKey}`;
+function loopDispatch(assistantText: string, turnEnded: boolean): void {
+	bridge.recordTurn({
+		scope,
+		conversationKey: loopKey,
+		title: loopTitle,
+		userText: "why did cache read fall?",
+		assistantText,
+		slug: "z-ai/glm-5.3-flash",
+		tier: "simple",
+		turnEnded,
+	});
+}
+for (const fragment of ["reading the ledger", "", "checking the cache column"]) loopDispatch(fragment, false);
+loopDispatch("the breakpoint index drifted every turn.", true);
+await bridge.flush();
+
+const loopRes = await fetch(`${baseUrl}/sessions?scope=${encodeURIComponent(scope)}`, {
+	headers: { authorization: `Bearer ${token}` },
+});
+const loopSessions = (await loopRes.json()) as { id: string; title: string }[];
+const loopSession = loopSessions.find((s) => s.title === loopTitle);
+check("tool loop created a session", loopSession !== undefined, loopSession?.id ?? "not found");
+
+if (loopSession !== undefined) {
+	const full = await fetch(`${baseUrl}/sessions/${loopSession.id}`, {
+		headers: { authorization: `Bearer ${token}` },
+	});
+	const session = (await full.json()) as { messages: { role: string; content: string }[] };
+	const users = session.messages.filter((m) => m.role === "user");
+	const assistants = session.messages.filter((m) => m.role === "assistant");
+	check("four dispatches wrote exactly one user message", users.length === 1, `${users.length} user messages`);
+	check("four dispatches wrote exactly one assistant message", assistants.length === 1, `${assistants.length} assistant messages`);
+	check(
+		"the loop's narration and the closing synthesis both survive",
+		assistants[0]?.content === "reading the ledger\n\nchecking the cache column\n\nthe breakpoint index drifted every turn.",
+		JSON.stringify(assistants[0]?.content ?? ""),
+	);
+}
+
 db.close();
 console.log(failures === 0 ? "\nAll bridge e2e checks passed." : `\n${failures} check(s) failed.`);
 process.exit(failures === 0 ? 0 : 1);