opencode-clm 0.1.0 → 0.2.0

package/src/clm.ts

@@ -33,16 +33,20 @@
  * included) was estimated; without those sizes it stays at 1.
  */
 import { randomUUID } from "node:crypto";
-import { appendFile, mkdir, writeFile } from "node:fs/promises";
+import { appendFile, mkdir, stat, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
 import {
+	budgetFit,
 	budgetNoticeText,
 	budgetTiers,
+	budgetTooSmallAlertText,
+	budgetTooSmallNoticeText,
 	BudgetTracker,
 	EstimateCalibrator,
 	formatTokens,
 	resolveBudget,
+	type BudgetFit,
 	type BudgetReading,
 } from "./budget.ts";
 import { applyContextDocument, renderContextDocument, renderMessage } from "./context-document.ts";
@@ -63,13 +67,19 @@ import type { ClmStatus } from "./presentation.ts";
 import { applyProjection, createProjectionCheckpoint, type ProjectionCheckpoint } from "./projection.ts";
 import type { ClmSettings } from "./settings.ts";
 import {
+	keptFields,
 	loadLiveContextState,
 	resetProjectionState,
 	saveLiveContextState,
+	type BudgetCheck,
 	type LiveContextState,
 } from "./state.ts";
 import type { SteeringDocument } from "./steering.ts";
-import type { ContextDocumentSnapshot, LiveContextMessage, TurnBaseline } from "./types.ts";
+import { overridesPath, readOverrides, stageSettings, type ChangeRequest, type StagedSettings } from "./overrides.ts";
+import { changedSummary, settingsAsOverrides, type ClmOverrides, type SettingsValues } from "./settings-table.ts";
+import type { ContextDocumentSnapshot, ContextEditTrace, LiveContextMessage, TurnBaseline } from "./types.ts";
+import { writeJsonAtomic } from "./atomic.ts";
+import { SNAPSHOT_FILE, type RevisionFile, type RevisionFileRow, type SnapshotFile } from "./panel/files.ts";
 
 export interface ModelLimits {
 	/** Model context window, tokens. */
@@ -94,6 +104,8 @@ export interface TransformResult {
 	/** Calibrated estimate of this request, tokens (system prompt and tool schemas included when known); undefined when CLM did not run. */
 	estimated?: number;
 	reading?: BudgetReading;
+	/** User-facing warning for a toast (the budget-too-small check); set on one request only. */
+	alert?: string;
 }
 
 export interface MirrorCheck {
@@ -112,6 +124,12 @@ const SESSION_ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
 
 const CHARS_PER_TOKEN = 4;
 
+/**
+ * Largest share of the provider count the conversation estimate may hold for an overhead
+ * measurement; above it the estimate's error would dominate the result.
+ */
+const MAX_CONVERSATION_SHARE = 0.25;
+
 /** Index after the pinned prefix: everything up to and including the first user message. */
 export function pinnedCount(raw: readonly OcMessage[]): number {
 	const first = raw.findIndex((message) => message.info.role === "user");
@@ -187,6 +205,8 @@ export class ClmSession {
 	requests = 0;
 
 	private pendingNotices: string[] = [];
+	/** Raw length and conversation estimate (calibrated, tokens) of the last request, for the overhead measurement. */
+	private previousRequest?: { rawCount: number; conversation: number };
 	private invalidationStreak = 0;
 	/**
 	 * Per-process seed of the stable document id. Fresh on every open, so a document id never
@@ -197,27 +217,124 @@ export class ClmSession {
 	private saving: Promise<void> = Promise.resolve();
 	private running: Promise<unknown> = Promise.resolve();
 
+	/** Settings in force: `baseSettings` with this session's overrides.json applied (`refreshSettings`). */
+	settings: ClmSettings;
+	/** Overrides in force, as read from overrides.json. */
+	overrides: ClmOverrides = {};
+	/** The steering document in force for this session; undefined is protocol only. */
+	steering?: SteeringDocument;
+	/** Why saved settings or the steering document were (partly) ignored; shown by `/clm status`. */
+	settingsWarning?: string;
+	/** stat key of the overrides.json last read; a change triggers a re-read. */
+	private overridesKey = "";
+
 	private constructor(
 		readonly sessionID: string,
 		readonly store: MirrorStore,
-		readonly settings: ClmSettings,
+		readonly baseSettings: ClmSettings,
 		loaded: { state: LiveContextState; warning?: string },
+		readonly baseSteering?: SteeringDocument,
 	) {
+		this.settings = baseSettings;
+		this.steering = baseSteering;
 		this.state = loaded.state;
 		this.loadWarning = loaded.warning;
 		this.annotations = new AnnotationStore(store.directory, { estimateTokens: (text) => this.textTokens(text) });
 	}
 
-	/** Open (or resume) the session directory `<mirrorDir>/clm-<sessionID>/`. */
-	static async open(sessionID: string, settings: ClmSettings): Promise<ClmSession> {
+	/**
+	 * Open (or resume) the session directory `<mirrorDir>/clm-<sessionID>/`. `steering` is the
+	 * document the base settings name, already loaded (the plugin loads it strictly at start).
+	 */
+	static async open(sessionID: string, settings: ClmSettings, options: { steering?: SteeringDocument } = {}): Promise<ClmSession> {
 		if (!SESSION_ID_RE.test(sessionID)) throw new Error(`Invalid session id for CLM: ${JSON.stringify(sessionID)}`);
 		const store = await MirrorStore.create(sessionID, settings.mirrorDir);
 		const loaded = await loadLiveContextState(store.directory);
-		const session = new ClmSession(sessionID, store, settings, loaded);
+		const session = new ClmSession(sessionID, store, settings, loaded, options.steering);
 		if (loaded.warning) await session.log({ event: "state-warning", warning: loaded.warning });
+		if (loaded.repaired) await session.log({ event: "state-repaired", message: loaded.repaired });
+		await session.refreshSettings();
 		return session;
 	}
 
+	/** Whether CLM edits apply in this session: the `editing` override, else state.json. */
+	get enabled(): boolean {
+		return this.overrides.editing ?? this.state.enabled;
+	}
+
+	/** Base and effective values, for the settings table. */
+	settingsValues(): { base: SettingsValues; effective: SettingsValues } {
+		return {
+			base: { editing: this.state.enabled, settings: this.baseSettings },
+			effective: { editing: this.enabled, settings: this.settings },
+		};
+	}
+
+	/** For `changeSetting` (overrides.ts): where and against what a change is validated. */
+	changeRequest(projectDirectory: string): ChangeRequest {
+		return {
+			sessionDirectory: this.store.directory,
+			base: this.baseSettings,
+			baseEditing: this.state.enabled,
+			projectDirectory,
+			format: { modelWindow: this.limits.context },
+		};
+	}
+
+	/**
+	 * Re-read overrides.json when it changed (stat: mtime, size, inode) and activate it.
+	 * Runs before every request and every `/clm` command, so a change written by the TUI or
+	 * the server's `/clm config` applies from the next request. Invalid keys are dropped; a
+	 * set that does not resolve falls back to the base settings; a steering document that
+	 * does not load leaves the session protocol-only. Each case is kept in `settingsWarning`.
+	 * `force` re-reads even when the file looks unchanged.
+	 */
+	async refreshSettings(force = false): Promise<void> {
+		const path = overridesPath(this.store.directory);
+		let key = "missing";
+		try {
+			const info = await stat(path);
+			key = `${info.mtimeMs}:${info.size}:${info.ino}`;
+		} catch {
+			// missing: no overrides
+		}
+		if (!force && key === this.overridesKey) return;
+		this.overridesKey = key;
+		const read = key === "missing" ? { overrides: {} as ClmOverrides } : await readOverrides(this.store.directory);
+		const warnings: string[] = read.warning ? [read.warning] : [];
+		let staged: StagedSettings;
+		let overrides = read.overrides;
+		try {
+			staged = stageSettings(this.baseSettings, overrides, { strict: false, loaded: this.steering ?? this.baseSteering });
+		} catch (error) {
+			warnings.push(`ignored saved settings: ${describe(error)}`);
+			overrides = {};
+			staged = { settings: this.baseSettings, ...(this.baseSteering ? { steering: this.baseSteering } : {}) };
+		}
+		if (staged.steeringError) warnings.push(`steering document not loaded: ${staged.steeringError}`);
+		await this.activateSettings(staged, overrides);
+		this.settingsWarning = warnings.length > 0 ? warnings.join("; ") : undefined;
+	}
+
+	private async activateSettings(staged: StagedSettings, overrides: ClmOverrides): Promise<void> {
+		const before = this.settings.budget;
+		const after = staged.settings.budget;
+		const wasEnabled = this.enabled;
+		const changed = JSON.stringify(this.overrides) !== JSON.stringify(overrides);
+		this.settings = staged.settings;
+		this.steering = staged.steering;
+		this.overrides = overrides;
+		if (before.contextBudget !== after.contextBudget || before.reserve !== after.reserve ||
+			before.remindAtFractions.join(",") !== after.remindAtFractions.join(",") || before.remindAtReserve !== after.remindAtReserve) {
+			this.tracker.reset();
+		}
+		if (wasEnabled !== this.enabled) {
+			this.baseline = undefined;
+			if (!this.enabled) this.continuitySize.observe(0);
+		}
+		if (changed) await this.log({ event: "settings", overrides });
+	}
+
 	get mirrorPath(): string {
 		return this.store.filePath;
 	}
@@ -250,8 +367,29 @@ export class ClmSession {
 		return notices.reduce((total, notice) => total + this.textTokens(notice), 0);
 	}
 
-	resolvedBudget() {
-		return resolveBudget(this.settings.budget, this.limits.context, this.limits.output);
+	/**
+	 * The budget in force: the configured one (or the model window), raised when the
+	 * session's budget check found it too small for OpenCode's fixed overhead (`budgetFit`).
+	 */
+	resolvedBudget(): Pick<BudgetReading, "budget" | "reserve" | "source" | "raisedFrom"> | undefined {
+		const base = resolveBudget(this.settings.budget, this.limits.context, this.limits.output);
+		if (!base) return undefined;
+		const fit = budgetFit(base.budget, base.reserve, this.state.budgetCheck?.overhead, this.windowCap());
+		return fit.raised ? { ...base, budget: fit.effective, raisedFrom: base.budget } : base;
+	}
+
+	/** Model window minus its output limit, when known: the ceiling for a raised budget. */
+	private windowCap(): number | undefined {
+		return resolveBudget({ ...this.settings.budget, contextBudget: undefined }, this.limits.context, this.limits.output)?.budget;
+	}
+
+	/**
+	 * Budget arithmetic for `/clm` and a TUI panel: fixed overhead, usable budget, effective
+	 * budget. Undefined while the budget is unknown; `overhead` is unset until measured.
+	 */
+	budgetFit(): BudgetFit | undefined {
+		const base = resolveBudget(this.settings.budget, this.limits.context, this.limits.output);
+		return base ? budgetFit(base.budget, base.reserve, this.state.budgetCheck?.overhead, this.windowCap()) : undefined;
 	}
 
 	/** budget − reserve, or undefined while the budget is unknown. */
@@ -260,6 +398,81 @@ export class ClmSession {
 		return resolved ? overflowGuardLimit(resolved.budget, resolved.reserve) : undefined;
 	}
 
+	/**
+	 * Fixed overhead of a request (system prompt + tool schemas), measured once per session.
+	 *
+	 * Request 1 cannot measure it: OpenCode calls `experimental.chat.system.transform` after
+	 * this hook, and the provider count arrives with the reply. So a later transform measures
+	 * it: provider-reported input of the previous request minus that request's conversation
+	 * estimate. The estimate's error lands in the overhead, so the measurement waits for a
+	 * request whose conversation is at most MAX_CONVERSATION_SHARE of the provider count
+	 * (a restarted or upgraded session with a long history is measured after the model
+	 * shrinks its context, or not at all).
+	 *
+	 * Fallback: the chars/4 hook sizes, only when the provider answered without reporting
+	 * usage. They miss OpenCode's built-in tool schemas (Effect schemas, not measured;
+	 * several thousand tokens low), so a fallback result is replaced by the first provider
+	 * measurement.
+	 */
+	private measureOverhead(raw: readonly OcMessage[], observed: ObservedRequest | undefined): Pick<BudgetCheck, "overhead" | "source"> | undefined {
+		const previous = this.previousRequest;
+		if (!previous) return undefined;
+		if (observed && observed.index >= previous.rawCount) {
+			if (previous.conversation > observed.tokens * MAX_CONVERSATION_SHARE) return undefined;
+			return { overhead: Math.round(observed.tokens - previous.conversation), source: "provider" };
+		}
+		if (this.state.budgetCheck) return undefined; // an estimate never replaces a measurement
+		const answered = raw.slice(previous.rawCount)
+			.some((message) => message.info.role === "assistant" && !message.info.error && !message.info.summary);
+		const { systemTokens, toolTokens } = this.scope;
+		if (answered && systemTokens !== undefined && toolTokens !== undefined) {
+			return { overhead: this.calibrator.apply(systemTokens + toolTokens), source: "estimate" };
+		}
+		return undefined;
+	}
+
+	/**
+	 * The budget-too-small check, once per session (plus once more when a provider count
+	 * replaces a fallback estimate). Decision: raise the effective budget to overhead +
+	 * WORKING_MARGIN + reserve (capped by the model window) rather than switch the overflow
+	 * guard off. With the guard off, one large tool result can push the request past the
+	 * model window; with the budget raised, reminders, the fit gate and the guard keep
+	 * working, measured against a budget the conversation can actually use. The overhead is
+	 * persisted in `state.budgetCheck` and the raise is derived from it on every request, so
+	 * it survives a restart, and the event, toast and notice do not repeat.
+	 */
+	private async checkBudget(measured: Pick<BudgetCheck, "overhead" | "source">): Promise<string | undefined> {
+		const base = resolveBudget(this.settings.budget, this.limits.context, this.limits.output);
+		if (!base) return undefined;
+		const previous = this.state.budgetCheck;
+		const fit = budgetFit(base.budget, base.reserve, measured.overhead, this.windowCap());
+		const check: BudgetCheck = {
+			...measured,
+			configured: base.budget,
+			reserve: base.reserve,
+			effective: fit.effective,
+			raised: fit.raised,
+			at: new Date().toISOString(),
+		};
+		// activateOnFailure: a failed save still applies the raise in this process.
+		await this.updateState((state) => ({ ...state, budgetCheck: check }), true).catch(() => undefined);
+		// A replaced estimate that already reported "too small" does not warn again.
+		const warnedBefore = previous !== undefined && budgetFit(previous.configured, previous.reserve, previous.overhead).tooSmall;
+		const warn = fit.tooSmall && !warnedBefore;
+		await this.log({
+			event: warn ? "budget-too-small" : "budget-check",
+			...check,
+			usable: fit.usable,
+			margin: fit.margin,
+			minimum: fit.minimum,
+			capped: fit.capped,
+			...(previous ? { replaces: previous.source, previousOverhead: previous.overhead } : {}),
+		});
+		if (!warn) return undefined;
+		this.pendingNotices.push(budgetTooSmallNoticeText(fit));
+		return budgetTooSmallAlertText(fit);
+	}
+
 	// ---- persistence -------------------------------------------------------------------
 
 	/**
@@ -347,7 +560,7 @@ export class ClmSession {
 	 * calls that only read it or do not touch it.
 	 */
 	receipt(tool: string, args: Record<string, unknown> | undefined, cwd: string): string | undefined {
-		if (!this.settings.enabled || !this.state.enabled) return undefined;
+		if (!this.settings.enabled || !this.enabled) return undefined;
 		if (classifyMirrorToolCall(tool, args ?? {}, cwd, this.mirrorPath) !== "write") return undefined;
 		const check = this.validateMirror(this.store.readSync());
 		if (!check) return undefined;
@@ -420,6 +633,7 @@ export class ClmSession {
 					revision,
 					checkpoint,
 					lastOutcome: { kind: "applied", message: applied, ...sizes, at },
+					...keptFields(state),
 				};
 			});
 		} catch (error) {
@@ -431,6 +645,10 @@ export class ClmSession {
 		const revisions = join(this.store.directory, "revisions");
 		await mkdir(revisions, { recursive: true, mode: 0o700 }).catch(() => undefined);
 		await writeFile(join(revisions, `r${revision}.md`), text, { mode: 0o600 }).catch(() => undefined);
+		if (trace) {
+			await writeJsonAtomic(join(revisions, `r${revision}.json`), this.revisionFile(revision, at, baseline, result.messages, trace, sizes))
+				.catch((error: unknown) => this.log({ event: "revision-file-error", revision, error: describe(error) }));
+		}
 		const notes = result.diagnostics.length > 0 ? ` ${result.diagnostics.join(" ")}` : "";
 		this.pendingNotices.push(`[CLM] ${applied}${notes}`);
 		await this.log({
@@ -452,6 +670,101 @@ export class ClmSession {
 		});
 	}
 
+	/** `revisions/rN.json` for the panel: every row's full text and role before and after. */
+	private revisionFile(
+		revision: number,
+		at: string,
+		baseline: Baseline,
+		output: readonly LiveContextMessage[],
+		trace: ContextEditTrace,
+		sizes: { beforeEstimate: number; afterEstimate: number },
+	): RevisionFile {
+		const rows: RevisionFileRow[] = [];
+		const roleOf = (message: LiveContextMessage | undefined) => (message ? String(message.role) : "?");
+		for (const source of trace.sources) {
+			const before = baseline.snapshot.blocks[source.sourceIndex]?.source;
+			const after = source.outputIndex !== undefined ? output[source.outputIndex] : undefined;
+			const row: RevisionFileRow = { kind: source.kind, sourceIndex: source.sourceIndex, role: roleOf(after ?? before) };
+			if (source.outputIndex !== undefined) row.outputIndex = source.outputIndex;
+			if (before && after && roleOf(before) !== roleOf(after)) {
+				row.beforeRole = roleOf(before);
+				row.afterRole = roleOf(after);
+			}
+			if (before) row.beforeTokens = this.estimate([before]);
+			if (after && source.kind !== "removed") row.afterTokens = this.estimate([after]);
+			const beforeText = before ? renderMessage(before) : undefined;
+			const afterText = after && source.kind !== "removed" ? renderMessage(after) : undefined;
+			// Unchanged rows (kept, most restored) store their text once.
+			if (beforeText !== undefined && beforeText === afterText) row.text = beforeText;
+			else {
+				if (beforeText !== undefined) row.before = beforeText;
+				if (afterText !== undefined) row.after = afterText;
+			}
+			rows.push(row);
+		}
+		for (const addition of trace.additions) {
+			const after = output[addition.outputIndex];
+			rows.push({
+				kind: "added",
+				outputIndex: addition.outputIndex,
+				role: roleOf(after),
+				...(after ? { after: renderMessage(after), afterTokens: this.estimate([after]) } : {}),
+			});
+		}
+		return {
+			version: 1,
+			revision,
+			sourceRevision: trace.sourceRevision,
+			at,
+			beforeTokens: sizes.beforeEstimate,
+			afterTokens: sizes.afterEstimate,
+			rows,
+		};
+	}
+
+	/** `snapshot.json` for the panel: the request just built, replaced atomically. */
+	private snapshotFile(input: {
+		pinned: readonly LiveContextMessage[];
+		effective: readonly LiveContextMessage[];
+		sourceTokens: number;
+		raw: number;
+		sent: number;
+		suffix: number;
+		estimated: number;
+		observed?: number;
+	}): SnapshotFile | undefined {
+		const base = resolveBudget(this.settings.budget, this.limits.context, this.limits.output);
+		const resolved = this.resolvedBudget();
+		if (!base || !resolved) return undefined;
+		const shown = [...input.pinned, ...input.effective];
+		const steering = this.steering;
+		return {
+			at: new Date().toISOString(),
+			request: this.requests,
+			revision: this.state.revision,
+			enabled: this.enabled,
+			budget: { budget: base.budget, reserve: base.reserve, limit: overflowGuardLimit(resolved.budget, resolved.reserve), source: base.source },
+			calibration: { factor: this.calibrator.factor, samples: this.calibrator.sampleCount },
+			...(steering ? { steering: { name: steering.name, hash: steering.hash, path: steering.path } } : {}),
+			sizes: { estimated: input.estimated, ...(input.observed !== undefined ? { observedPrevious: input.observed } : {}) },
+			input: {
+				raw: input.raw,
+				sent: input.sent,
+				suffix: input.suffix,
+				rawTokens: input.sourceTokens,
+				effectiveTokens: this.estimate([...shown]),
+				messages: shown.map((message, index) => ({
+					index: index + 1,
+					role: String(message.role),
+					tokens: this.estimate([message]),
+					preview: renderMessage(message).replace(/\s+/g, " ").trim().slice(0, 120),
+				})),
+			},
+			...(this.state.budgetCheck ? { overhead: this.state.budgetCheck.overhead } : {}),
+			base: settingsAsOverrides(this.baseSettings) as Record<string, unknown>,
+		};
+	}
+
 	// ---- the transform -----------------------------------------------------------------
 
 	/** Transforms of one session run one at a time. */
@@ -469,7 +782,7 @@ export class ClmSession {
 
 	/** Text for `experimental.session.compacting`'s `output.context`: the instruction plus the active annotations. */
 	async compactionContext(): Promise<string | undefined> {
-		if (!this.settings.enabled || !this.state.enabled) return undefined;
+		if (!this.settings.enabled || !this.enabled) return undefined;
 		const continuity = formatContinuityMessage({ annotations: await this.loadAnnotations(), effectiveMessages: [] });
 		return continuity ? `${COMPACTION_INSTRUCTION}\n\n${continuity}` : COMPACTION_INSTRUCTION;
 	}
@@ -489,6 +802,7 @@ export class ClmSession {
 			enabled: state.enabled,
 			revision: state.revision + 1,
 			lastOutcome: { kind: "compacted", message, at },
+			...keptFields(state),
 		}), true).catch(() => {
 			written = false;
 			return this.state;
@@ -508,7 +822,8 @@ export class ClmSession {
 	}
 
 	private async transformNow(raw: OcMessage[]): Promise<TransformResult> {
-		if (!this.settings.enabled || !this.state.enabled) {
+		await this.refreshSettings();
+		if (!this.settings.enabled || !this.enabled) {
 			this.baseline = undefined;
 			this.compacting = false;
 			return { messages: raw, notices: [] };
@@ -536,6 +851,12 @@ export class ClmSession {
 		const source = flatten(raw.slice(pinned));
 		const observed = lastProviderReported(raw);
 		this.calibrator.observe(observed);
+		// Before the guard and the reading, so a raise applies to this request already.
+		const measured = this.state.budgetCheck?.source === "provider" ? undefined : this.measureOverhead(raw, observed);
+		const alert = measured ? await this.checkBudget(measured) : undefined;
+		// Samples taken before the overhead was measured read the unmeasured part of the
+		// overhead (built-in tool schemas) as undercounting; start calibration over.
+		if (measured?.source === "provider") this.calibrator.reset();
 
 		let projection = applyProjection(source, this.state.checkpoint);
 		// A late or repeated compaction signal must not swallow a later revert: rebase only
@@ -575,9 +896,15 @@ export class ClmSession {
 		const resolved = this.resolvedBudget();
 		const limit = resolved ? overflowGuardLimit(resolved.budget, resolved.reserve) : undefined;
 		// System prompt and tool schemas, when the hooks reported them (one request late).
+		// A provider-measured overhead replaces them: it is in real tokens, so it is not
+		// calibrated, and it includes the built-in tool schemas the hooks cannot size. The
+		// hook sizes stay a floor, since they count text that is certainly sent.
 		const { systemTokens, toolTokens } = this.scope;
-		const scopeTokens = this.calibrator.apply((systemTokens ?? 0) + (toolTokens ?? 0));
-		const excluded = [
+		const measuredOverhead = this.state.budgetCheck?.source === "provider"
+			? Math.max(this.state.budgetCheck.overhead, (systemTokens ?? 0) + (toolTokens ?? 0))
+			: undefined;
+		const scopeTokens = measuredOverhead ?? this.calibrator.apply((systemTokens ?? 0) + (toolTokens ?? 0));
+		const excluded = measuredOverhead !== undefined ? [] : [
 			...(systemTokens === undefined ? ["the system prompt"] : []),
 			...(toolTokens === undefined ? ["tool schemas"] : []),
 		];
@@ -668,39 +995,65 @@ export class ClmSession {
 		];
 
 		// Calibrate only against a same-scope estimate: the provider count includes the system
-		// prompt and tool schemas, so both sizes must be known.
-		if (systemTokens !== undefined && toolTokens !== undefined) {
-			const conversation = this.rawTokens(flatten(pinnedMessages)) + this.rawTokens(effective) +
-				(continuity ? this.textTokens(continuity) : 0) + this.noticeTokens(notices);
-			this.calibrator.record(systemTokens + toolTokens + conversation, raw.length);
+		// prompt and tool schemas. With a measured overhead the calibrator compares the
+		// conversation with the provider count minus that overhead; otherwise both hook sizes
+		// must be known.
+		const conversationRaw = this.rawTokens(flatten(pinnedMessages)) + this.rawTokens(effective) +
+			(continuity ? this.textTokens(continuity) : 0) + this.noticeTokens(notices);
+		if (measuredOverhead !== undefined) {
+			this.calibrator.record(conversationRaw, raw.length, measuredOverhead);
+		} else if (systemTokens !== undefined && toolTokens !== undefined) {
+			this.calibrator.record(systemTokens + toolTokens + conversationRaw, raw.length);
 		}
 
+		this.previousRequest = { rawCount: raw.length, conversation: conversationTokens + this.calibrator.apply(this.noticeTokens(notices)) };
 		this.lastRequest = { rawMessages: raw.length, sentMessages: messages.length, mirrorBlocks: snapshot.blocks.length };
 		if (this.settings.dumpRequests) {
 			const directory = join(this.store.directory, "requests");
 			await mkdir(directory, { recursive: true, mode: 0o700 }).catch(() => undefined);
 			await writeFile(join(directory, `n${this.requests}.json`), JSON.stringify(messages, null, 1), { mode: 0o600 }).catch(() => undefined);
 		}
+		const snapshotFile = this.snapshotFile({
+			pinned: flatten(pinnedMessages),
+			effective,
+			sourceTokens: pinnedTokens + this.estimate(source),
+			raw: raw.length,
+			sent: messages.length,
+			suffix: suffixLength,
+			estimated: reading?.estimated ?? requestTokens,
+			...(observed ? { observed: observed.tokens } : {}),
+		});
+		if (snapshotFile) {
+			await writeJsonAtomic(join(this.store.directory, SNAPSHOT_FILE), snapshotFile)
+				.catch((error: unknown) => this.log({ event: "snapshot-error", error: describe(error) }));
+		}
 		await this.log({
 			event: "request",
 			n: this.requests,
 			revision: this.state.revision,
+			users: raw.filter((message) => message.info.role === "user").length,
 			raw: raw.length,
 			sent: messages.length,
 			blocks: snapshot.blocks.length,
 			withheld: withheldCount,
 			estimated: reading?.estimated ?? requestTokens,
 			observedPrevious: observed?.tokens,
+			// The assistant message that reported `observedPrevious`; a new id means a new count.
+			observedMessage: observed?.messageID,
 			calibration: this.calibrator.factor,
 			notices: notices.map((notice) => notice.slice(0, 80)),
 		});
-		return { messages, notices, estimated: reading?.estimated ?? requestTokens, reading };
+		return { messages, notices, estimated: reading?.estimated ?? requestTokens, reading, ...(alert ? { alert } : {}) };
 	}
 
 	/** Inputs for presentation.ts `statusText` / `statusLine`. */
-	status(steering?: SteeringDocument): ClmStatus {
+	status(steering: SteeringDocument | undefined = this.steering): ClmStatus {
 		const checkpoint = this.state.checkpoint;
+		const { base, effective } = this.settingsValues();
+		const changed = changedSummary(base, effective, { modelWindow: this.limits.context });
 		return {
+			...(changed ? { changed } : {}),
+			...(this.settingsWarning ? { settingsWarning: this.settingsWarning } : {}),
 			sessionID: this.sessionID,
 			mirrorPath: this.mirrorPath,
 			revision: this.state.revision,
@@ -709,6 +1062,7 @@ export class ClmSession {
 			gate: this.settings.gate,
 			guard: this.settings.guard,
 			reading: this.lastReading,
+			fit: this.budgetFit(),
 			modelWindow: this.limits.context,
 			checkpoint: checkpoint
 				? {

package/src/commands.ts

@@ -0,0 +1,18 @@
+// The slash commands the server plugin defines, shared with the TUI so its Enter intercept
+// can tell this package's `/clm` from a user's own. Written for this package.
+
+export const STATUS_COMMAND = "clm";
+export const COMPACT_COMMAND = "clm-compact";
+export const STATUS_TEMPLATE = "Show the CLM status. $ARGUMENTS";
+export const COMPACT_TEMPLATE = "Compact your context. $ARGUMENTS";
+
+/**
+ * True when the config's `command.clm` is not this package's: a user-defined `/clm` keeps
+ * its owner, as the server's config hook leaves it alone. Absent → ours (or none yet).
+ */
+export function userOwnsStatusCommand(commands: unknown): boolean {
+	if (!commands || typeof commands !== "object") return false;
+	const entry = (commands as Record<string, unknown>)[STATUS_COMMAND];
+	if (entry === undefined) return false;
+	return !(entry && typeof entry === "object" && (entry as { template?: unknown }).template === STATUS_TEMPLATE);
+}

package/src/context-document.ts

@@ -525,13 +525,40 @@ export function applyContextDocument(
 
 	const parsed = parseDocument(editedText, snapshot);
 	const metadataLine = snapshot.text.split("\n")[0] ?? "";
-	const staleMetadata = () =>
-		rejected(
+	// States the current revision, what is wrong with the file, and the exact line to
+	// write, so the model can fix the file in one step.
+	const staleMetadata = () => {
+		const current = `The mirror is at revision ${snapshot.revision}.`;
+		let found: string;
+		let cause: string;
+		if (parsed.revision === undefined) {
+			found = "your file has no [[LIVE_CONTEXT ...]] line 1";
+			cause = parsed.blocks.length === 0 && /^\s*\[\[CTX_TURN /m.test(editedText)
+				? `${current} Its block headers come from an older copy of the mirror: read the file again and apply your change to its current text.`
+				: `${current} Put the line below back as line 1 and keep the rest of your edit.`;
+		} else if (parsed.revision !== snapshot.revision) {
+			found = `your file says revision ${parsed.revision}`;
+			cause = `${current} It was rewritten after the copy you edited was taken: read the file again and apply your change to its current text, leaving line 1 as it is.`;
+		} else {
+			const fields = [
+				...(parsed.version !== snapshot.version ? ["version"] : []),
+				...(parsed.documentId !== snapshot.documentId ? ["document id"] : []),
+				...(!snapshot.stableDocument && parsed.baselineDigest !== snapshot.baselineDigest ? ["baseline digest"] : []),
+			];
+			found = fields.length > 0
+				? `your file says revision ${parsed.revision}, but its ${fields.join(" and ")} differ${fields.length === 1 ? "s" : ""}`
+				: `your file's line 1 is current, but its block headers belong to another copy of the mirror`;
+			cause = fields.length > 0
+				? `${current} Line 1 was changed or copied from another mirror: restore it exactly and keep the rest of your edit.`
+				: `${current} Read the file again and apply your change to its current text.`;
+		}
+		return rejected(
 			snapshot,
 			beforeEstimate,
-			`Mirror metadata does not match the current context revision (expected revision ${snapshot.revision}, document ${snapshot.documentId.slice(0, 12)}…). ` +
-				`The first line must be exactly: ${metadataLine}`,
+			`Mirror metadata does not match the current context revision (expected revision ${snapshot.revision}, document ${snapshot.documentId.slice(0, 12)}…; ${found}). ` +
+				`${cause} The first line must be exactly: ${metadataLine}`,
 		);
+	};
 	// A file with no current block headers but with framing lines from another document
 	// (or a stale revision) is an old mirror copied back, not a summary: reject it.
 	if (parsed.blocks.length === 0 && hasForeignFraming(editedText, snapshot)) return staleMetadata();

package/src/mirror-store.ts

@@ -14,7 +14,7 @@ export function defaultMirrorParent(): string {
 	return join(stateHome, "opencode-clm", "mirrors");
 }
 
-function safeSessionId(sessionId: string): string {
+export function safeSessionId(sessionId: string): string {
 	const safe = sessionId.replace(/[^a-zA-Z0-9_-]/g, "-").slice(0, 64);
 	return safe || "session";
 }