opencode-clm 0.2.0 → 0.4.0

package/src/overrides.ts

@@ -170,9 +170,21 @@ export async function resetSettings(sessionDirectory: string): Promise<void> {
  * Current values of one session, read from its overrides.json (non-strict, never throws for
  * bad files). `mtimeMs`: when overrides.json was last written, if it exists.
  */
-export async function sessionValues(sessionDirectory: string, base: ClmSettings, baseEditing: boolean): Promise<{ values: SettingsValues; warning?: string; overrides: ClmOverrides; mtimeMs?: number }> {
+export async function sessionValues(sessionDirectory: string, base: ClmSettings, baseEditing: boolean): Promise<SessionValues> {
 	const read = await readOverrides(sessionDirectory);
 	const mtimeMs = await stat(overridesPath(sessionDirectory)).then((info) => info.mtimeMs, () => undefined);
+	return overridesValues(read, base, baseEditing, mtimeMs);
+}
+
+export interface SessionValues {
+	values: SettingsValues;
+	warning?: string;
+	overrides: ClmOverrides;
+	mtimeMs?: number;
+}
+
+/** `sessionValues` for overrides already read (e.g. through the server's file API). */
+export function overridesValues(read: OverridesRead, base: ClmSettings, baseEditing: boolean, mtimeMs?: number): SessionValues {
 	const at = mtimeMs !== undefined ? { mtimeMs } : {};
 	try {
 		return { values: valuesOf(base, baseEditing, read.overrides), overrides: read.overrides, ...(read.warning ? { warning: read.warning } : {}), ...at };

package/src/panel/command.ts

@@ -19,7 +19,7 @@ export type ClmCommand =
 	| { kind: "server"; args: string }
 	| { kind: "usage"; text: string };
 
-export const CLM_USAGE = "Usage: /clm [overview | input | edits | settings | status | path | on | off | reset | config [setting [value]]]";
+export const CLM_USAGE = "Usage: /clm [overview | input | edits | settings | status | path | on | off | reset | budget [value] | config [setting [value]]]";
 
 /** Page names and the short forms pi accepts. */
 const PAGE_ALIASES: Record<string, Page> = {
@@ -54,7 +54,13 @@ export function parseClmCommand(text: string): ClmCommand | undefined {
 		case "off":
 			return rest.length === 0 ? { kind: "enable", enabled: word === "on" } : { kind: "usage", text: CLM_USAGE };
 		case "reset":
-			return { kind: "server", args };
+			// Extra words are a typo, not a reset: dropping the revision cannot be undone.
+			return rest.length === 0 ? { kind: "server", args } : { kind: "usage", text: CLM_USAGE };
+		case "budget": {
+			// pi's shorthand for `/clm config budget …`.
+			const value = args.replace(/^\S+\s*/, "");
+			return value === "" ? { kind: "config-show", setting: "budget" } : { kind: "config-set", setting: "budget", value };
+		}
 		case "config": {
 			if (rest.length === 0) return { kind: "open", page: "settings" };
 			const setting = rest[0]!.toLowerCase();

package/src/panel/files.ts

@@ -60,6 +60,8 @@ export interface SnapshotFile {
 	budget: { budget: number; reserve: number; limit: number; source: string };
 	calibration: { factor: number; samples: number };
 	steering?: { name: string; hash: string; path: string };
+	/** Why the configured steering document did not load (sessions then run protocol-only). */
+	steeringError?: string;
 	sizes: { estimated: number; observedPrevious?: number };
 	input: {
 		raw: number;
@@ -98,6 +100,8 @@ export interface SessionFiles {
 	revisionTexts: Map<number, string>;
 	/** Path of the mirror file, whether or not it exists. */
 	mirrorPath: string;
+	/** annotations.jsonl counts: unresolved continuity/pin, unresolved archive, all. */
+	annotations?: { active: number; archived: number; total: number };
 	/** Read problems other than missing files. */
 	warnings: string[];
 }

package/src/panel/keys.ts

@@ -13,6 +13,7 @@ import {
 	effectiveZoom,
 	markerSelection,
 	maxScroll,
+	pageViewport,
 	revisionIndex,
 	settingsPage,
 	viewportHeight,
@@ -116,7 +117,7 @@ function clampSetting(model: PanelModel, index: number): number {
 
 function revealSetting(state: PanelState, model: PanelModel, size: PanelSize): PanelState {
 	const { focus } = settingsPage(model, state, contentWidth(size));
-	const viewport = viewportHeight(size);
+	const viewport = pageViewport(state, size);
 	let scroll = state.scroll;
 	if (focus < scroll) scroll = focus;
 	else if (focus >= scroll + viewport) scroll = focus - viewport + 1;
@@ -226,6 +227,15 @@ function step(state: PanelState, key: Key, model: PanelModel, size: PanelSize):
 	return { state };
 }
 
+/**
+ * The settings page with a result message pinned below it. The message takes body rows, so
+ * the selected row is scrolled back into view if the message would cover it.
+ */
+export function withMessage(state: PanelState, message: PanelState["message"], model: PanelModel, size: PanelSize): PanelState {
+	const next = { ...state, message };
+	return next.page === "settings" ? revealSetting(next, model, size) : next;
+}
+
 /** Applies one key. The result's scroll is clamped to the page. */
 export function reduce(state: PanelState, key: Key, model: PanelModel, size: PanelSize): ReduceResult {
 	const result = step(state, ALIASES[key] ?? key, model, size);

package/src/panel/model.ts

@@ -92,7 +92,7 @@ export interface BudgetView {
 	reserve?: number;
 	/** Overflow-guard limit (budget − reserve), from snapshot.json. */
 	limit?: number;
-	/** Where the budget came from (`config`, `model-window`). */
+	/** Where the budget came from (`config`, `model-window`, `window-fraction`, `fallback`). */
 	source?: string;
 	/** Fixed overhead per request (system prompt + tool schemas), tokens. */
 	overhead?: number;
@@ -123,7 +123,15 @@ export interface PanelModel {
 	budgetInfo?: BudgetView;
 	calibration?: { factor: number; samples: number };
 	steering?: { name: string; hash: string; path: string };
+	/** snapshot.json `steeringError`: the configured steering document did not load. */
+	steeringError?: string;
+	/** annotations.jsonl counts (`countAnnotations`): active continuity/pin, unresolved archive, all. */
+	annotations?: { active: number; archived: number; total: number };
 	mirrorPath: string;
+	/** The newest `mirror-unavailable` event's reason: the session runs without a mirror. */
+	mirrorUnavailable?: string;
+	/** The session runs `mode notices-only` (set by the caller from the settings in force). */
+	noticesOnly?: boolean;
 	/** Problems reading the files (corrupt JSON, skipped event lines). */
 	warnings: string[];
 }
@@ -245,11 +253,13 @@ export function buildTimeline(events: readonly ClmEvent[], latest?: LatestUsage)
 			let tokens = observedAfter.get(position);
 			if (tokens === undefined && position === lastRequest?.position) tokens = latestTokens;
 			const measured = tokens !== undefined;
+			const estimated = num(event.estimated);
 			points.push({
 				request: points.length + 1,
 				...(at ? { at } : {}),
-				tokens: tokens ?? Math.max(0, num(event.estimated) ?? 0),
+				tokens: tokens ?? Math.max(0, estimated ?? 0),
 				measured,
+				...(measured && estimated !== undefined && estimated > 0 ? { estimated } : {}),
 				revision: count(event.revision) ?? 0,
 			});
 			// `users` counts user messages in the raw history; a rise starts a turn. A drop
@@ -297,6 +307,13 @@ function markerOf(name: string | undefined, event: ClmEvent, afterPoint: number)
 			const reason = str(event.reason) ?? "OpenCode's history changed.";
 			return base("reset", dropped === undefined ? 0 : dropped + 1, dropped === undefined ? reason : `Revision ${dropped} dropped: ${reason}`);
 		}
+		case "restored": {
+			// Revert (`dropped`) or fork (`origin`): an older revision became the next one.
+			const from = count(event.from);
+			const origin = str(event.origin);
+			const source = from === undefined ? "an earlier revision" : `r${from}`;
+			return base("restored", revision ?? 0, origin ? `restored ${source} of ${origin} (fork)` : `restored ${source} (revert)`);
+		}
 		case "compacted": {
 			const summary = str(event.summary);
 			return base("compacted", revision ?? 0, summary ? `Rebased on compaction summary ${summary}.` : "Rebased on a compaction summary.");
@@ -539,9 +556,16 @@ export function buildPanelModel(files: SessionFiles, extras: PanelExtras = {}):
 	const calibration = isObject(snapshot?.calibration) ? snapshot.calibration : undefined;
 	const factor = num(calibration?.factor);
 	if (factor !== undefined) model.calibration = { factor, samples: count(calibration?.samples) ?? 0 };
+	if (files.annotations) model.annotations = files.annotations;
 	const steering = isObject(snapshot?.steering) ? snapshot.steering : undefined;
 	if (steering && typeof steering.name === "string" && typeof steering.hash === "string" && typeof steering.path === "string") {
 		model.steering = { name: steering.name, hash: steering.hash, path: steering.path };
 	}
+	if (typeof snapshot?.steeringError === "string" && snapshot.steeringError !== "") model.steeringError = snapshot.steeringError;
+	const unavailable = files.events.filter((event) => eventName(event) === "mirror-unavailable").at(-1)?.reason;
+	if (typeof unavailable === "string") {
+		model.mirrorUnavailable = unavailable;
+		model.mirrorPath = `unavailable (${unavailable})`;
+	}
 	return model;
 }

package/src/panel/timeline.ts

@@ -15,11 +15,13 @@ export interface TimelinePoint {
 	/** Context size of this request: provider-reported when `measured`, else the CLM estimate. */
 	tokens: number;
 	measured: boolean;
+	/** The CLM estimate logged for this request, kept beside a provider count (`measured`). */
+	estimated?: number;
 	/** Live-context revision active when the request was sent. */
 	revision: number;
 }
 
-export type MarkerKind = "applied" | "rejected" | "reset" | "compacted";
+export type MarkerKind = "applied" | "rejected" | "reset" | "compacted" | "restored";
 
 export interface TimelineMarker {
 	kind: MarkerKind;
@@ -410,6 +412,8 @@ export function formatMarkerCompact(marker: TimelineMarker): string {
 			return `r${marker.revision}  ${time}  reset to raw context`;
 		case "compacted":
 			return `r${marker.revision}  ${time}  compacted by OpenCode`;
+		case "restored":
+			return `r${marker.revision}  ${time}  ${marker.message}`;
 		case "rejected":
 			return `r${marker.revision}  ${time}  rejected: ${marker.message}`;
 		case "applied": {
@@ -439,6 +443,8 @@ export function formatMarkerRow(marker: TimelineMarker, timeline: ContextTimelin
 			return `r${marker.revision}  ${time}  reset to raw context  (${where})`;
 		case "compacted":
 			return `r${marker.revision}  ${time}  compacted by OpenCode  (${where})`;
+		case "restored":
+			return `r${marker.revision}  ${time}  ${marker.message}  (${where})`;
 		case "rejected":
 			return `r${marker.revision}  ${time}  edit rejected: ${marker.message}  (${where})`;
 	}

package/src/panel/view.ts

@@ -51,6 +51,8 @@ const ZOOM_LABELS: Record<TimelineZoom, string> = { fit: "all", requests: "detai
 const EDIT_TONE: Tone = "edit";
 const KEPT_PREVIEW_CHARACTERS = 2_000;
 const MIRROR_TEXT_MAX_LINES = 200;
+const MIRROR_UNAVAILABLE_TEXT = "No mirror: requests carry the raw history plus the continuity annotations; edits are off.";
+const NOTICES_ONLY_TEXT = "Mode notices-only: requests carry the raw history plus the budget notices; no mirror, so the model cannot edit its context (/clm config mode edit).";
 
 /** Body rows available for the page. */
 export function viewportHeight(size: PanelSize): number {
@@ -191,6 +193,10 @@ function overviewLines(model: PanelModel, state: PanelState, width: number, view
 	const timeline = model.timeline;
 	const notice = !model.enabled
 		? text("Projection off: the model sees the raw history (/clm on).", "warning")
+		: model.mirrorUnavailable !== undefined
+		? text(MIRROR_UNAVAILABLE_TEXT, "warning")
+		: model.noticesOnly
+		? text(NOTICES_ONLY_TEXT, "warning")
 		: model.lastOutcome?.kind === "rejected"
 			? text(`Last edit rejected: ${model.lastOutcome.message}`, "warning")
 			: undefined;
@@ -271,7 +277,9 @@ function inputLines(model: PanelModel, width: number): Line[] {
 		return wrapAll([
 			title,
 			[],
-			text("No input snapshot yet: snapshot.json appears after the next model request.", "muted"),
+			model.mirrorUnavailable !== undefined
+				? text(`${MIRROR_UNAVAILABLE_TEXT} No input snapshot is kept.`, "warning")
+				: text("No input snapshot yet: snapshot.json appears after the next model request.", "muted"),
 			[],
 			text(`Mirror: ${model.mirrorPath}`, "dim"),
 		], width);
@@ -447,6 +455,10 @@ export function settingsPage(model: PanelModel, state: PanelState, width: number
 		[span("Settings", "accent", true), span(" · changes apply from the next request and are saved in this session", "muted")],
 		...settings.summary.map((line) => text(line, "dim")),
 		...(settings.warning ? [text(`⚠ ${settings.warning}`, "warning")] : []),
+		// The server's own record, also when the TUI's settings check passed.
+		...(model.steeringError && !settings.warning?.includes(model.steeringError)
+			? [text(`⚠ steering document not loaded, the session runs without it: ${model.steeringError}`, "warning")]
+			: []),
 		[],
 	], width);
 	if (settings.rows.length === 0) {
@@ -469,12 +481,26 @@ export function settingsPage(model: PanelModel, state: PanelState, width: number
 	const row = settings.rows[selected]!;
 	if (row.description) lines.push([], ...wrapAll([text(row.description, "dim")], width));
 	lines.push([], ...wrapAll([text(row.choices?.length ? "Enter: next value" : "Enter: type a value", "dim")], width));
-	if (state.message) {
-		lines.push(...wrapAll([text(`${state.message.warning ? "⚠" : "✓"} ${state.message.text}`, state.message.warning ? "warning" : "success")], width));
-	}
 	return { lines, focus };
 }
 
+/**
+ * Lines pinned below the scrolling page: the settings page's result message ("✓ Budget:
+ * 20k"), so it stays on screen when the page is longer than the viewport. At most
+ * `viewport` − 1 lines, so one page line always shows.
+ */
+export function pinnedLines(state: PanelState, width: number, viewport: number): Line[] {
+	if (state.page !== "settings" || !state.message) return [];
+	const message = wrapAll([text(`${state.message.warning ? "⚠" : "✓"} ${state.message.text}`, state.message.warning ? "warning" : "success")], width);
+	return message.slice(0, Math.max(0, viewport - 1));
+}
+
+/** Body rows left for the scrolling page once the pinned lines take theirs. */
+export function pageViewport(state: PanelState, size: PanelSize): number {
+	const viewport = viewportHeight(size);
+	return Math.max(1, viewport - pinnedLines(state, contentWidth(size), viewport).length);
+}
+
 // ---- frame ---------------------------------------------------------------------------
 
 /** The whole page at `width` (unclipped; the frame scrolls it). */
@@ -505,7 +531,7 @@ export function helpText(model: PanelModel, state: PanelState, width: number): s
 }
 
 export function maxScroll(model: PanelModel, state: PanelState, size: PanelSize): number {
-	return Math.max(0, pageLines(model, state, contentWidth(size), viewportHeight(size)).length - viewportHeight(size));
+	return Math.max(0, pageLines(model, state, contentWidth(size), viewportHeight(size)).length - pageViewport(state, size));
 }
 
 /** The framed panel, exactly `size.height` lines of `size.width` cells. */
@@ -513,15 +539,18 @@ export function renderPanel(model: PanelModel, state: PanelState, size: PanelSiz
 	const width = Math.max(8, size.width);
 	const inner = width - 2;
 	const content = contentWidth({ width, height: size.height });
-	const viewport = viewportHeight(size);
-	const page = pageLines(model, state, content, viewport);
+	const body = viewportHeight(size);
+	const page = pageLines(model, state, content, body);
+	const pinned = pinnedLines(state, content, body);
+	const viewport = pageViewport(state, size);
 	const scroll = Math.max(0, Math.min(state.scroll, page.length - viewport));
-	const visible = page.slice(scroll, scroll + viewport);
-	while (visible.length < viewport) visible.push([]);
+	// The pinned lines follow the page directly when it fits, else sit at the bottom.
+	const visible = [...page.slice(scroll, scroll + viewport), ...pinned];
+	while (visible.length < body) visible.push([]);
 
 	const border = (value: string) => span(value, "border");
 	const row = (line: Line): Line => normalize([border("│"), span(" "), ...fit(line, inner - 1), border("│")]);
-	const title = ` Live Context Viewer · r${model.revision} `;
+	const title = ` Live Context Viewer · r${model.revision}${model.noticesOnly && model.enabled ? " · notices-only" : ""} `;
 	const titleText = truncate([span(title)], inner, "").map((part) => part.text).join("");
 	const left = Math.max(0, Math.floor((inner - titleText.length) / 2));
 	const right = Math.max(0, inner - titleText.length - left);

package/src/presentation.ts

@@ -98,6 +98,8 @@ export interface ClmStatus {
 	changed?: string;
 	/** Saved settings that could not be used. */
 	settingsWarning?: string;
+	/** Set in `mode notices-only`; absent in `edit`. */
+	mode?: "notices-only";
 }
 
 /** One line for a toast. */
@@ -105,7 +107,8 @@ export function statusLine(status: ClmStatus): string {
 	const size = status.reading
 		? ` · ${formatTokens(status.reading.estimated)} of ${formatTokens(status.reading.budget)} tok`
 		: "";
-	return `CLM r${status.revision} · ${status.accepted} accepted / ${status.rejected} rejected${size}`;
+	const mode = status.mode ? ` · mode ${status.mode}` : "";
+	return `CLM r${status.revision}${mode} · ${status.accepted} accepted / ${status.rejected} rejected${size}`;
 }
 
 /** Multi-line status for `/clm`. */
@@ -113,6 +116,7 @@ export function statusText(status: ClmStatus): string {
 	const lines = [
 		`CLM status for session ${status.sessionID}`,
 		`mirror: ${status.mirrorPath}`,
+		...(status.mode ? ["mode notices-only: budget notices and the overflow guard run; no mirror and no protocol prompt, so the model cannot edit its context"] : []),
 		`revision ${status.revision} · edits accepted ${status.accepted} · rejected ${status.rejected} · gate ${status.gate} · guard ${status.guard}`,
 		status.reading
 			? `${budgetSummaryLine(status.reading)} · model window ${status.modelWindow ? formatTokens(status.modelWindow) : "unknown"}`
@@ -121,7 +125,9 @@ export function statusText(status: ClmStatus): string {
 	if (status.fit) lines.push(budgetFitLine(status.fit));
 	const checkpoint = status.checkpoint;
 	lines.push(
-		checkpoint
+		checkpoint && status.mode
+			? `revision ${checkpoint.revision} kept but not applied in notices-only mode: the model sees the raw history`
+			: checkpoint
 			? `active revision ${checkpoint.revision}: covers ${checkpoint.anchorCount} raw messages; ~${formatTokens(checkpoint.beforeEstimate)}→${formatTokens(checkpoint.afterEstimate)} tokens when accepted`
 			: "no accepted edit: the model sees the raw history",
 	);

package/src/projection.ts

@@ -85,6 +85,14 @@ export function digestSourcePrefix(messages: readonly LiveContextMessage[]): str
 	);
 }
 
+/**
+ * `digestSourcePrefix` without OpenCode message ids. `Session.fork` copies every message
+ * under a new id, so the copied history digests the same way as the original.
+ */
+export function digestSourceContent(messages: readonly LiveContextMessage[]): string {
+	return digestSourcePrefix(messages.map(({ ocMessageID: _id, ...rest }) => rest as LiveContextMessage));
+}
+
 export function createProjectionCheckpoint(options: {
 	revision: number;
 	sourceMessages: readonly LiveContextMessage[];

package/src/session-files.ts

@@ -1,7 +1,8 @@
 // Read-only access to one session's CLM directory (`<mirrorDir>/clm-<session>/`) for the
 // `/clm` panel: events.jsonl, state.json, snapshot.json and revisions/rN.{json,md}. Missing
 // files are normal (a v0.1 session has no snapshot or rN.json); torn or corrupt lines and
-// files are skipped, never thrown. Written for this package.
+// files are skipped, never thrown. Reads go through a `SessionReader`: the disk, or the
+// server's file API for an attached TUI (src/tui/remote.ts). Written for this package.
 
 import { readdir, readFile, stat } from "node:fs/promises";
 import { join } from "node:path";
@@ -16,6 +17,17 @@ import {
 	type SessionFiles,
 } from "./panel/files.ts";
 import { STATE_FILE } from "./state.ts";
+import { activeContinuityAnnotations, ANNOTATIONS_FILE, reconstructAnnotations } from "./continuity.ts";
+
+/** Counts of annotations.jsonl (latest snapshot per id, as the server reconstructs them). */
+export function countAnnotations(text: string): { active: number; archived: number; total: number } {
+	const annotations = reconstructAnnotations(parseEvents(text).events);
+	return {
+		active: activeContinuityAnnotations(annotations).length,
+		archived: annotations.filter((annotation) => annotation.retention === "archive" && annotation.resolvedAt === undefined).length,
+		total: annotations.length,
+	};
+}
 
 /** `<mirrorDir>/clm-<safe session id>`, the directory MirrorStore creates for the session. */
 export function sessionDirectory(mirrorDir: string, sessionID: string): string {
@@ -47,40 +59,123 @@ export function parseEvents(text: string): { events: ClmEvent[]; skipped: number
 }
 
 /**
- * Revision files keyed by path, kept while their mtime and size are unchanged, so a reload
+ * Where a session directory is read from: the local disk, or the server through OpenCode's
+ * file API when the TUI runs elsewhere (src/tui/remote.ts). Paths are the server's absolute
+ * paths either way.
+ */
+export interface SessionReader {
+	/** Cache-key prefix, so the same path read two ways does not share entries. */
+	readonly name: string;
+	/** True for a directory; false when missing. Throws for other errors. */
+	isDirectory(path: string): Promise<boolean>;
+	/** File text; undefined when missing. Throws for other errors. */
+	readText(path: string): Promise<string | undefined>;
+	/** Entry names; [] when the directory is missing. Throws for other errors. */
+	list(path: string): Promise<string[]>;
+	/**
+	 * Version stamp of a file for the revision cache (mtime and size locally); undefined
+	 * when missing. A constant stamp caches the file for good (rN files are written once).
+	 */
+	stamp(path: string): Promise<string | undefined>;
+}
+
+export const localReader: SessionReader = {
+	name: "local",
+	async isDirectory(path) {
+		try {
+			return (await stat(path)).isDirectory();
+		} catch (error) {
+			if (isMissing(error)) return false;
+			throw error;
+		}
+	},
+	async readText(path) {
+		try {
+			return await readFile(path, "utf8");
+		} catch (error) {
+			if (isMissing(error)) return undefined;
+			throw error;
+		}
+	},
+	async list(path) {
+		try {
+			return await readdir(path);
+		} catch (error) {
+			if (isMissing(error)) return [];
+			throw error;
+		}
+	},
+	async stamp(path) {
+		try {
+			const info = await stat(path);
+			return `${info.mtimeMs}:${info.size}`;
+		} catch (error) {
+			if (isMissing(error)) return undefined;
+			throw error;
+		}
+	},
+};
+
+/**
+ * Revision files keyed by reader and path, kept while their stamp is unchanged, so a reload
  * on every streamed message reads only new or changed revisions. rN files are written once.
  */
-const revisionCache = new Map<string, { mtimeMs: number; size: number; value: unknown }>();
+const revisionCache = new Map<string, { stamp: string; size: number; value: unknown }>();
 const REVISION_CACHE_LIMIT = 2_000;
-/** Total file bytes kept; the oldest entries go first once it is exceeded. */
+/** Total text kept (characters); the oldest entries go first once it is exceeded. */
 const REVISION_CACHE_BYTES = 32 * 1024 * 1024;
 let revisionCacheBytes = 0;
 
+/** The last `state.json` revision seen per reader and session directory. */
+const lastStateRevision = new Map<string, number>();
+
+/**
+ * Drop the cached revision files of one session directory when `state.json`'s revision went
+ * down since the last read: the session restarted its count (a corrupt state file starts at
+ * 0), so its next rN files replace old ones. Needed for readers with a constant stamp (no
+ * mtime over the file API or the channel); harmless for the disk.
+ */
+function invalidateRevisions(reader: SessionReader, revisionsDirectory: string, stateRevision: number): void {
+	const prefix = `${reader.name}:${revisionsDirectory}/`;
+	const last = lastStateRevision.get(prefix);
+	lastStateRevision.set(prefix, stateRevision);
+	if (last === undefined || stateRevision >= last) return;
+	for (const [key, entry] of [...revisionCache.entries()]) {
+		if (!key.startsWith(prefix)) continue;
+		revisionCache.delete(key);
+		revisionCacheBytes -= entry.size;
+	}
+}
+
 function evictRevision(): void {
 	const [path, entry] = revisionCache.entries().next().value!;
 	revisionCache.delete(path);
 	revisionCacheBytes -= entry.size;
 }
 
-async function readCached(path: string, kind: "json" | "md", warnings: string[]): Promise<unknown> {
-	let info;
+async function readCached(reader: SessionReader, path: string, kind: "json" | "md", warnings: string[]): Promise<unknown> {
+	let stamp: string | undefined;
 	try {
-		info = await stat(path);
+		stamp = await reader.stamp(path);
 	} catch (error) {
-		if (!isMissing(error)) warnings.push(`Could not read ${path}: ${describe(error)}`);
+		warnings.push(`Could not read ${path}: ${describe(error)}`);
 		return undefined;
 	}
-	const cached = revisionCache.get(path);
-	if (cached && cached.mtimeMs === info.mtimeMs && cached.size === info.size) return cached.value;
-	const value = kind === "json" ? await readJson(path, warnings) : await readText(path, warnings);
+	if (stamp === undefined) return undefined;
+	const key = `${reader.name}:${path}`;
+	const cached = revisionCache.get(key);
+	if (cached && cached.stamp === stamp) return cached.value;
+	const text = await readText(reader, path, warnings);
+	if (text === undefined) return undefined;
+	const value = kind === "json" ? parseJson(text, path, warnings) : text;
 	if (value !== undefined) {
 		if (cached) {
-			revisionCache.delete(path);
+			revisionCache.delete(key);
 			revisionCacheBytes -= cached.size;
 		}
-		while (revisionCache.size > 0 && (revisionCache.size >= REVISION_CACHE_LIMIT || revisionCacheBytes + info.size > REVISION_CACHE_BYTES)) evictRevision();
-		revisionCache.set(path, { mtimeMs: info.mtimeMs, size: info.size, value });
-		revisionCacheBytes += info.size;
+		while (revisionCache.size > 0 && (revisionCache.size >= REVISION_CACHE_LIMIT || revisionCacheBytes + text.length > REVISION_CACHE_BYTES)) evictRevision();
+		revisionCache.set(key, { stamp, size: text.length, value });
+		revisionCacheBytes += text.length;
 	}
 	return value;
 }
@@ -99,18 +194,16 @@ function describe(error: unknown): string {
 	return error instanceof Error ? error.message : String(error);
 }
 
-async function readText(path: string, warnings: string[]): Promise<string | undefined> {
+async function readText(reader: SessionReader, path: string, warnings: string[]): Promise<string | undefined> {
 	try {
-		return await readFile(path, "utf8");
+		return await reader.readText(path);
 	} catch (error) {
-		if (!isMissing(error)) warnings.push(`Could not read ${path}: ${describe(error)}`);
+		warnings.push(`Could not read ${path}: ${describe(error)}`);
 		return undefined;
 	}
 }
 
-async function readJson(path: string, warnings: string[]): Promise<unknown> {
-	const text = await readText(path, warnings);
-	if (text === undefined) return undefined;
+function parseJson(text: string, path: string, warnings: string[]): unknown {
 	try {
 		return JSON.parse(text);
 	} catch (error) {
@@ -119,13 +212,18 @@ async function readJson(path: string, warnings: string[]): Promise<unknown> {
 	}
 }
 
+async function readJson(reader: SessionReader, path: string, warnings: string[]): Promise<unknown> {
+	const text = await readText(reader, path, warnings);
+	return text === undefined ? undefined : parseJson(text, path, warnings);
+}
+
 /** Reads the session directory of `sessionID` under `mirrorDir`. */
 export function readSessionFiles(mirrorDir: string, sessionID: string): Promise<SessionFiles> {
 	return readSessionDirectory(sessionDirectory(mirrorDir, sessionID), sessionID);
 }
 
 /** Reads a session directory given its path. Never throws for missing or corrupt files. */
-export async function readSessionDirectory(directory: string, sessionID: string): Promise<SessionFiles> {
+export async function readSessionDirectory(directory: string, sessionID: string, reader: SessionReader = localReader): Promise<SessionFiles> {
 	const warnings: string[] = [];
 	const files: SessionFiles = {
 		sessionID,
@@ -139,17 +237,19 @@ export async function readSessionDirectory(directory: string, sessionID: string)
 		warnings,
 	};
 	try {
-		files.found = (await stat(directory)).isDirectory();
+		files.found = await reader.isDirectory(directory);
 	} catch (error) {
-		if (!isMissing(error)) warnings.push(`Could not read ${directory}: ${describe(error)}`);
+		warnings.push(`Could not read ${directory}: ${describe(error)}`);
 	}
 	if (!files.found) return files;
 
-	const [eventsText, state, snapshot] = await Promise.all([
-		readText(join(directory, EVENTS_FILE), warnings),
-		readJson(join(directory, STATE_FILE), warnings),
-		readJson(join(directory, SNAPSHOT_FILE), warnings),
+	const [eventsText, state, snapshot, annotationsText] = await Promise.all([
+		readText(reader, join(directory, EVENTS_FILE), warnings),
+		readJson(reader, join(directory, STATE_FILE), warnings),
+		readJson(reader, join(directory, SNAPSHOT_FILE), warnings),
+		readText(reader, join(directory, ANNOTATIONS_FILE), warnings),
 	]);
+	if (annotationsText !== undefined) files.annotations = countAnnotations(annotationsText);
 	if (eventsText !== undefined) {
 		const parsed = parseEvents(eventsText);
 		files.events = parsed.events;
@@ -159,11 +259,13 @@ export async function readSessionDirectory(directory: string, sessionID: string)
 	if (snapshot !== undefined) files.snapshot = snapshot;
 
 	const revisionsDirectory = join(directory, REVISIONS_DIRECTORY);
+	const stateRevision = (state as { revision?: unknown } | undefined)?.revision;
+	if (typeof stateRevision === "number" && Number.isInteger(stateRevision)) invalidateRevisions(reader, revisionsDirectory, stateRevision);
 	let names: string[] = [];
 	try {
-		names = await readdir(revisionsDirectory);
+		names = await reader.list(revisionsDirectory);
 	} catch (error) {
-		if (!isMissing(error)) warnings.push(`Could not list ${revisionsDirectory}: ${describe(error)}`);
+		warnings.push(`Could not list ${revisionsDirectory}: ${describe(error)}`);
 	}
 	const jsonRevisions = new Set<number>();
 	const mdRevisions = new Set<number>();
@@ -172,12 +274,12 @@ export async function readSessionDirectory(directory: string, sessionID: string)
 		if (match) (match[2] === "json" ? jsonRevisions : mdRevisions).add(Number(match[1]));
 	}
 	await Promise.all([...jsonRevisions].map(async (revision) => {
-		const value = await readCached(join(revisionsDirectory, `r${revision}.json`), "json", warnings);
+		const value = await readCached(reader, join(revisionsDirectory, `r${revision}.json`), "json", warnings);
 		if (value !== undefined) files.revisions.set(revision, value);
 	}));
 	// rN.md is only shown when rN.json is missing or invalid.
 	await Promise.all([...mdRevisions].filter((revision) => !isRevisionFile(files.revisions.get(revision))).map(async (revision) => {
-		const text = await readCached(join(revisionsDirectory, `r${revision}.md`), "md", warnings);
+		const text = await readCached(reader, join(revisionsDirectory, `r${revision}.md`), "md", warnings);
 		if (typeof text === "string") files.revisionTexts.set(revision, text);
 	}));
 	return files;