@iowarp/clio-coder 0.3.3 → 0.3.4

package/src/domains/context/working-set/policies/structural.ts

@@ -0,0 +1,160 @@
+/**
+ * `structural-v1`: evict what the session has structurally finished with.
+ *
+ * The age rule asks how old a result is. This one asks what happened to it
+ * since: was the file rewritten, did a later read cover the same lines, did the
+ * failure get resolved, has the listing been walked. Those are facts the ledger
+ * already records, and they are the facts a human would use to decide what is
+ * still worth carrying. Age is the last rung, not the first, and it only runs
+ * when the structural rungs did not free enough.
+ *
+ * Rule order is the policy. Each rung emits candidates newest-first, every
+ * candidate passes `isProtected`, and no unit is claimed twice, so a read that
+ * is both stale and superseded is evicted for the reason that came first and
+ * carries the ref that explains it. Rungs 1 to 5 are unconditional: redundant
+ * content is free to drop, whatever the pressure. Rung 6 is the only one that
+ * looks at token counts, and it stops the moment the projection reaches
+ * `target`.
+ *
+ * Deterministic by construction: the index is a pure function of the entries,
+ * every loop runs in index order, and nothing here reads a clock, a size
+ * ranking, or a recency score.
+ */
+
+import type { EvictionCandidate, EvictionReason, PolicyInput, WorkingSetPolicy } from "../contract.js";
+import { tokensFreedByEviction } from "../engine.js";
+import { protectionCutoffIndex } from "../horizon.js";
+import { buildPathIndex, callPathsByToolCallId, covers, type PathIndex, type PathObservation } from "../path-index.js";
+import { hasThinking } from "../payload.js";
+import { findLaterSuccess, isProtected } from "../protect.js";
+
+/** Ops that observe content rather than change it. */
+const READ_CLASS = new Set<PathObservation["op"]>(["read", "grep", "find", "ls", "code_nav"]);
+const MUTATING = new Set<PathObservation["op"]>(["write", "edit"]);
+
+/**
+ * The mutation that invalidated this observation: the first successful one
+ * after it. A failed edit (`oldText not found`, permission denied) changed
+ * nothing, and the read it was aimed at is exactly what the model needs to fix
+ * the edit.
+ */
+function firstMutationAfter(observation: PathObservation, index: PathIndex): PathObservation | null {
+	for (const other of index.byPath.get(observation.path) ?? []) {
+		if (other.entryIndex > observation.entryIndex && MUTATING.has(other.op) && !other.isError) return other;
+	}
+	return null;
+}
+
+/** The most recent later read of the same file that covers this one's lines. */
+function lastCoveringRead(observation: PathObservation, index: PathIndex): PathObservation | null {
+	let found: PathObservation | null = null;
+	for (const other of index.byPath.get(observation.path) ?? []) {
+		if (other.entryIndex <= observation.entryIndex || other.op !== "read" || other.isError) continue;
+		if (covers(other.range, observation.range)) found = other;
+	}
+	return found;
+}
+
+/** Every surfaced path went on to be read. A path nobody read is an unread path. */
+function isListingConsumed(observation: PathObservation, index: PathIndex): boolean {
+	if (observation.surfaced.length === 0) return false;
+	for (const path of observation.surfaced) {
+		const readLater = (index.byPath.get(path) ?? []).some(
+			(other) => other.op === "read" && !other.isError && other.entryIndex > observation.entryIndex,
+		);
+		if (!readLater) return false;
+	}
+	return true;
+}
+
+export const structuralPolicy: WorkingSetPolicy = {
+	id: "structural-v1",
+	select(input: PolicyInput): ReadonlyArray<EvictionCandidate> {
+		const { entries, view, settings, pressure, estimateTokens } = input;
+		const index = buildPathIndex(entries, { cwd: input.cwd });
+		const callPaths = callPathsByToolCallId(entries);
+		const cutoffIndex = protectionCutoffIndex(entries, settings.protectLastTurns);
+		const candidates: EvictionCandidate[] = [];
+		const claimed = new Set<string>();
+		let freed = 0;
+
+		const entryIndexOf = new Map<string, number>();
+		for (let i = 0; i < entries.length; i += 1) {
+			const entry = entries[i];
+			if (entry !== undefined) entryIndexOf.set(entry.turnId, i);
+		}
+
+		const emit = (turnId: string, reason: EvictionReason, by?: string): boolean => {
+			if (claimed.has(turnId) || view.evicted.has(turnId)) return false;
+			const entryIndex = entryIndexOf.get(turnId);
+			if (entryIndex === undefined) return false;
+			const entry = entries[entryIndex];
+			if (entry === undefined) return false;
+			if (isProtected(entry, { entryIndex, cutoffIndex, input, index })) return false;
+			const candidate: EvictionCandidate = { ref: { entry: turnId }, reason, ...(by === undefined ? {} : { by }) };
+			claimed.add(turnId);
+			candidates.push(candidate);
+			freed += tokensFreedByEviction(estimateTokens, entry, candidate, callPaths);
+			return true;
+		};
+
+		// Newest-first within every rung, for the cost reason in charter 4.6:
+		// evicting the youngest safe unit keeps the cold region after the
+		// eviction point small, so the turn that pays for the event pays least.
+		const newestFirst = [...index.observations].reverse();
+
+		// 1. The file changed under it. Whatever the body said is now a claim
+		//    about a file that no longer exists in that form.
+		for (const observation of newestFirst) {
+			if (!READ_CLASS.has(observation.op) || observation.path.length === 0) continue;
+			const mutation = firstMutationAfter(observation, index);
+			if (mutation !== null) emit(observation.ref.entry, "stale_after_mutation", mutation.ref.entry);
+		}
+
+		// 2. The agent asked for the same lines again. It already decided this
+		//    content was worth re-fetching, and the newer copy is the live one.
+		for (const observation of newestFirst) {
+			if (observation.op !== "read" || observation.path.length === 0) continue;
+			const superseding = lastCoveringRead(observation, index);
+			if (superseding !== null) emit(observation.ref.entry, "superseded_read", superseding.ref.entry);
+		}
+
+		// 3. The failure was resolved. The marker keeps its first line, because
+		//    a failure that happened is evidence even once it is fixed.
+		for (const observation of newestFirst) {
+			if (!observation.isError) continue;
+			const success = findLaterSuccess(observation, index);
+			if (success !== null) emit(observation.ref.entry, "failure_resolved", success.ref.entry);
+		}
+
+		// 4. The listing has been walked. One surfaced path still unread and it
+		//    stays: that is the path the agent comes back to.
+		for (const observation of newestFirst) {
+			if (isListingConsumed(observation, index)) emit(observation.ref.entry, "listing_consumed");
+		}
+
+		// 5. Reasoning from a closed turn, the same rule age-horizon applies.
+		for (let i = cutoffIndex - 1; i >= 0; i -= 1) {
+			const entry = entries[i];
+			if (entry?.kind !== "message" || entry.role !== "assistant") continue;
+			if (hasThinking(entry.payload)) emit(entry.turnId, "thinking_turn_closed");
+		}
+
+		// 6. Age, and only under pressure. Everything above is redundancy the
+		//    session can lose for free; this rung loses content that is still
+		//    good, so it runs only when the projection is still over threshold
+		//    and stops the moment it reaches target.
+		const window = pressure.contextWindow;
+		if (window <= 0) return candidates;
+		let projected = pressure.tokens - freed;
+		if (projected <= pressure.threshold * window) return candidates;
+		const targetTokens = pressure.target * window;
+		for (let i = cutoffIndex - 1; i >= 0 && projected > targetTokens; i -= 1) {
+			const entry = entries[i];
+			if (entry?.kind !== "message" || entry.role !== "tool_result") continue;
+			const before = freed;
+			if (emit(entry.turnId, "age_horizon")) projected -= freed - before;
+		}
+		return candidates;
+	},
+};

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

@@ -0,0 +1,132 @@
+/**
+ * Apply a `WorkingSetView` to a ledger slice as an in-memory projection.
+ *
+ * This is the whole point of the layer: the ledger keeps every byte the tools
+ * produced, and the model sees a narrower view of it. Nothing here writes, and
+ * nothing here decides what leaves; `fold.ts` says what is out and this module
+ * renders that decision onto the entries the replay builder consumes.
+ *
+ * Pure and idempotent. Projecting an already-projected slice reproduces it
+ * byte for byte, because the marker comes from the ledger entry rather than
+ * from the body being replaced. Entries the view does not name are returned by
+ * reference, and a named entry is a shallow copy with a new payload: nothing
+ * below the payload is ever mutated, so a deep clone of the body about to be
+ * replaced would only cost the pricing loop the body's size.
+ *
+ * Callers may pass raw ledger entries: only entries whose `turnId` is a key in
+ * `view.evicted` change, and the view was already narrowed to the active path
+ * by the fold, so an eviction recorded on an abandoned branch cannot reach a
+ * live one (issue #94).
+ */
+
+import type { MessageEntry, SessionEntry } from "../../session/entries.js";
+import type { EvictedState, WorkingSetView } from "./contract.js";
+import { hasThinking, isRecord, toolResultPayload, withoutThinkingBlocks } from "./payload.js";
+
+/**
+ * Replace the observation body with its marker. Tool pairing (`toolCallId`,
+ * `toolName`) and `details` survive untouched, so replay still matches the
+ * result to its call and the renderer still knows what the call was; only the
+ * text the model reads changes. The `workingSet` stamp on `details` is how a
+ * reader tells a marker from a genuinely tiny tool result.
+ */
+function projectToolResult(entry: MessageEntry, state: EvictedState): MessageEntry {
+	const next = { ...entry };
+	const { obj, result } = toolResultPayload(next.payload);
+	const details = isRecord(result) && isRecord(result.details) ? result.details : {};
+	next.payload = {
+		...obj,
+		result: {
+			content: [{ type: "text", text: state.marker }],
+			details: {
+				...details,
+				workingSet: { evicted: true, reason: state.reason, ref: entry.turnId },
+			},
+		},
+		output: undefined,
+		out: undefined,
+		content: undefined,
+	};
+	return next;
+}
+
+/**
+ * Drop reasoning from a closed turn. No marker replaces it: thinking is
+ * model-internal, the Anthropic API discards it after every turn anyway, and a
+ * marker would spend tokens to say that something the model cannot act on is
+ * gone. Both persisted shapes go: `thinking` content blocks and the
+ * payload-level string the local engine adapters write.
+ *
+ * A turn that was nothing but reasoning keeps it. Projected, it would reach
+ * the provider as an assistant message with no content, or vanish from the
+ * replay and leave two user messages adjacent; either is worse than the
+ * tokens. `planEviction` then prices such a turn at zero and records nothing.
+ */
+function projectAssistant(entry: MessageEntry): MessageEntry {
+	const obj = isRecord(entry.payload) ? entry.payload : null;
+	if (obj === null || !hasThinking(obj)) return entry;
+	const content = withoutThinkingBlocks(obj.content);
+	if (!hasVisibleContent(obj, content)) return entry;
+	const next = { ...entry };
+	next.payload = {
+		...obj,
+		...(content !== undefined ? { content } : {}),
+		thinking: undefined,
+	};
+	return next;
+}
+
+/** What the replay builder would still send: a payload-level text or at least one surviving block. */
+function hasVisibleContent(obj: Record<string, unknown>, content: unknown[] | undefined): boolean {
+	if (typeof obj.text === "string" && obj.text.length > 0) return true;
+	return content !== undefined && content.length > 0;
+}
+
+/**
+ * Usage recorded before the projection existed described a longer prompt than
+ * the model will now receive. `calculateContextTokens` anchors on the newest
+ * assistant usage it trusts, so leaving those anchors in place would report the
+ * pre-eviction size forever and the pressure estimator would never see the
+ * space the eviction freed. Mirrors `invalidateUsage()` in
+ * mask-observations.ts, bounded to the entries that precede the event.
+ */
+function invalidateUsage(entry: SessionEntry): SessionEntry {
+	if (entry.kind !== "message" || entry.role !== "assistant") return entry;
+	const obj = isRecord(entry.payload) ? entry.payload : null;
+	if (obj === null || obj.contextUsageInvalidated === true) return entry;
+	const next = { ...entry };
+	next.payload = { ...obj, contextUsageInvalidated: true };
+	return next;
+}
+
+/**
+ * Index of the newest eviction event within this slice. An event the slice does
+ * not contain (a caller that truncated before it) is treated as later than
+ * everything here: every usage anchor in the slice predates the projection.
+ */
+function eventIndex(entries: ReadonlyArray<SessionEntry>, lastEvictionTurnId: string | null): number {
+	if (lastEvictionTurnId === null) return entries.length;
+	const index = entries.findIndex((entry) => entry.turnId === lastEvictionTurnId);
+	return index < 0 ? entries.length : index;
+}
+
+export function projectWorkingSet(entries: ReadonlyArray<SessionEntry>, view: WorkingSetView): SessionEntry[] {
+	if (view.evicted.size === 0 && view.evictionEvents === 0) return [...entries];
+	const cutoff = view.evictionEvents > 0 ? eventIndex(entries, view.lastEvictionTurnId) : -1;
+	const out: SessionEntry[] = [];
+	for (let index = 0; index < entries.length; index += 1) {
+		const entry = entries[index];
+		if (entry === undefined) continue;
+		let next = entry;
+		if (entry.kind === "message") {
+			const state = view.evicted.get(entry.turnId);
+			if (state !== undefined) {
+				if (entry.role === "tool_result") next = projectToolResult(entry, state);
+				else if (entry.role === "assistant") next = projectAssistant(entry);
+			}
+		}
+		if (index < cutoff) next = invalidateUsage(next);
+		out.push(next);
+	}
+	return out;
+}

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

@@ -0,0 +1,109 @@
+/**
+ * Protection predicates: what the working set never gives up, whatever a rule
+ * concludes.
+ *
+ * These run before every rule and are absolute. A policy is allowed to be
+ * wrong about relevance (that is what the replay table measures); it is not
+ * allowed to drop the operator's words, the last few turns of work, a failure
+ * nobody has resolved, or a mutation the current turn is still standing on.
+ * Charter 4.5 lists them; this module is that list, and `structural.ts` calls
+ * it on every candidate rather than reimplementing any of it.
+ *
+ * Pure over the entry, the index, and the policy input.
+ */
+
+import type { SessionEntry } from "../../session/entries.js";
+import type { PolicyInput } from "./contract.js";
+import type { PathIndex, PathObservation } from "./path-index.js";
+import { hasLegacyCompactionMarker, isRecord, toolResultBodyTokens } from "./payload.js";
+
+export interface ProtectionContext {
+	entryIndex: number;
+	/** First entry of the protected recent window, from `protectionCutoffIndex`. */
+	cutoffIndex: number;
+	input: PolicyInput;
+	index: PathIndex;
+}
+
+/** Ops whose identity is the file they touched, so a retry on the same path counts as the same call. */
+const PATH_IDENTIFIED_OPS = new Set(["read", "grep", "find"]);
+
+function isBlockedResult(payload: unknown): boolean {
+	if (!isRecord(payload)) return false;
+	// The registry's admission verdict, persisted by turn-persistence. A call
+	// the safety rails refused is a decision the session made, not an
+	// observation it can re-fetch.
+	return payload.outcome === "blocked" || typeof payload.blockReason === "string";
+}
+
+function isErrorResult(payload: unknown): boolean {
+	if (!isRecord(payload)) return false;
+	return payload.isError === true || payload.error === true;
+}
+
+/**
+ * The later call that resolved this failure: same tool with byte-identical
+ * arguments, or, for the path-identified ops, the same file by any route. Null
+ * when nothing after it succeeded, which is what keeps the failure protected.
+ * A refused call is not a success: the safety rails returned a verdict, not
+ * the observation the failure was trying to make.
+ *
+ * Shared with `structural.ts` rung 3 on purpose: the rule that evicts a
+ * resolved failure and the predicate that protects an unresolved one must
+ * answer the same question, or a failure could be both.
+ */
+export function findLaterSuccess(observation: PathObservation, index: PathIndex): PathObservation | null {
+	for (const candidate of index.observations) {
+		if (candidate.entryIndex <= observation.entryIndex || candidate.isError || candidate.isBlocked) continue;
+		if (candidate.toolName === observation.toolName && observation.argsKey.length > 0) {
+			if (candidate.argsKey === observation.argsKey) return candidate;
+		}
+		if (
+			PATH_IDENTIFIED_OPS.has(observation.op) &&
+			candidate.op === observation.op &&
+			observation.path.length > 0 &&
+			candidate.path === observation.path
+		) {
+			return candidate;
+		}
+	}
+	return null;
+}
+
+/** A write or edit the turn in flight is still standing on. */
+function isActiveTurnMutation(observation: PathObservation, index: PathIndex): boolean {
+	if (observation.op !== "write" && observation.op !== "edit") return false;
+	return observation.turnIndex >= index.turnCount;
+}
+
+export function isProtected(entry: SessionEntry, ctx: ProtectionContext): boolean {
+	// Only two things ever leave the working set: a tool result's body and an
+	// assistant turn's thinking. Everything else (operator words, summaries,
+	// skill activations, ledgers, worker runs, bash executions) is the session's
+	// own record of itself.
+	if (entry.kind !== "message") return true;
+	if (entry.role !== "tool_result" && entry.role !== "assistant") return true;
+
+	// The recent window is untouchable for both kinds.
+	if (ctx.entryIndex >= ctx.cutoffIndex) return true;
+	if (entry.role === "assistant") return false;
+
+	// The floor protects low-yield bodies from churn. The engine separately
+	// rejects any candidate whose marker would free zero or negative tokens, so
+	// this setting may stay above the literal marker break-even point. The floor
+	// is the body's size, not the payload's: details never reach the model.
+	if (toolResultBodyTokens(entry.payload) < ctx.input.settings.minEvictableTokens) return true;
+	// A body the legacy destructive stage already replaced has nothing left to evict.
+	if (hasLegacyCompactionMarker(entry.payload)) return true;
+	if (isBlockedResult(entry.payload)) return true;
+
+	const observation = ctx.index.byRef.get(entry.turnId);
+	// No observation means no way to ask whether a failure was resolved, so an
+	// unindexed failure stays. Everything else unindexed is an ordinary result
+	// the age rung may still take under pressure.
+	if (observation === undefined) return isErrorResult(entry.payload);
+
+	if (isActiveTurnMutation(observation, ctx.index)) return true;
+	if (observation.isError && findLaterSuccess(observation, ctx.index) === null) return true;
+	return false;
+}

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

@@ -0,0 +1,177 @@
+/**
+ * Exact recall by ref.
+ *
+ * A `contextEviction` entry removes a tool-result body from the projection
+ * and leaves a marker naming the ref. Recall is the reverse move: given a ref
+ * on the active path whose key the fold still lists as evicted, hand back the
+ * original body byte-exact and describe the `contextRecall` entry the caller
+ * appends. The ref stays evicted in the fold: the body rides the recall tool
+ * result at the tail of the working set, so the marker and the prefix cache
+ * are untouched and a repeat recall is the churn signal. Pure over entries:
+ * nothing here reads the session, writes the ledger, or calls a model.
+ *
+ * The body is read through the same `payload.ts` readers the projection and
+ * the marker use, so what recall returns is exactly what the model saw before
+ * eviction. No truncation happens here; the observation envelope applies the
+ * per-turn caps.
+ */
+
+import { ceilChars } from "../../session/context-accounting.js";
+import type { MessageEntry, SessionEntry } from "../../session/entries.js";
+import { filterEntriesToActivePath } from "../../session/tree/active-path.js";
+import {
+	type ContextRecallFields,
+	EMPTY_WORKING_SET_VIEW,
+	type RecallError,
+	type RecallResult,
+	type RecallTrigger,
+	type WorkingSetView,
+} from "./contract.js";
+import { parseRefKey, refKey } from "./fold.js";
+import { callPathsByToolCallId } from "./path-index.js";
+import { offloadPathOf, primaryPathOf, toolResultPayload, toolResultText } from "./payload.js";
+
+export type RecallOutcome = { ok: true; result: RecallResult } | { ok: false; error: RecallError };
+
+function isThinkingEntry(entry: SessionEntry): boolean {
+	return entry.kind === "message" && entry.role === "assistant";
+}
+
+function isToolResultEntry(entry: SessionEntry): entry is MessageEntry {
+	return entry.kind === "message" && entry.role === "tool_result";
+}
+
+export function resolveRecall(
+	entries: ReadonlyArray<SessionEntry>,
+	view: WorkingSetView,
+	ref: string,
+	activeLeafTurnId?: string,
+): RecallOutcome {
+	const parsed = parseRefKey(ref);
+	if (parsed === null) return { ok: false, error: { kind: "invalid_ref", ref } };
+	const key = refKey(parsed);
+	const active = filterEntriesToActivePath(entries, activeLeafTurnId);
+	const entry = active.find((candidate) => candidate.turnId === key);
+	if (entry === undefined) {
+		return { ok: false, error: { kind: "not_on_active_path", ref: key } };
+	}
+	// Thinking leaves the working set without a marker and is not recallable
+	// in this slice; `recallErrorMessage` names that case from the entry.
+	if (isThinkingEntry(entry) || !view.evicted.has(key) || !isToolResultEntry(entry)) {
+		return { ok: false, error: { kind: "not_evicted", ref: key } };
+	}
+	const payload = toolResultPayload(entry.payload);
+	const body = toolResultText(payload.result);
+	const offloadPath = offloadPathOf(payload);
+	return {
+		ok: true,
+		result: {
+			ref: parsed,
+			entry,
+			body,
+			tokens: ceilChars(body.length),
+			...(offloadPath !== undefined ? { offloadPath } : {}),
+		},
+	};
+}
+
+/**
+ * The turn a `contextRecall` entry parents onto: the newest message on the
+ * active path. Every recall caller needs this and they must agree, because a
+ * record anchored anywhere else folds onto the wrong branch and a `/tree`
+ * switch would then show a recall the branch never made.
+ */
+export function recallParentTurnId(entries: ReadonlyArray<SessionEntry>, activeLeafTurnId?: string): string | null {
+	const active = filterEntriesToActivePath(entries, activeLeafTurnId);
+	for (let i = active.length - 1; i >= 0; i -= 1) {
+		const candidate = active[i];
+		if (candidate?.kind === "message") return candidate.turnId;
+	}
+	return null;
+}
+
+export function buildRecallFields(
+	result: RecallResult,
+	meta: { trigger: RecallTrigger; toolCallId?: string },
+): ContextRecallFields {
+	return {
+		kind: "contextRecall",
+		ref: { entry: result.ref.entry },
+		trigger: meta.trigger,
+		tokensReadmitted: result.tokens,
+		...(meta.toolCallId !== undefined ? { toolCallId: meta.toolCallId } : {}),
+	};
+}
+
+/** Refs listed in a recall failure before the list is cut with an ellipsis. */
+const MAX_LISTED_REFS = 8;
+
+export interface RecallableRefListing {
+	/** Already-rendered `ref (tool path)` rows, bounded for prompt use. */
+	refs: string[];
+	/** Recallable refs omitted after the bounded prefix. */
+	remaining: number;
+}
+
+/**
+ * The refs a recall can actually bring back, so the next call can name one of
+ * them. Thinking refs are evicted too but are not recallable, so listing them
+ * would hand the caller a ref that fails for a different reason. A guessed
+ * "nearest" ref was tried first and dropped: over time-ordered ids a prefix
+ * match names an unrelated result, and the listing is what helps.
+ */
+export function recallableRefListing(entries: ReadonlyArray<SessionEntry>, view: WorkingSetView): RecallableRefListing {
+	const byTurnId = new Map<string, SessionEntry>();
+	for (const entry of entries) byTurnId.set(entry.turnId, entry);
+	const callPaths = callPathsByToolCallId(entries);
+	const refs: string[] = [];
+	for (const key of view.evicted.keys()) {
+		const entry = byTurnId.get(key);
+		if (entry === undefined || !isToolResultEntry(entry)) continue;
+		// After a summary compaction the markers before the cut are gone from
+		// the working set, so the listing is the only place the caller learns
+		// what a ref was. Tool and path are what it needs to pick one.
+		const payload = toolResultPayload(entry.payload);
+		const toolCallId = typeof payload.obj.toolCallId === "string" ? payload.obj.toolCallId : undefined;
+		const path = primaryPathOf(payload) ?? (toolCallId === undefined ? undefined : callPaths.get(toolCallId));
+		refs.push(`${key} (${payload.toolName}${path === undefined ? "" : ` ${path}`})`);
+	}
+	return {
+		refs: refs.slice(0, MAX_LISTED_REFS),
+		remaining: Math.max(0, refs.length - MAX_LISTED_REFS),
+	};
+}
+
+function recallableRefMessage(entries: ReadonlyArray<SessionEntry>, view: WorkingSetView): string {
+	const listing = recallableRefListing(entries, view);
+	if (listing.refs.length === 0) return "No recallable refs on the active path.";
+	const more = listing.remaining > 0 ? `, and ${listing.remaining} more` : "";
+	return `Recallable refs on the active path: ${listing.refs.join(", ")}${more}.`;
+}
+
+/**
+ * One-line operator/model-facing message for a recall failure. Says why an
+ * assistant turn is refused instead of calling it "not evicted", and ends with
+ * the refs that can be recalled. `entries` is the active path the view was
+ * folded over; without it the listing is empty.
+ */
+export function recallErrorMessage(
+	error: RecallError,
+	entries: ReadonlyArray<SessionEntry> = [],
+	view: WorkingSetView = EMPTY_WORKING_SET_VIEW,
+): string {
+	const listing = ` ${recallableRefMessage(entries, view)}`;
+	switch (error.kind) {
+		case "invalid_ref":
+			return `recall ref must be a single turnId without whitespace; got '${error.ref}'.`;
+		case "not_on_active_path":
+			return `ref ${error.ref} is not on the active path of this session (unknown or on an abandoned branch).${listing}`;
+		case "not_evicted": {
+			const entry = entries.find((candidate) => candidate.turnId === error.ref);
+			if (entry !== undefined && isThinkingEntry(entry)) {
+				return `ref ${error.ref} is an assistant turn; thinking is not recallable.${listing}`;
+			}
+			return `ref ${error.ref} is not evicted; its content is already in context.${listing}`;
+		}
+	}
+}