@iowarp/clio-coder 0.3.2 → 0.3.4

package/src/domains/evidence/types.ts

@@ -3,6 +3,7 @@ import type { RunPersonaOverride, RunPipelineProvenance, RunReceiptAutonomyEnfor
 import type { EvalCommandPhase, EvalFailureClass, EvalRunRecord } from "../eval/index.js";
 import type { ProtectedArtifact } from "../safety/protected-artifacts.js";
 import type { RunEscalationCounts } from "./provenance.js";
+import type { CanonicalTrustStatus } from "./trust-status.js";
 
 export const EVIDENCE_VERSION = 1;
 
@@ -131,13 +132,38 @@ export interface EvidenceBuildResult {
 	directory: string;
 	overview: EvidenceOverview;
 	findings: EvidenceFinding[];
+	trustStatus: EvidenceTrustStatusFile;
 }
 
 export interface EvidenceInspectable {
 	overview: EvidenceOverview;
 	findings: EvidenceFinding[];
+	trustStatus: EvidenceTrustStatusView;
 }
 
+export interface EvidenceRunTrustStatus {
+	runId: string;
+	status: CanonicalTrustStatus;
+}
+
+/** Canonical per-run projection persisted by current evidence builders. */
+export interface EvidenceTrustStatusFile {
+	version: 1;
+	evidenceId: string;
+	projection: "canonical";
+	runs: EvidenceRunTrustStatus[];
+}
+
+/** Explicit compatibility result for a bundle built before the projection existed. */
+export interface HistoricalEvidenceTrustStatus {
+	version: 1;
+	evidenceId: string;
+	projection: "historical_format";
+	runs: [];
+}
+
+export type EvidenceTrustStatusView = EvidenceTrustStatusFile | HistoricalEvidenceTrustStatus;
+
 export interface EvidenceRunSource {
 	envelope: RunEnvelope;
 	receipt: RunReceipt | null;

package/src/domains/middleware/memory-intervention.ts

@@ -202,6 +202,9 @@ export function createMemoryInterventionRegistration(deps: MemoryInterventionDep
 						return effects;
 					}
 					case "on_compaction":
+						// Recall grows the working set; it is an observability point, not
+						// context loss that should reactivate compacted task memory.
+						if (input.metadata?.stage === "working_set_recall") return NO_EFFECTS;
 						reactivateAfterCompaction = true;
 						return NO_EFFECTS;
 					case "turn_start": {

package/src/domains/middleware/stalled-turn.ts

@@ -7,7 +7,116 @@ export const STALLED_TURN_REQUEST_CONTINUATION_MESSAGE =
 	"You ended your turn after announcing an action without executing it: no tools were called. Continue now and perform the announced action, or state plainly that you are finished and waiting for the user.";
 
 const INTENT_PATTERN = /\b(let me|i['’]ll|i will|i am going to|i['’]m going to|now i|next i|let's|let us)\b/i;
+
+// Bare stems only. Inflected forms are derived below so that "running",
+// "checking", and "verifies" count as the same announced action as "run".
+const CONCRETE_ACTION_STEMS = [
+	"add",
+	"analyse",
+	"analyze",
+	"apply",
+	"audit",
+	"build",
+	"change",
+	"check",
+	"compare",
+	"compile",
+	"create",
+	"debug",
+	"delete",
+	"edit",
+	"execute",
+	"explore",
+	"find",
+	"fix",
+	"format",
+	"grep",
+	"implement",
+	"inspect",
+	"install",
+	"investigate",
+	"list",
+	"load",
+	"look",
+	"modify",
+	"open",
+	"patch",
+	"query",
+	"read",
+	"refactor",
+	"remove",
+	"rename",
+	"replace",
+	"review",
+	"run",
+	"scan",
+	"search",
+	"test",
+	"trace",
+	"update",
+	"validate",
+	"verify",
+	"write",
+] as const;
+
+// Stems whose final consonant doubles before a vowel suffix.
+const DOUBLED_CONSONANT_STEMS = new Set(["debug", "format", "run", "scan"]);
+
+function concreteActionForms(stem: string): string[] {
+	const forms = new Set([stem, `${stem}s`, `${stem}ed`, `${stem}ing`]);
+	if (/(?:ch|sh|s|x|z)$/.test(stem)) forms.add(`${stem}es`);
+	if (stem.endsWith("e")) {
+		forms.add(`${stem}d`);
+		forms.add(`${stem.slice(0, -1)}ing`);
+	}
+	if (stem.endsWith("y")) {
+		forms.add(`${stem.slice(0, -1)}ies`);
+		forms.add(`${stem.slice(0, -1)}ied`);
+	}
+	if (DOUBLED_CONSONANT_STEMS.has(stem)) {
+		const doubled = `${stem}${stem.slice(-1)}`;
+		forms.add(`${doubled}ed`);
+		forms.add(`${doubled}ing`);
+	}
+	return [...forms];
+}
+
+const CONCRETE_ACTION_PATTERN = new RegExp(
+	`\\b(?:${CONCRETE_ACTION_STEMS.flatMap(concreteActionForms).join("|")})\\b`,
+	"giu",
+);
+
+// Extensions a model actually names when announcing work on a file. Requiring
+// one (or an explicit ./, ../, ~/ prefix) keeps "and/or" and "I/O" from
+// reading as paths.
+const NAMED_PATH_EXTENSIONS =
+	"c|cc|cfg|cjs|cmake|conf|cpp|cs|css|csv|env|go|h|hpp|html|ini|java|jl|js|json|jsx|lock|log|lua|md|mjs|nc|php|py|rb|rs|rst|sh|sql|toml|ts|tsx|txt|yaml|yml";
+const NAMED_PATH_PATTERN = new RegExp(
+	`(?:^|[\\s\`"'(\\[])(?:[\\w@.\\-/]*[\\w@\\-]\\.(?:${NAMED_PATH_EXTENSIONS})\\b|(?:\\.{1,2}|~)\\/[\\w@.\\-/]+)`,
+	"iu",
+);
+
+// A named executable followed by at least one argument token. Words that are
+// ordinary English on their own ("go", "make", "test") are deliberately absent.
+const NAMED_COMMAND_PATTERN =
+	/\b(?:npm|npx|pnpm|yarn|bun|git|cargo|rustc|cmake|ctest|ninja|meson|bazel|gradle|mvn|pytest|pip|python3?|node|deno|tsc|biome|eslint|prettier|jest|vitest|ruff|mypy|docker|kubectl|mpirun|srun|sbatch|gcc|clang)\s+[-\w./]/iu;
+
+const ACTION_OBJECT_CONNECTOR_PATTERN = /^(?:at|for|in|into|on|through|to)\s+/i;
+const ACTION_OBJECT_DETERMINER_PATTERN = /^(?:a|an|my|our|that|the|their|these|this|those|your)\s+/i;
+const ACTION_OBJECT_PATTERN = /^(?!(?:again|everyone|later|next|now|soon|then|you)\b)[`"'./~]*[\p{L}\p{N}_-]/iu;
+const CONDITIONAL_LEAD_IN_PATTERN = /\b(?:if|once|unless|until|when|whenever)\b/i;
+const CONDITIONAL_INVITATION_PATTERN = /\b(?:ask|give|point|say|send|share|tell)\b[\s\S]*\b(?:and|then)\s*$/i;
+// "if needed", and any conditional whose condition is about the user: "if you
+// want", "if that is what you need". Conditions about the work ("if the config
+// is valid") stay announcements.
+const CONDITIONAL_OFFER_SUFFIX_PATTERN =
+	/\b(?:if\s+(?:needed|necessary|requested)\b|if\b[^.!?]*\byou\b|when(?:ever)?\s+you\b)/i;
 const LET_ME_KNOW_PATTERN = /\blet me know\b/i;
+// "I'll wait for your go-ahead before I touch src/cli/index.ts" names a path
+// and promises nothing now. A clause that opens by deferring is a wait
+// statement whatever it goes on to name, so it is read before any verb or
+// path inside it can count as an announcement.
+const DEFERRAL_LEAD_PATTERN = /^\s*(?:just\s+|simply\s+|now\s+)?(?:wait|hold\s+off|hold|stand\s+by|pause|defer)\b/i;
 const COMPLETION_PATTERN =
 	/^\s*(?:all\s+done|done|complete|completed|all\s+set)\b|^\s*(?:here(?:'s| is)\s+)?(?:a\s+)?summary\b|^\s*summary\s*:?$/i;
 
@@ -38,7 +147,47 @@ export function shouldRequestStalledTurnContinuation(input: MiddlewareHookInput)
 	if (LET_ME_KNOW_PATTERN.test(finalSentence)) return false;
 	if (COMPLETION_PATTERN.test(lastLine) || COMPLETION_PATTERN.test(finalSentence)) return false;
 
-	return finalSentence.endsWith(":") || INTENT_PATTERN.test(finalSentence);
+	return announcesConcreteAction(finalSentence);
+}
+
+function announcesConcreteAction(sentence: string): boolean {
+	const intent = INTENT_PATTERN.exec(sentence);
+	if (intent) {
+		const leadIn = sentence.slice(0, intent.index);
+		if (
+			CONDITIONAL_LEAD_IN_PATTERN.test(leadIn) ||
+			CONDITIONAL_INVITATION_PATTERN.test(leadIn) ||
+			CONDITIONAL_OFFER_SUFFIX_PATTERN.test(sentence)
+		) {
+			return false;
+		}
+		const clause = sentence.slice(intent.index + intent[0].length);
+		if (DEFERRAL_LEAD_PATTERN.test(clause)) return false;
+		if (hasActionWithObject(clause)) return true;
+		// A path or command is evidence of an immediate action only when the
+		// announcement itself is unconditional; "once package.json is updated"
+		// names a file but promises nothing now.
+		if (CONDITIONAL_LEAD_IN_PATTERN.test(clause)) return false;
+		return namesToolTarget(clause);
+	}
+
+	// A trailing colon can still signal a cut-off action lead-in, but only when
+	// the lead-in names work and its target instead of relying on punctuation.
+	return sentence.endsWith(":") && hasActionWithObject(sentence);
+}
+
+function namesToolTarget(clause: string): boolean {
+	return NAMED_PATH_PATTERN.test(clause) || NAMED_COMMAND_PATTERN.test(clause);
+}
+
+function hasActionWithObject(clause: string): boolean {
+	for (const action of clause.matchAll(CONCRETE_ACTION_PATTERN)) {
+		const remainder = clause.slice((action.index ?? 0) + action[0].length).trimStart();
+		const withoutConnector = remainder.replace(ACTION_OBJECT_CONNECTOR_PATTERN, "");
+		const object = withoutConnector.replace(ACTION_OBJECT_DETERMINER_PATTERN, "");
+		if (ACTION_OBJECT_PATTERN.test(object)) return true;
+	}
+	return false;
 }
 
 function isNormalStopReason(value: unknown): boolean {
@@ -60,10 +209,22 @@ function lastNonEmptyLine(text: string): string | null {
 	return null;
 }
 
+// A period only terminates a sentence when it ends a token: "bash.ts" and
+// "package.json" must survive extraction intact.
+const SENTENCE_TERMINATOR_PATTERN = /[.!?]+["'’)\]]*(?=\s|$)/gu;
+
 function lastSentence(line: string): string {
-	const matches = line.match(/[^.!?]+[.!?]+(?:["')\]]+)?|[^.!?]+$/g);
-	const sentence = matches?.at(-1)?.trim() ?? line.trim();
-	return sentence.replace(/^[\s"'([{-]+/, "").trim();
+	const trimmed = line.trimEnd();
+	let start = 0;
+	for (const terminator of trimmed.matchAll(SENTENCE_TERMINATOR_PATTERN)) {
+		const end = (terminator.index ?? 0) + terminator[0].length;
+		if (end >= trimmed.length) break;
+		start = end;
+	}
+	return trimmed
+		.slice(start)
+		.replace(/^[\s"'([{-]+/, "")
+		.trim();
 }
 
 function isQuestion(sentence: string): boolean {

package/src/domains/safety/autonomy.ts

@@ -165,7 +165,7 @@ export function autonomyAskRejection(
 			// directory listings.
 			...(actionClass === "execute"
 				? [
-						'A declared package.json check runs without approval through the verify tool: verify(check="<script>").',
+						'A declared package or project-catalog check runs without approval through the verify tool: verify(check="<id>").',
 						"Read-only inspection runs without approval through the ls, read, grep, and find tools.",
 					]
 				: []),

package/src/domains/safety/default-path-policy.ts

@@ -61,6 +61,14 @@ export const DEFAULT_DAMAGE_CONTROL_PATH_POLICY: PathPolicyInput = {
 		"*.dump",
 	],
 	readOnlyPaths: [
+		// Clio's own operator-authority files in the project. `safety.yaml` is the
+		// policy that gates the model's tools, and `verifiers.yaml` is an argv
+		// catalog that verify() executes; a model that can author either one can
+		// widen its own permissions in two tool calls. Both are authored by the
+		// operator through the CLI (`clio-coder verifiers author` lands nothing
+		// before `--yes`), so model-side writes and deletes are refused.
+		".clio-coder/safety.yaml",
+		".clio-coder/verifiers.yaml",
 		"/etc/",
 		"/usr/",
 		"/bin/",

package/src/domains/safety/finish-contract.ts

@@ -1,5 +1,5 @@
 import { ToolNames } from "../../core/tool-names.js";
-import { isVerificationScriptName } from "../../core/verification-scripts.js";
+import { isProjectVerifierCheckId, isVerificationScriptName } from "../../core/verification-scripts.js";
 import {
 	detectValidationCommand,
 	extractCommandDeleteTargets,
@@ -399,8 +399,9 @@ export function typedValidationSummary(toolName: string, payload: Record<string,
 			const path = typeof args?.path === "string" && args.path.trim().length > 0 ? args.path.trim() : "artifact";
 			return `verify frontend ${path}`;
 		}
-		if (!isVerificationScriptName(check)) return null;
-		return `npm run ${check}`;
+		if (isVerificationScriptName(check)) return `npm run ${check}`;
+		if (isProjectVerifierCheckId(check)) return `verify ${check}`;
+		return null;
 	}
 	return null;
 }

package/src/domains/safety/policy-engine.ts

@@ -4,6 +4,7 @@ import { artifactDefaultPath } from "../../core/artifact-paths.js";
 import { canonicalizeExistingPath } from "../../core/path-canonical.js";
 import { ToolNames } from "../../core/tool-names.js";
 import { clioConfigDir } from "../../core/xdg.js";
+import { type DeclaredCheck, loadProjectVerifierCatalog } from "../../tools/verify/catalog.js";
 import { type ActionClass, type Classification, type ClassifierCall, classify } from "./action-classifier.js";
 import type { DamageControlMatch, DamageControlRule } from "./damage-control.js";
 import { DEFAULT_DAMAGE_CONTROL_PATH_POLICY, mergePathPolicyInputs } from "./default-path-policy.js";
@@ -225,7 +226,9 @@ export function createSafetyPolicyEngine(options: SafetyPolicyEngineOptions = {}
 			const rawClassification = classify(call);
 			const command = commandArg(call.args);
 			const callCwd = cwdArg(call.args, cwd);
-			const scan = damageControlScan(call);
+			const catalogCheck = resolveVerifyCatalogCheck(call, cwd);
+			const catalogCommand = catalogCheck === null ? null : catalogCheck.command.join(" ");
+			const scan = catalogCommand ?? damageControlScan(call);
 			const hit = scan ? matchSourcedRule(scan, sourcedRules) : null;
 			const classification = effectiveClassification(rawClassification, hit?.match);
 
@@ -335,8 +338,9 @@ export function createSafetyPolicyEngine(options: SafetyPolicyEngineOptions = {}
 			// command; the one carve-out is the exit-code-only presence check
 			// (`grep -q`/`grep -sq` with a ^NAME= pattern), which is the safe
 			// protocol the credentials skill teaches.
-			if (call.tool === ToolNames.Bash && command !== null) {
-				const secretRead = evaluateBashZeroAccessRead(zeroAccessPolicy, command, callCwd);
+			const scannedCommand = call.tool === ToolNames.Bash ? command : catalogCommand;
+			if (scannedCommand !== null) {
+				const secretRead = evaluateBashZeroAccessRead(zeroAccessPolicy, scannedCommand, callCwd);
 				if (secretRead !== null) {
 					const blockInput: Omit<
 						SafetyPolicyDecision,
@@ -407,9 +411,22 @@ export function createSafetyPolicyEngine(options: SafetyPolicyEngineOptions = {}
 			};
 			if (hit?.match.ruleId !== undefined) allowInput.ruleId = hit.match.ruleId;
 			if (hit?.match !== undefined) allowInput.match = hit.match;
-			// The typed execution tool (verify) is bounded by its own check
-			// allowlist, so it sits in the no-prompt set.
-			if (classification.actionClass === "execute") allowInput.execRecognition = "recognized";
+			// The typed execution tool (verify) sits in the no-prompt set when the
+			// check is a package script or the frontend validator: both are bounded
+			// by the verification-script family and run a fixed argv shape. A
+			// project-catalog check runs whatever argv the workspace file declares,
+			// so it is unrecognized: auto-edit parks it for one confirmation that
+			// shows the argv, full-auto runs it, and the damage-control match and
+			// zero-access scan above have already seen the declared vector.
+			if (classification.actionClass === "execute") {
+				allowInput.execRecognition = catalogCheck === null ? "recognized" : "unrecognized";
+				if (catalogCheck !== null) {
+					allowInput.reasons = [
+						...allowInput.reasons,
+						`project verifier '${catalogCheck.id}' runs declared argv: ${catalogCommand ?? ""}`,
+					];
+				}
+			}
 			return allowDecision(base, allowInput);
 		},
 		metadata() {
@@ -958,6 +975,31 @@ function damageControlScan(call: ClassifierCall): string {
 	return typeof pathArg === "string" ? pathArg : "";
 }
 
+/**
+ * The project-catalog check a verify call resolves to, or null for a listing,
+ * the frontend validator, a package script, or an id the catalog does not
+ * declare. The catalog is an argv vector the operator authored, but the file
+ * sits in the workspace, so the engine reads it fresh on every verify call and
+ * treats the declared argv exactly like a bash command string: it is what the
+ * damage-control rules and the zero-access read guard scan, and it is not in
+ * the no-prompt set. An unreadable or invalid catalog resolves to null here and
+ * fails closed in the tool itself.
+ */
+function resolveVerifyCatalogCheck(call: ClassifierCall, workspaceRoot: string): DeclaredCheck | null {
+	if (call.tool !== ToolNames.Verify) return null;
+	const check = call.args?.check;
+	if (typeof check !== "string") return null;
+	const id = check.trim();
+	if (id.length === 0 || id === "frontend") return null;
+	try {
+		const catalog = loadProjectVerifierCatalog(workspaceRoot);
+		if (!catalog.ok || catalog.source === null) return null;
+		return catalog.source.checks.find((candidate) => candidate.id === id) ?? null;
+	} catch {
+		return null;
+	}
+}
+
 function serializeArgs(args?: Record<string, unknown>): string {
 	if (!args) return "";
 	const parts: string[] = [];

package/src/domains/session/compaction/compact.ts

@@ -12,6 +12,8 @@
 
 import { stream } from "../../../engine/ai.js";
 import type { EngineModel, Usage } from "../../../engine/types.js";
+import { foldWorkingSet } from "../../context/working-set/fold.js";
+import { recallableRefListing } from "../../context/working-set/recall.js";
 import type { CompactionUsage, SessionEntry } from "../entries.js";
 import { serializeConversation } from "./branch-summary.js";
 import { findCutPoint } from "./cut-point.js";
@@ -307,6 +309,23 @@ function formatFileOperations(fileOps: FileOperations): string {
 	return sections.length > 0 ? `\n\n${sections.join("\n\n")}` : "";
 }
 
+function formatRecallableRefs(entries: ReadonlyArray<SessionEntry>, firstKeptEntryIndex: number): string {
+	const entryIndexes = new Map<string, number>();
+	for (let index = 0; index < entries.length; index += 1) {
+		const entry = entries[index];
+		if (entry) entryIndexes.set(entry.turnId, index);
+	}
+	const view = foldWorkingSet(entries);
+	const evictedBeforeCut = new Map(
+		[...view.evicted].filter(([ref]) => (entryIndexes.get(ref) ?? Number.POSITIVE_INFINITY) < firstKeptEntryIndex),
+	);
+	const listing = recallableRefListing(entries, { ...view, evicted: evictedBeforeCut });
+	if (listing.refs.length === 0) return "";
+	const rows = [...listing.refs];
+	if (listing.remaining > 0) rows.push(`and ${listing.remaining} more`);
+	return `\n\n<recallable-refs>\n${rows.join("\n")}\n</recallable-refs>`;
+}
+
 function numberOrZero(value: unknown): number {
 	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
 }
@@ -457,7 +476,10 @@ export async function compact(input: CompactInput): Promise<CompactResult> {
 		}
 	}
 
-	const summary = `${summaryParts.join("\n\n---\n\n").trim()}${formatFileOperations(fileOps)}`.trim();
+	const summary = `${summaryParts.join("\n\n---\n\n").trim()}${formatFileOperations(fileOps)}${formatRecallableRefs(
+		input.entries,
+		cut.firstKeptEntryIndex,
+	)}`.trim();
 
 	return {
 		summary,

package/src/domains/session/compaction/cut-point.ts

@@ -72,6 +72,8 @@ function isValidCutPoint(entry: SessionEntry): boolean {
 		case "taskLedger":
 		case "decisionLedger":
 		case "workerRun":
+		case "contextEviction":
+		case "contextRecall":
 			return false;
 	}
 }

package/src/domains/session/compaction/tokens.ts

@@ -34,7 +34,18 @@ export interface TokenEstimator {
 }
 
 function estimateMessage(entry: MessageEntry): number {
-	return estimateAgentMessageTokens(entry);
+	// Usage invalidation is bookkeeping for token-anchor selection. The replay
+	// builder carries it as AgentMessage metadata, but providers never see it in
+	// message content, so it cannot change a projected entry's prompt cost. Drop
+	// it here so plan-time pricing and the post-event projection use one byte
+	// definition even though only the latter has applied the stamp.
+	if (entry.role !== "assistant" || !entry.payload || typeof entry.payload !== "object") {
+		return estimateAgentMessageTokens(entry);
+	}
+	const payload = entry.payload as Record<string, unknown>;
+	if (!("contextUsageInvalidated" in payload)) return estimateAgentMessageTokens(entry);
+	const { contextUsageInvalidated: _stamp, ...promptPayload } = payload;
+	return estimateAgentMessageTokens({ ...entry, payload: promptPayload });
 }
 
 function estimateBashExecution(entry: BashExecutionEntry): number {
@@ -78,6 +89,10 @@ export function estimateTokens(entry: SessionEntry): number {
 		case "taskLedger":
 		case "decisionLedger":
 		case "workerRun":
+		// Working-set bookkeeping: refs and markers, never bodies. The
+		// projection accounts for marker cost on the projected messages.
+		case "contextEviction":
+		case "contextRecall":
 			return 0;
 	}
 }

package/src/domains/session/context-ledger.ts

@@ -122,6 +122,8 @@ export interface PromptCacheStats {
 	 * combination the overlay renders as a warning.
 	 */
 	backendVerdict: "hot" | "partial" | "cold" | "small" | null;
+	/** Cache disturbances Clio expected before the last settled run. */
+	expectedColdReasons?: ReadonlyArray<string>;
 }
 
 export interface ContextLedgerGroup {

package/src/domains/session/entries.ts

@@ -276,6 +276,75 @@ export interface WorkerRunEntry extends BaseSessionEntry {
 	parentToolCallId?: string;
 }
 
+/**
+ * Working-set layer (context domain) ledger records. Eviction is a projection:
+ * these entries say what left the model's working set and what came back; the
+ * original bodies stay in the ledger untouched. The context domain owns the
+ * semantics (`src/domains/context/working-set/contract.ts`); the session
+ * domain owns the wire shape because it owns the ledger format.
+ */
+export const EVICTION_REASONS = [
+	"superseded_read",
+	"stale_after_mutation",
+	"listing_consumed",
+	"failure_resolved",
+	"thinking_turn_closed",
+	"age_horizon",
+	"operator",
+] as const;
+export type EvictionReason = (typeof EVICTION_REASONS)[number];
+
+export const EVICTION_TRIGGERS = ["pressure", "operator"] as const;
+export type EvictionTrigger = (typeof EVICTION_TRIGGERS)[number];
+
+export const RECALL_TRIGGERS = ["tool", "operator"] as const;
+export type RecallTrigger = (typeof RECALL_TRIGGERS)[number];
+
+/**
+ * Identity of an evictable unit: the `turnId` of a ledger entry. For a
+ * `tool_result` message the unit is the result body; for an `assistant`
+ * message the unit is every thinking block it carries. Partial (per-block)
+ * eviction is deliberately not modelled; add a `block` field here when it is.
+ */
+export interface WorkingSetRef {
+	entry: string;
+}
+
+export interface EvictedItem {
+	ref: WorkingSetRef;
+	reason: EvictionReason;
+	/** Estimated tokens the projection removes for this item (marker cost already subtracted). */
+	tokensFreed: number;
+	/**
+	 * Byte-stable one-line stub the projection renders in place of the body.
+	 * Empty for thinking-block eviction, which removes without a marker.
+	 */
+	marker: string;
+	/** Ref key of the entry that superseded or resolved this one, when the reason names one. */
+	by?: string;
+}
+
+export interface ContextEvictionEntry extends BaseSessionEntry {
+	kind: "contextEviction";
+	policyId: string;
+	trigger: EvictionTrigger;
+	evicted: ReadonlyArray<EvictedItem>;
+	tokensBefore: number;
+	tokensAfter: number;
+	/** Used/window ratio that fired the event; null for operator-triggered events. */
+	pressureBefore: number | null;
+	snapshotIdBefore: string | null;
+}
+
+export interface ContextRecallEntry extends BaseSessionEntry {
+	kind: "contextRecall";
+	ref: WorkingSetRef;
+	trigger: RecallTrigger;
+	tokensReadmitted: number;
+	/** The tool call that performed the recall, when `trigger` is `tool`. */
+	toolCallId?: string;
+}
+
 export type SessionEntry =
 	| MessageEntry
 	| BashExecutionEntry
@@ -291,7 +360,9 @@ export type SessionEntry =
 	| SkillActivationEntry
 	| TaskLedgerEntry
 	| DecisionLedgerEntry
-	| WorkerRunEntry;
+	| WorkerRunEntry
+	| ContextEvictionEntry
+	| ContextRecallEntry;
 
 export type SessionFileEntry = SessionHeader | SessionEntry;
 
@@ -317,6 +388,8 @@ export const SESSION_ENTRY_KINDS = [
 	"taskLedger",
 	"decisionLedger",
 	"workerRun",
+	"contextEviction",
+	"contextRecall",
 ] as const;
 
 export type SessionEntryKind = (typeof SESSION_ENTRY_KINDS)[number];
@@ -477,6 +550,21 @@ export function isSessionHeader(value: unknown): value is SessionHeader {
 	);
 }
 
+function isWorkingSetRef(value: unknown): value is WorkingSetRef {
+	return isRecord(value) && isString(value.entry);
+}
+
+function isEvictedItem(value: unknown): value is EvictedItem {
+	return (
+		isRecord(value) &&
+		isWorkingSetRef(value.ref) &&
+		isOneOf(value.reason, EVICTION_REASONS) &&
+		isNumber(value.tokensFreed) &&
+		isString(value.marker) &&
+		isOptionalString(value.by)
+	);
+}
+
 export function isSessionEntry(value: unknown): value is SessionEntry {
 	if (!value || typeof value !== "object") return false;
 	const v = value as Record<string, unknown>;
@@ -567,6 +655,24 @@ export function isSessionEntry(value: unknown): value is SessionEntry {
 				isWorkerRunRuntime(v.runtime) &&
 				isOptionalString(v.parentToolCallId)
 			);
+		case "contextEviction":
+			return (
+				isString(v.policyId) &&
+				isOneOf(v.trigger, EVICTION_TRIGGERS) &&
+				Array.isArray(v.evicted) &&
+				v.evicted.every(isEvictedItem) &&
+				isNumber(v.tokensBefore) &&
+				isNumber(v.tokensAfter) &&
+				(v.pressureBefore === null || isNumber(v.pressureBefore)) &&
+				(v.snapshotIdBefore === null || isString(v.snapshotIdBefore))
+			);
+		case "contextRecall":
+			return (
+				isWorkingSetRef(v.ref) &&
+				isOneOf(v.trigger, RECALL_TRIGGERS) &&
+				isNumber(v.tokensReadmitted) &&
+				isOptionalString(v.toolCallId)
+			);
 	}
 	return false;
 }

package/src/domains/session/manager.ts

@@ -70,9 +70,16 @@ export function resumeSessionState(sessionId: string): {
 } {
 	const persistedMeta = readSessionMeta(sessionId) as SessionMeta;
 	const paths = sessionPaths(persistedMeta);
-	runMigrations(persistedMeta, paths.meta);
+	const migration = runMigrations(persistedMeta, paths.meta);
 	const { meta, writer, tree } = engineResumeSession(sessionId);
-	return { state: { meta: meta as SessionMeta, writer }, nodes: tree };
+	const state: SessionManagerState = { meta: meta as SessionMeta, writer };
+	if (migration.migrated) {
+		// The ledger needed no transformation; only the stamp moves, so the next
+		// reader does not re-run the same no-op.
+		state.meta.sessionFormatVersion = migration.to;
+		persistSessionMeta(state);
+	}
+	return { state, nodes: tree };
 }
 
 export function appendTurn(state: SessionManagerState, input: TurnInput): ClioTurnRecord {