@iowarp/clio-coder 0.3.2 → 0.3.4

package/src/core/defaults.ts

@@ -4,6 +4,7 @@
  * exist. Users edit the file directly or through TUI overlays.
  */
 
+import { DEFAULT_WORKING_SET_SETTINGS } from "../domains/context/working-set/defaults.js";
 import type { TargetDescriptor } from "../domains/providers/types/target-descriptor.js";
 import type { AutonomyLevel } from "../domains/safety/autonomy.js";
 import { GUARDRAIL_DEFAULTS, type GuardrailValues } from "./guardrails.js";
@@ -98,6 +99,32 @@ export interface CompactionSettings {
 	systemPrompt?: string;
 }
 
+/**
+ * Working-set layer settings (`context.workingSet`). The layer decides which
+ * tool-result bodies and thinking blocks leave the model's working set when
+ * pressure crosses `compaction.threshold`; it records evictions as ledger
+ * entries and never rewrites history. Defaults and prose live in
+ * src/domains/context/working-set/defaults.ts.
+ *
+ *   - enabled: master switch. Off skips eviction and goes straight to summary
+ *     compaction (the legacy destructive mask is only reachable through
+ *     CLIO_CODER_LEGACY_MASK=1).
+ *   - policy: candidate selection rule set.
+ *   - target: used/window ratio an applied event batches down to.
+ *   - protectLastTurns: recent user turns whose observations are never evicted.
+ *   - minEvictableTokens: results below this estimate are never evicted; the
+ *     marker would cost more than it saves.
+ */
+export type WorkingSetPolicyId = "age-horizon" | "structural-v1";
+
+export interface WorkingSetSettings {
+	enabled: boolean;
+	policy: WorkingSetPolicyId;
+	target: number;
+	protectLastTurns: number;
+	minEvictableTokens: number;
+}
+
 /**
  * Transient provider retry controls for the interactive chat loop. These are
  * intentionally small and mirror the session retry helper defaults. Dispatched
@@ -357,6 +384,9 @@ export const DEFAULT_SETTINGS = {
 		threshold: 0.8,
 		excludeLastTurns: 6,
 	} as CompactionSettings,
+	context: {
+		workingSet: DEFAULT_WORKING_SET_SETTINGS,
+	},
 	retry: {
 		enabled: true,
 		maxRetries: 3,
@@ -610,9 +640,9 @@ keybindings: {}
 #   auto              master switch for the pre-request compaction trigger.
 #                     Manual /context compact always runs the LLM summary.
 #   threshold         pressure = estimated_tokens / context_window. Crossing
-#                     it masks stale tool observations first, then runs a
-#                     full LLM summary if pressure stays above the threshold.
-#   excludeLastTurns  recent user turns protected from observation masking.
+#                     it evicts from the working set first, then runs a full
+#                     LLM summary if pressure stays above the threshold.
+#   excludeLastTurns  recent turns protected only by the temporary legacy mask.
 #   model             optional pattern (e.g. provider/summary-model-id) for a
 #                     dedicated summarization model. Absent ⇒ orchestrator target.
 #   systemPrompt      optional path to a prompt-override file.
@@ -623,6 +653,23 @@ compaction:
   # model: provider/summary-model-id
   # systemPrompt: ~/.config/clio-coder/prompts/compaction.md
 
+# Non-destructive working-set eviction before summary compaction.
+#   enabled             false skips eviction and goes directly to the summary stage.
+#   policy              structural-v1 evicts by what the session did since
+#                       (re-reads, edits, resolved failures, consumed listings)
+#                       and falls back to age only under pressure;
+#                       age-horizon is the previous age-based selection.
+#   target              pressure ratio an applied eviction batches down to.
+#   protectLastTurns    recent user turns whose observations remain in the working set.
+#   minEvictableTokens  entries below this estimate remain in the working set.
+context:
+  workingSet:
+    enabled: true
+    policy: structural-v1
+    target: 0.6
+    protectLastTurns: 6
+    minEvictableTokens: 200
+
 # Transient provider/stream retry controls for interactive chat.
 # Retryable errors include overloads, rate limits, 5xx responses, network
 # resets, and timeouts. Context overflow uses compaction recovery instead.

package/src/core/git-commit-attribution.ts

@@ -1,5 +1,15 @@
 import { execFileSync } from "node:child_process";
-import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import {
+	accessSync,
+	chmodSync,
+	existsSync,
+	constants as fsConstants,
+	mkdirSync,
+	readFileSync,
+	renameSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
 import { join, resolve } from "node:path";
 import { AI_AGENT_NAME } from "./agent-environment.js";
 import { CLIO_COMMIT_TRAILERS, type CommitAttributionEvidence } from "./commit-attribution.js";
@@ -30,7 +40,7 @@ const PROBE_CACHE_MAX_ENTRIES = 32;
 type RepositoryProbe =
 	| { kind: "outside" }
 	| { kind: "custom"; hooksPath: string }
-	| { kind: "default"; declaredDefault: boolean };
+	| { kind: "default"; declaredDefaultHooksPath: string | null };
 
 const probeCache = new Map<string, { at: number; probe: RepositoryProbe }>();
 let installedHooksDirectory: string | null = null;
@@ -171,27 +181,29 @@ case "$base_count" in
     ;;
 esac
 
-# A command may have moved into a different repository after Clio prepared the
-# environment. A repository with its own core.hooksPath gets its hook run and
-# is never attributed; composing an unknown setup is not attempted.
-if [ "$${DEFAULT_HOOKS_EQUIVALENT_ENV}" != '1' ] && git config --get core.hooksPath >/dev/null 2>&1; then
-  custom_hooks=$(git config --path --get core.hooksPath 2>/dev/null || true)
+# Resolve the current repository's default hooks directory before interpreting
+# the environment prepared for the originating repository. A command may have
+# moved into a different repository in between; an explicit default path is
+# composable only while it still names this same repository's default.
+common_dir=$(git rev-parse --git-common-dir 2>/dev/null || true)
+common_dir_absolute=$(cd "$common_dir" 2>/dev/null && pwd -P || true)
+case "$common_dir_absolute" in
+  '') default_hooks_directory=; default_hook= ;;
+  *) default_hooks_directory=$common_dir_absolute/hooks; default_hook=$default_hooks_directory/$hook_name ;;
+esac
+
+if git config --get core.hooksPath >/dev/null 2>&1 &&
+   [ "$${DEFAULT_HOOKS_EQUIVALENT_ENV}" != "$default_hooks_directory" ]; then
+	custom_hooks=$(git config --path --get core.hooksPath 2>/dev/null || true)
   case "$custom_hooks" in
     '') ;;
     /*) custom_hook=$custom_hooks/$hook_name ;;
     *) custom_hook=$PWD/$custom_hooks/$hook_name ;;
   esac
   if [ -n "$custom_hooks" ] && [ -x "$custom_hook" ]; then exec "$custom_hook" "$@"; fi
-  exit 0
+	exit 0
 fi
 
-common_dir=$(git rev-parse --git-common-dir 2>/dev/null || true)
-case "$common_dir" in
-  '') default_hook= ;;
-  /*) default_hook=$common_dir/hooks/$hook_name ;;
-  *) default_hook=$PWD/$common_dir/hooks/$hook_name ;;
-esac
-
 if [ "$hook_name" != 'prepare-commit-msg' ]; then
   if [ -n "$default_hook" ] && [ -x "$default_hook" ]; then exec "$default_hook" "$@"; fi
   exit 0
@@ -258,11 +270,22 @@ function installManagedHook(directory: string, name: string): void {
 	}
 }
 
+function managedHooksDirectoryIsIntact(directory: string): boolean {
+	try {
+		for (const name of MANAGED_HOOK_NAMES) {
+			const hook = join(directory, name);
+			if (readFileSync(hook, "utf8") !== MANAGED_HOOK_SCRIPT) return false;
+			accessSync(hook, fsConstants.X_OK);
+		}
+		return true;
+	} catch {
+		return false;
+	}
+}
+
 function managedHooksDirectory(): string {
 	const directory = join(clioStateDir(), "git-hooks", `v${MANAGED_HOOK_VERSION}`);
-	// Installed once per process; one stat afterwards confirms the Clio-owned
-	// directory is still there rather than re-reading all of its wrappers.
-	if (installedHooksDirectory === directory && existsSync(join(directory, "prepare-commit-msg"))) return directory;
+	if (installedHooksDirectory === directory && managedHooksDirectoryIsIntact(directory)) return directory;
 	mkdirSync(directory, { recursive: true, mode: 0o700 });
 	for (const name of MANAGED_HOOK_NAMES) installManagedHook(directory, name);
 	installedHooksDirectory = directory;
@@ -281,13 +304,13 @@ function gitEnvironmentFingerprint(env: NodeJS.ProcessEnv): string {
 function probeRepositoryUncached(cwd: string, env: NodeJS.ProcessEnv): RepositoryProbe {
 	if (gitOutput(cwd, env, ["rev-parse", "--is-inside-work-tree"]) !== "true") return { kind: "outside" };
 	const customHooksPath = gitOutput(cwd, env, ["config", "--path", "--get", "core.hooksPath"]);
-	if (customHooksPath === null) return { kind: "default", declaredDefault: false };
+	if (customHooksPath === null) return { kind: "default", declaredDefaultHooksPath: null };
 	const commonDirectory = gitOutput(cwd, env, ["rev-parse", "--git-common-dir"]);
 	const defaultHooksPath = commonDirectory === null ? null : resolve(cwd, commonDirectory, "hooks");
 	if (customHooksPath.length === 0 || resolve(cwd, customHooksPath) !== defaultHooksPath) {
 		return { kind: "custom", hooksPath: customHooksPath };
 	}
-	return { kind: "default", declaredDefault: true };
+	return { kind: "default", declaredDefaultHooksPath: defaultHooksPath };
 }
 
 function probeRepository(cwd: string, env: NodeJS.ProcessEnv, now = Date.now()): RepositoryProbe {
@@ -342,7 +365,9 @@ export function withManagedGitCommitAttributionEnvironment(
 			diagnostic: boundedDiagnostic(`core.hooksPath is set to '${probe.hooksPath}'; Clio commit attribution skipped`),
 		};
 	}
-	if (probe.declaredDefault) env[DEFAULT_HOOKS_EQUIVALENT_ENV] = "1";
+	if (probe.declaredDefaultHooksPath !== null) {
+		env[DEFAULT_HOOKS_EQUIVALENT_ENV] = probe.declaredDefaultHooksPath;
+	}
 
 	let hooksDirectory: string;
 	try {

package/src/core/verification-scripts.ts

@@ -1,11 +1,17 @@
 export const VERIFICATION_SCRIPT_FAMILY_HINT = "test*/lint*/build*/typecheck*/check*/format*/ci*";
 
 const VERIFICATION_SCRIPT_PATTERN = /^(?:test|lint|build|typecheck|check|format|ci)(?:[:.-].*)?$/;
+const PROJECT_VERIFIER_CHECK_ID_PATTERN = /^[a-z0-9][a-z0-9._:-]*$/;
 
 export function isVerificationScriptName(name: string): boolean {
 	return VERIFICATION_SCRIPT_PATTERN.test(name);
 }
 
+/** Stable identifier grammar for project-declared verifier catalog checks. */
+export function isProjectVerifierCheckId(name: string): boolean {
+	return PROJECT_VERIFIER_CHECK_ID_PATTERN.test(name);
+}
+
 export function declaredVerificationScripts(scripts: Record<string, unknown>): string[] {
 	return Object.keys(scripts)
 		.filter((name) => isVerificationScriptName(name))

package/src/domains/agents/builtins/verifier.md

@@ -24,6 +24,9 @@ Inspect scripts, docs, recent diffs, and touched files before choosing commands.
 When a codewiki exists, prefer `code_nav` (symbol, dependents) over broad reads to scope what a diff touches.
 Run only the checks required for the requested confidence level.
 Prefer typed validation tools over arbitrary shell execution.
+Call `verify()` before choosing an executable check. It lists package scripts and strict project entries from `.clio-coder/verifiers.yaml` through the same metadata shape.
+Run a project entry only by its listed ID. Do not add args, cwd, timeout, environment, or shell composition; the catalog's exact argv, cwd, and timeout are authoritative.
+Treat scientific validation contracts and generated handbook expectations as advisory evidence requirements. They do not become executable until the project declares a corresponding verifier-catalog entry.
 Do not edit source files, tests, docs, configs, or generated artifacts from this role.
 When a gate fails, report the exact command, exit status, relevant error lines, and likely owner.
 Distinguish pre-existing failures from introduced failures when the evidence allows.

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/config/keybindings.ts

@@ -122,14 +122,14 @@ export const CLIO_APP_KEYBINDINGS = {
 	"clio.tool.expand": {
 		defaultKeys: "alt+o",
 		description:
-			"Fold or unfold the newest tool call or worker block between its one-line summary and full details (no effect while /output verbose pins them open)",
+			"Fold or unfold the newest tool call or worker block between its one-line summary and full details, overriding the /output level for that block",
 	},
 	"clio.tool.expandAll": {
 		// Alt+Shift+letter is commonly consumed by OS keyboard-layout switching.
 		// Keep it discoverable, but pair it with the legacy-safe Ctrl+Alt form.
 		defaultKeys: ["ctrl+alt+o", "alt+shift+o"],
 		description:
-			"Fold or unfold every tool call and worker block at once (no effect while /output verbose pins them open)",
+			"Fold or unfold every tool call and worker block at once, overriding the /output level; changing /output clears the overrides",
 	},
 	"clio.tool.liveOutput": {
 		defaultKeys: "alt+p",
@@ -145,7 +145,7 @@ export const CLIO_APP_KEYBINDINGS = {
 		// Alt+Shift+R as a distinct key event.
 		defaultKeys: ["ctrl+alt+r", "alt+shift+r"],
 		description:
-			"Toggle all thinking blocks between hidden markers and full bodies (no effect while /output verbose pins them open)",
+			"Toggle all thinking blocks between hidden markers and full bodies, overriding the /output level; changing /output clears the overrides",
 	},
 	"clio.editor.external": {
 		defaultKeys: "alt+g",

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