@iowarp/clio-coder 0.3.3 → 0.3.4

package/src/domains/config/classify.ts

@@ -56,6 +56,7 @@ const NEXT_TURN_FIELDS = new Set<string>([
 	"skills",
 	"delegation",
 	"compaction",
+	"context",
 	"retry",
 ]);
 

package/src/domains/context/working-set/contract.ts

@@ -0,0 +1,161 @@
+/**
+ * Working-set layer contract.
+ *
+ * The working set is what the model sees on the next request. The ledger is
+ * durable, append-only truth. This layer decides which tool-result bodies and
+ * thinking blocks leave the working set, records that decision as
+ * `contextEviction` entries, and applies it as an in-memory projection when
+ * the replay messages are built. Nothing here rewrites the ledger and nothing
+ * here calls a model.
+ *
+ * Shared by the live engine and the replay-lite runner by construction: a
+ * policy is a pure function of `PolicyInput`, so the same selection runs in
+ * both places. Widening these types is an owner decision; workers build
+ * against them.
+ */
+
+import type { WorkingSetPolicyId, WorkingSetSettings } from "../../../core/defaults.js";
+import type {
+	ContextEvictionEntry,
+	ContextRecallEntry,
+	EvictedItem,
+	EvictionReason,
+	EvictionTrigger,
+	RecallTrigger,
+	SessionEntry,
+	WorkingSetRef,
+} from "../../session/entries.js";
+
+export { EVICTION_REASONS, EVICTION_TRIGGERS, RECALL_TRIGGERS } from "../../session/entries.js";
+export type {
+	ContextEvictionEntry,
+	ContextRecallEntry,
+	EvictedItem,
+	EvictionReason,
+	EvictionTrigger,
+	RecallTrigger,
+	WorkingSetPolicyId,
+	WorkingSetRef,
+	WorkingSetSettings,
+};
+
+/**
+ * What the fold knows about one evicted unit. Keyed in `WorkingSetView.evicted`
+ * by the entry turnId (`ref.entry`); `fold.ts` owns `refKey` / `parseRefKey`.
+ */
+export interface EvictedState {
+	reason: EvictionReason;
+	marker: string;
+	by?: string;
+	tokensFreed: number;
+	/** turnId of the `contextEviction` entry that evicted it (the latest one, after churn). */
+	evictedAtTurnId: string;
+	policyId: string;
+}
+
+/**
+ * The fold of every `contextEviction` / `contextRecall` entry on the active
+ * path. A recall does not remove its key: the recalled body lives in the
+ * recall tool result at the tail of the working set, the marker stays at the
+ * original position so the prefix cache is untouched, and repeated recalls of
+ * one ref are the churn signal.
+ */
+export interface WorkingSetView {
+	evicted: ReadonlyMap<string, EvictedState>;
+	/** Applied eviction events on the active path. */
+	evictionEvents: number;
+	/** Items evicted across all events, including re-evictions after recall. */
+	itemsEvicted: number;
+	/** Recall entries on the active path. `churn = recalls / itemsEvicted`. */
+	recalls: number;
+	/** Policy that produced the most recent event; null when none. */
+	lastPolicyId: string | null;
+	/** turnId of the most recent eviction event; null when none. */
+	lastEvictionTurnId: string | null;
+}
+
+export const EMPTY_WORKING_SET_VIEW: WorkingSetView = Object.freeze({
+	evicted: new Map<string, EvictedState>(),
+	evictionEvents: 0,
+	itemsEvicted: 0,
+	recalls: 0,
+	lastPolicyId: null,
+	lastEvictionTurnId: null,
+});
+
+export interface PressureInput {
+	/** Estimated tokens in the current working set (projected), same estimator as the live pressure check. */
+	tokens: number;
+	contextWindow: number;
+	/** `compaction.threshold`. */
+	threshold: number;
+	/** `context.workingSet.target`: the ratio an applied event batches down to. */
+	target: number;
+}
+
+/**
+ * Everything a policy may look at. `entries` are the active-path entries the
+ * model can currently see: after the latest `compactionSummary` cut, in ledger
+ * order, as `selectVisibleEntries` in visible.ts produces them. They are NOT
+ * projected: a policy must consult `view.evicted` to skip units that are
+ * already out. The view is folded over the full active path, so a ref evicted
+ * before a later compaction is still known. Token counts enter selection only
+ * through `settings.minEvictableTokens` and the headroom arithmetic against
+ * `pressure.target`; no rule may rank candidates by size or recency score.
+ */
+export interface PolicyInput {
+	entries: ReadonlyArray<SessionEntry>;
+	view: WorkingSetView;
+	/** Session working directory for the path index; null when unknown (paths stay relative). */
+	cwd: string | null;
+	settings: WorkingSetSettings;
+	pressure: PressureInput;
+	/** chars/4 estimator shared with `context-accounting.ts`, so replay and live agree. */
+	estimateTokens: (entry: SessionEntry) => number;
+}
+
+/** A unit the policy wants out, with the typed reason. Ordered: apply in this order, stop when headroom is met. */
+export interface EvictionCandidate {
+	ref: WorkingSetRef;
+	reason: EvictionReason;
+	by?: string;
+}
+
+export interface WorkingSetPolicy {
+	readonly id: WorkingSetPolicyId;
+	/**
+	 * Select candidates. Must be pure and deterministic for a given input.
+	 * Returns an empty array when nothing qualifies. Units already in
+	 * `input.view.evicted` must not be returned.
+	 */
+	select(input: PolicyInput): ReadonlyArray<EvictionCandidate>;
+}
+
+/** Materialized selection: markers rendered, tokens estimated, ready to become a ledger entry. */
+export interface EvictionPlan {
+	policyId: WorkingSetPolicyId;
+	items: ReadonlyArray<EvictedItem>;
+	tokensBefore: number;
+	tokensAfter: number;
+}
+
+/** Fields the caller adds when appending the plan as a ledger entry. */
+export type ContextEvictionFields = Omit<ContextEvictionEntry, "turnId" | "parentTurnId" | "timestamp">;
+export type ContextRecallFields = Omit<ContextRecallEntry, "turnId" | "parentTurnId" | "timestamp">;
+
+/** Typed failure for recall by ref. `recallErrorMessage` lists the refs that are evicted beside it. */
+export type RecallError =
+	| { kind: "not_on_active_path"; ref: string }
+	| { kind: "not_evicted"; ref: string }
+	| { kind: "invalid_ref"; ref: string };
+
+export interface RecallResult {
+	ref: WorkingSetRef;
+	/** The ledger entry whose body is readmitted. */
+	entry: SessionEntry;
+	/** Exact original body as the projection would have rendered it before eviction. */
+	body: string;
+	tokens: number;
+	/** Present when the original result was offloaded; recall returns the pointer, never the file. */
+	offloadPath?: string;
+}

package/src/domains/context/working-set/defaults.ts

@@ -0,0 +1,28 @@
+/**
+ * Working-set settings: user-visible defaults. The structural type lives in
+ * `src/core/defaults.ts` beside the rest of the settings tree so core stays
+ * free of a backward domain dependency; this module pairs it with the value
+ * the DEFAULT_SETTINGS tree and the engine read at runtime.
+ *
+ * `structural-v1` is the default: typed path-keyed rules first, the age rule
+ * last and batched to `target`. On the reproducible 24-trace procedural grid,
+ * it meets the recorded default rule at 32k, 64k, and 128k: retention is no
+ * lower than `age-horizon`, precision is higher than random, and the target
+ * stop remains active above 32k. `age-horizon` stays available as the exact
+ * pre-layer selection recorded through the ledger.
+ */
+
+import type { WorkingSetSettings } from "../../../core/defaults.js";
+
+export type { WorkingSetPolicyId, WorkingSetSettings } from "../../../core/defaults.js";
+
+export const DEFAULT_WORKING_SET_SETTINGS: WorkingSetSettings = {
+	enabled: true,
+	policy: "structural-v1",
+	target: 0.6,
+	protectLastTurns: 6,
+	// The procedural floor sweep found marker break-even near 50 tokens. A zero
+	// floor saved only 0.167 summaries at 64k and none at 128k while reducing
+	// covered retention by 0.0076 and 0.0237. Keep 200 as the churn guard.
+	minEvictableTokens: 200,
+};

package/src/domains/context/working-set/engine.ts

@@ -0,0 +1,203 @@
+/**
+ * Turn a policy's selection into something the session can append.
+ *
+ * `planEviction` is the whole decision: it asks the policy what should leave,
+ * materializes each candidate into an `EvictedItem` (marker rendered, tokens
+ * measured), and prices the result against the projection the model will
+ * actually receive. It writes nothing and calls no model, so the live engine
+ * and the replay-lite runner drive it identically.
+ *
+ * `buildEvictionFields` is the boring half: the plan plus the trigger facts,
+ * shaped as the ledger entry minus the three fields the session owns
+ * (`turnId`, `parentTurnId`, `timestamp`).
+ */
+
+import type { EvictedItem, SessionEntry } from "../../session/entries.js";
+import type {
+	ContextEvictionFields,
+	EvictedState,
+	EvictionCandidate,
+	EvictionPlan,
+	EvictionTrigger,
+	PolicyInput,
+	WorkingSetPolicy,
+	WorkingSetView,
+} from "./contract.js";
+import { refKey } from "./fold.js";
+import { renderMarker } from "./marker.js";
+import { callPathsByToolCallId } from "./path-index.js";
+import { hasThinking, offloadPathOf, primaryPathOf, toolResultPayload, toolResultText } from "./payload.js";
+import { projectWorkingSet } from "./project.js";
+
+/** Paths of the tool calls whose results may be evicted: `callPathsByToolCallId` over the policy input. */
+export type CallPaths = ReadonlyMap<string, string>;
+const NO_CALL_PATHS: CallPaths = new Map();
+
+/**
+ * The event has no turnId until `session.appendEntry` gives it one, and the
+ * projection reads only `reason` and `marker`, so plan-time states carry this
+ * placeholder rather than a fabricated id.
+ */
+const PENDING_EVENT_TURN_ID = "";
+
+/**
+ * The stub that replaces this unit's body, or null when there is nothing to
+ * evict. Thinking eviction renders no marker at all: the reasoning simply
+ * stops being replayed.
+ */
+function markerFor(entry: SessionEntry, candidate: EvictionCandidate, callPaths: CallPaths): string | null {
+	if (entry.kind !== "message") return null;
+	if (entry.role === "assistant") return hasThinking(entry.payload) ? "" : null;
+	if (entry.role !== "tool_result") return null;
+	const payload = toolResultPayload(entry.payload);
+	const toolCallId = typeof payload.obj.toolCallId === "string" ? payload.obj.toolCallId : undefined;
+	return renderMarker({
+		ref: candidate.ref,
+		reason: candidate.reason,
+		by: candidate.by,
+		toolName: payload.toolName,
+		text: toolResultText(payload.result),
+		offloadPath: offloadPathOf(payload),
+		path: primaryPathOf(payload) ?? (toolCallId === undefined ? undefined : callPaths.get(toolCallId)),
+	});
+}
+
+function pendingState(candidate: EvictionCandidate, marker: string, policyId: string): EvictedState {
+	return {
+		reason: candidate.reason,
+		marker,
+		...(candidate.by === undefined ? {} : { by: candidate.by }),
+		tokensFreed: 0,
+		evictedAtTurnId: PENDING_EVENT_TURN_ID,
+		policyId,
+	};
+}
+
+/** A view holding exactly one item, for pricing that item on its own. */
+function soloView(key: string, state: EvictedState): WorkingSetView {
+	return {
+		evicted: new Map([[key, state]]),
+		// Zero events: pricing one body must not also stamp usage invalidation,
+		// which would put the cost of a different mechanism in this item's total.
+		evictionEvents: 0,
+		itemsEvicted: 1,
+		recalls: 0,
+		lastPolicyId: null,
+		lastEvictionTurnId: null,
+	};
+}
+
+/**
+ * The view this plan would produce. `evictionEvents` and `lastEvictionTurnId`
+ * stay where they were on purpose: both totals are then measured under the same
+ * usage-invalidation state, so `tokensBefore - tokensAfter` is exactly the
+ * bodies this event removes and nothing else.
+ */
+function viewWithItems(view: WorkingSetView, items: ReadonlyArray<EvictedItem>, policyId: string): WorkingSetView {
+	const evicted = new Map(view.evicted);
+	for (const item of items) {
+		evicted.set(refKey(item.ref), {
+			reason: item.reason,
+			marker: item.marker,
+			...(item.by === undefined ? {} : { by: item.by }),
+			tokensFreed: item.tokensFreed,
+			evictedAtTurnId: PENDING_EVENT_TURN_ID,
+			policyId,
+		});
+	}
+	return { ...view, evicted, itemsEvicted: view.itemsEvicted + items.length };
+}
+
+function sumTokens(entries: ReadonlyArray<SessionEntry>, estimate: (entry: SessionEntry) => number): number {
+	let total = 0;
+	for (const entry of entries) total += estimate(entry);
+	return total;
+}
+
+/**
+ * What one candidate takes out of the working set: the entry as it stands now
+ * minus the entry as the projection would render it. Zero when the candidate
+ * does not apply to the entry, and never negative, because a marker longer than
+ * the body it replaces is a bad trade, not a negative saving.
+ *
+ * Exported so a policy can do headroom arithmetic (`structural-v1` rung 6 needs
+ * to know when to stop) against the same numbers `planEviction` will record.
+ * A policy that priced evictions its own way would report headroom the ledger
+ * then contradicts. Pass the same `callPaths` the plan will use, or the marker
+ * priced here is a few bytes shorter than the one recorded.
+ */
+export function tokensFreedByEviction(
+	estimateTokens: (entry: SessionEntry) => number,
+	entry: SessionEntry,
+	candidate: EvictionCandidate,
+	callPaths: CallPaths = NO_CALL_PATHS,
+): number {
+	const marker = markerFor(entry, candidate, callPaths);
+	if (marker === null) return 0;
+	const key = refKey(candidate.ref);
+	const projected = projectWorkingSet([entry], soloView(key, pendingState(candidate, marker, "")))[0] ?? entry;
+	return Math.max(0, estimateTokens(entry) - estimateTokens(projected));
+}
+
+export function planEviction(policy: WorkingSetPolicy, input: PolicyInput): EvictionPlan | null {
+	const candidates = policy.select(input);
+	if (candidates.length === 0) return null;
+
+	const byTurnId = new Map<string, SessionEntry>();
+	for (const entry of input.entries) byTurnId.set(entry.turnId, entry);
+	const callPaths = callPathsByToolCallId(input.entries);
+
+	const items: EvictedItem[] = [];
+	const claimed = new Set<string>();
+	for (const candidate of candidates) {
+		const key = refKey(candidate.ref);
+		// A policy is contractually forbidden from returning a unit that is
+		// already out, and a duplicate inside one selection would double-count
+		// the tokens it frees. Both are cheap to refuse here.
+		if (input.view.evicted.has(key) || claimed.has(key)) continue;
+		const entry = byTurnId.get(key);
+		if (entry === undefined) continue;
+		const marker = markerFor(entry, candidate, callPaths);
+		if (marker === null) continue;
+		// A marker at least as long as the body it replaces is a cold turn bought
+		// for nothing, whatever the policy's reason. Refused here so no policy can
+		// record an eviction that freed nothing.
+		const tokensFreed = tokensFreedByEviction(input.estimateTokens, entry, candidate, callPaths);
+		if (tokensFreed <= 0) continue;
+		claimed.add(key);
+		items.push({
+			ref: candidate.ref,
+			reason: candidate.reason,
+			tokensFreed,
+			marker,
+			...(candidate.by === undefined ? {} : { by: candidate.by }),
+		});
+	}
+	if (items.length === 0) return null;
+
+	return {
+		policyId: policy.id,
+		items,
+		tokensBefore: sumTokens(projectWorkingSet(input.entries, input.view), input.estimateTokens),
+		tokensAfter: sumTokens(
+			projectWorkingSet(input.entries, viewWithItems(input.view, items, policy.id)),
+			input.estimateTokens,
+		),
+	};
+}
+
+export function buildEvictionFields(
+	plan: EvictionPlan,
+	meta: { trigger: EvictionTrigger; pressureBefore: number | null; snapshotIdBefore: string | null },
+): ContextEvictionFields {
+	return {
+		kind: "contextEviction",
+		policyId: plan.policyId,
+		trigger: meta.trigger,
+		evicted: plan.items,
+		tokensBefore: plan.tokensBefore,
+		tokensAfter: plan.tokensAfter,
+		pressureBefore: meta.pressureBefore,
+		snapshotIdBefore: meta.snapshotIdBefore,
+	};
+}

package/src/domains/context/working-set/fold.ts

@@ -0,0 +1,62 @@
+/**
+ * Fold the working-set ledger records on the active path into a view.
+ *
+ * Pure over entries. The active path is selected here, through
+ * `filterEntriesToActivePath`, so every consumer (live projection, recall,
+ * overlay, replay-lite) shares the same #94 discipline: after a `/tree` switch
+ * the raw file still holds abandoned turns, and an eviction recorded on an
+ * abandoned branch must not project onto the live one. Forks inherit the view
+ * of their shared prefix for the same reason compaction summaries do.
+ */
+
+import type { SessionEntry } from "../../session/entries.js";
+import { filterEntriesToActivePath } from "../../session/tree/active-path.js";
+import type { EvictedState, WorkingSetRef, WorkingSetView } from "./contract.js";
+
+/** Ref keys index `WorkingSetView.evicted`. Today a key is the entry turnId. */
+export function refKey(ref: WorkingSetRef): string {
+	return ref.entry;
+}
+
+export function parseRefKey(key: string): WorkingSetRef | null {
+	const trimmed = key.trim();
+	if (trimmed.length === 0 || /\s/.test(trimmed)) return null;
+	return { entry: trimmed };
+}
+
+export function foldWorkingSet(entries: ReadonlyArray<SessionEntry>, activeLeafTurnId?: string): WorkingSetView {
+	const active = filterEntriesToActivePath(entries, activeLeafTurnId);
+	const evicted = new Map<string, EvictedState>();
+	let evictionEvents = 0;
+	let itemsEvicted = 0;
+	let recalls = 0;
+	let lastPolicyId: string | null = null;
+	let lastEvictionTurnId: string | null = null;
+	for (const entry of active) {
+		if (entry.kind === "contextEviction") {
+			evictionEvents += 1;
+			lastPolicyId = entry.policyId;
+			lastEvictionTurnId = entry.turnId;
+			for (const item of entry.evicted) {
+				itemsEvicted += 1;
+				evicted.set(refKey(item.ref), {
+					reason: item.reason,
+					marker: item.marker,
+					...(item.by === undefined ? {} : { by: item.by }),
+					tokensFreed: item.tokensFreed,
+					evictedAtTurnId: entry.turnId,
+					policyId: entry.policyId,
+				});
+			}
+			continue;
+		}
+		// A recall does not un-evict. The recalled body rides the recall tool
+		// result at the tail of the working set, which is where the model asked
+		// for it and where it costs no cold prefix; readmitting it at the
+		// original position would duplicate the bytes and invalidate the cache
+		// for everything after it. The marker stays, byte-stable, and a second
+		// recall of the same ref is the churn signal.
+		if (entry.kind === "contextRecall") recalls += 1;
+	}
+	return { evicted, evictionEvents, itemsEvicted, recalls, lastPolicyId, lastEvictionTurnId };
+}

package/src/domains/context/working-set/horizon.ts

@@ -0,0 +1,38 @@
+/**
+ * The protection horizon: where the recent, untouchable window begins.
+ *
+ * Both policies and every protection predicate answer "is this entry inside the
+ * last `protectLastTurns` turns" the same way, so the arithmetic lives here
+ * once. It is the same cutoff `maskStaleObservations` used before this layer
+ * existed, which is what keeps `age-horizon` selection-identical to the
+ * destructive stage it replaced.
+ */
+
+import type { SessionEntry } from "../../session/entries.js";
+
+/**
+ * What starts a turn, in the sense the protection horizon counts. A local `!`
+ * bash execution and a branch summary both open a new stretch of work the same
+ * way an operator message does.
+ */
+export function isTurnStart(entry: SessionEntry): boolean {
+	if (entry.kind === "bashExecution" || entry.kind === "branchSummary") return true;
+	return entry.kind === "message" && entry.role === "user";
+}
+
+/**
+ * Index of the first protected entry: walk back until `protectLastTurns` turn
+ * starts have been seen. Entries before it are candidates, entries from it on
+ * are the recent window nothing touches.
+ */
+export function protectionCutoffIndex(entries: ReadonlyArray<SessionEntry>, protectLastTurns: number): number {
+	const horizon = Math.max(1, Math.floor(protectLastTurns));
+	let seen = 0;
+	for (let i = entries.length - 1; i >= 0; i -= 1) {
+		const entry = entries[i];
+		if (!entry || !isTurnStart(entry)) continue;
+		seen += 1;
+		if (seen >= horizon) return i;
+	}
+	return 0;
+}

package/src/domains/context/working-set/marker.ts

@@ -0,0 +1,103 @@
+/**
+ * The one-line stub the projection renders in place of an evicted tool-result
+ * body.
+ *
+ * Byte-stable by construction: same input, same bytes, forever. No timestamp,
+ * no counter, no `Date.now()`. Two reasons. The marker is persisted inside the
+ * `contextEviction` entry and replayed by the projection on every request, so a
+ * marker that changed between renders would invalidate the prompt cache on a
+ * turn that evicted nothing new. And replay-lite reruns the same policy over
+ * recorded ledgers; a marker carrying wall-clock state would make two runs of
+ * the same trace disagree.
+ *
+ * The field order is fixed (ref, reason, by, tool, path, size, offload,
+ * recall, then the body tail) so a diff between two markers is readable and so
+ * a model reading many of them sees the same shape every time. Undefined
+ * fields are omitted rather than rendered empty. `recall` spells out the exact
+ * tool call that brings the body back, which is the only affordance the model
+ * has once the body is gone.
+ *
+ * The body tail is `preview` for every reason but one. A `failure_resolved`
+ * eviction renders `first_line` instead: failures are evidence, and the line
+ * that says what failed is the part worth a marker's tokens, where a preview
+ * of a stack trace is not.
+ */
+
+import { formatSize } from "../../../engine/truncate.js";
+import type { EvictionReason, WorkingSetRef } from "./contract.js";
+
+/** Characters of the original body the marker keeps as a preview. */
+const PREVIEW_LIMIT = 120;
+
+export interface MarkerInput {
+	ref: WorkingSetRef;
+	reason: EvictionReason;
+	/** Ref key of the entry that superseded or resolved this one, when the reason names one. */
+	by?: string | undefined;
+	toolName: string;
+	/** The body leaving the working set; drives size and preview. */
+	text: string;
+	/** Set when the original result was offloaded to scratch. Replaces the preview. */
+	offloadPath?: string | undefined;
+	/** Primary file the result was about, when the payload names exactly one. */
+	path?: string | undefined;
+}
+
+/** Lines as `split(/\r\n|\r|\n/)` would count them, without materializing them. */
+function lineCount(text: string): number {
+	if (text.length === 0) return 0;
+	let count = 1;
+	for (let index = 0; index < text.length; index += 1) {
+		const code = text.charCodeAt(index);
+		if (code === 10 || (code === 13 && text.charCodeAt(index + 1) !== 10)) count += 1;
+	}
+	return count;
+}
+
+/**
+ * First `PREVIEW_LIMIT` characters with whitespace collapsed to single spaces
+ * and double quotes escaped, so the preview never breaks the quoted field or
+ * spills onto a second line. Bounded: the body is scanned only as far as the
+ * preview reaches, because the marker is priced once per candidate on every
+ * eviction and a body-length collapse was most of that price.
+ */
+function preview(text: string): string {
+	let out = "";
+	let pendingSpace = false;
+	for (const char of text) {
+		if (/\s/.test(char)) {
+			pendingSpace = out.length > 0;
+			continue;
+		}
+		if (pendingSpace) out += " ";
+		pendingSpace = false;
+		out += char;
+		if (out.length >= PREVIEW_LIMIT) break;
+	}
+	return out.slice(0, PREVIEW_LIMIT).replace(/"/g, '\\"');
+}
+
+/** The first line that says anything, bounded and escaped like a preview. */
+function firstLine(text: string): string {
+	const line = /[^\r\n]*\S[^\r\n]*/.exec(text)?.[0] ?? "";
+	return line.trim().slice(0, PREVIEW_LIMIT).replace(/"/g, '\\"');
+}
+
+export function renderMarker(input: MarkerInput): string {
+	const ref = input.ref.entry;
+	const fields: string[] = [`ref=${ref}`, `reason=${input.reason}`];
+	if (input.by !== undefined) fields.push(`by=${input.by}`);
+	fields.push(`tool=${input.toolName}`);
+	if (input.path !== undefined) fields.push(`path=${input.path}`);
+	fields.push(`size=${lineCount(input.text)} lines/${formatSize(Buffer.byteLength(input.text, "utf8"))}`);
+	if (input.offloadPath !== undefined) fields.push(`offload=${input.offloadPath}`);
+	fields.push(`recall=context(scope="recall", ref="${ref}")`);
+	// An offloaded body is one `read` away at a stable path; a preview of it
+	// would spend tokens repeating what the pointer already promises.
+	if (input.offloadPath === undefined) {
+		const failed = input.reason === "failure_resolved";
+		const tail = failed ? firstLine(input.text) : preview(input.text);
+		if (tail.length > 0) fields.push(`${failed ? "first_line" : "preview"}="${tail}"`);
+	}
+	return `[evicted ${fields.join(" ")}]`;
+}