@iowarp/clio-coder 0.3.3 → 0.3.6

package/src/domains/context/project-metadata.ts

@@ -19,6 +19,7 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { parse as parseYaml } from "yaml";
+import { createTomlFileReader, type TomlFileReader, tomlTableAt } from "../../core/toml.js";
 
 /** Longest description worth carrying into a one-sentence identity line. */
 const MAX_DESCRIPTION_CHARS = 400;
@@ -39,7 +40,7 @@ interface MetadataFragment {
 	description?: string | null;
 }
 
-type MetadataReader = (cwd: string) => { file: string; fragment: MetadataFragment } | null;
+type MetadataReader = (cwd: string, tomlFiles: TomlFileReader) => { file: string; fragment: MetadataFragment } | null;
 
 function readText(cwd: string, relative: string): string | null {
 	try {
@@ -83,54 +84,6 @@ function jsonRecord(cwd: string, relative: string): Record<string, unknown> | nu
 	}
 }
 
-/**
- * One key from one TOML table, without a TOML parser.
- *
- * Deliberately narrow: it reads `key = "value"` (single-line, single- or
- * double-quoted) from the named top-level table and understands nothing else.
- * That is the entire shape `description` and `name` take in `pyproject.toml`
- * and `Cargo.toml`. A multi-line or otherwise exotic value reads as absent,
- * which costs a description and never produces a wrong one.
- */
-function tomlTableValue(raw: string, table: string, key: string): string | null {
-	const lines = raw.split(/\r?\n/u);
-	let inTable = false;
-	for (const line of lines) {
-		const trimmed = line.trim();
-		if (trimmed.startsWith("[")) {
-			inTable = trimmed === `[${table}]`;
-			continue;
-		}
-		if (!inTable) continue;
-		const match = /^([A-Za-z0-9_-]+)\s*=\s*(.*)$/u.exec(trimmed);
-		if (!match || match[1] !== key) continue;
-		const value = (match[2] ?? "").trim();
-		const quoted = /^"((?:[^"\\]|\\.)*)"$/u.exec(value) ?? /^'([^']*)'$/u.exec(value);
-		if (!quoted) return null;
-		return (quoted[1] ?? "").replace(/\\"/gu, '"');
-	}
-	return null;
-}
-
-/**
- * Whether a TOML file declares the named top-level table, e.g. `tool.tox`.
- * A trimmed line must start with `[table]` and carry nothing after it but an
- * optional `# comment`, the only content TOML itself allows there. A raw
- * `raw.includes("[table]")` check would also fire on a comment mentioning the
- * table or a string value that happens to contain the same bracketed text;
- * anchoring to the start of the line rules both out without a TOML parser,
- * while still accepting the valid `[table] # comment` form that a plain
- * equality check would have missed.
- */
-export function hasTomlTable(raw: string, table: string): boolean {
-	const header = `[${table}]`;
-	return raw.split(/\r?\n/u).some((line) => {
-		const trimmed = line.trim();
-		if (!trimmed.startsWith(header)) return false;
-		return /^\s*(?:#.*)?$/u.test(trimmed.slice(header.length));
-	});
-}
-
 /** One `KEY = value` line from a Doxyfile or an INI-shaped config. */
 function keyEqualsValue(raw: string, key: string): string | null {
 	const match = new RegExp(`^[ \\t]*${key}[ \\t]*(?:\\+?=)[ \\t]*(.+)$`, "mu").exec(raw);
@@ -182,27 +135,30 @@ const packageJson: MetadataReader = (cwd) => {
 	return { file: "package.json", fragment: { name: name(record.name), description: description(record.description) } };
 };
 
-const pyprojectToml: MetadataReader = (cwd) => {
-	const raw = readText(cwd, "pyproject.toml");
-	if (raw === null) return null;
+const pyprojectToml: MetadataReader = (_cwd, tomlFiles) => {
+	const document = tomlFiles.read("pyproject.toml");
+	if (document === null) return null;
+	const project = tomlTableAt(document, ["project"]);
+	const poetry = tomlTableAt(document, ["tool", "poetry"]);
 	// PEP 621 `[project]` first, then Poetry's older table.
-	const projectName = tomlTableValue(raw, "project", "name") ?? tomlTableValue(raw, "tool.poetry", "name");
-	const projectDescription =
-		tomlTableValue(raw, "project", "description") ?? tomlTableValue(raw, "tool.poetry", "description");
 	return {
 		file: "pyproject.toml",
-		fragment: { name: name(projectName), description: description(projectDescription) },
+		fragment: {
+			name: name(project?.name) ?? name(poetry?.name),
+			description: description(project?.description) ?? description(poetry?.description),
+		},
 	};
 };
 
-const cargoToml: MetadataReader = (cwd) => {
-	const raw = readText(cwd, "Cargo.toml");
-	if (raw === null) return null;
+const cargoToml: MetadataReader = (_cwd, tomlFiles) => {
+	const document = tomlFiles.read("Cargo.toml");
+	if (document === null) return null;
+	const packageTable = tomlTableAt(document, ["package"]);
 	return {
 		file: "Cargo.toml",
 		fragment: {
-			name: name(tomlTableValue(raw, "package", "name")),
-			description: description(tomlTableValue(raw, "package", "description")),
+			name: name(packageTable?.name),
+			description: description(packageTable?.description),
 		},
 	};
 };
@@ -488,13 +444,13 @@ function readmeTitle(content: string): string | null {
  * a CMake project that names itself but describes itself only in its README
  * should get both, not one or neither.
  */
-export function readProjectMetadata(cwd: string): ProjectMetadata {
+export function readProjectMetadata(cwd: string, tomlFiles = createTomlFileReader(cwd)): ProjectMetadata {
 	const out: ProjectMetadata = { name: null, description: null, nameSource: null, descriptionSource: null };
 	for (const reader of METADATA_READERS) {
 		if (out.name !== null && out.description !== null) break;
 		let read: ReturnType<MetadataReader>;
 		try {
-			read = reader(cwd);
+			read = reader(cwd, tomlFiles);
 		} catch {
 			continue;
 		}

package/src/domains/context/prompt-context.ts

@@ -20,6 +20,10 @@ import { wikiCompleteness, wikiStaleness } from "./wiki/staleness.js";
  * context-init preload reporting, and `clio-coder config inspect`, so every surface
  * measures the same text the session prompt would preload.
  */
+/** The one line that stands in for a handbook this workspace does not have. */
+export const HANDBOOK_ABSENT_FRAGMENT =
+	"<handbook>none: this workspace has no CLIO-CODER.md, so do not read one; learn the repository from its files, and the operator can run /context init to write a handbook</handbook>";
+
 export function renderPromptContext(cwd: string): ProjectPromptContext {
 	const projectType = detectProjectType(cwd);
 	const pieces = [renderProjectTypeFragment(projectType)];
@@ -30,6 +34,10 @@ export function renderPromptContext(cwd: string): ProjectPromptContext {
 	for (const issue of loadedClioMd.errors) {
 		warnings.push(`clio: malformed ${issue.path} ignored: ${issue.error}`);
 	}
+	// Said where the handbook would have been: a model that sees no project
+	// context spends its first tool call reading CLIO-CODER.md and gets
+	// ENOENT, while the operator's header already says it is missing (#191).
+	if (loadedClioMd.files.length === 0 && loadedClioMd.errors.length === 0) pieces.push(HANDBOOK_ABSENT_FRAGMENT);
 	const codewiki = readCodewiki(cwd);
 	if (codewiki) {
 		const state = readClioState(cwd);

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;
+}