opencode-clm 0.1.0 → 0.1.1

package/README.md

@@ -56,6 +56,31 @@ option.
 
 Booleans accept `true/false`, `1/0`, `on/off` and `yes/no`.
 
+**Choosing `budget`.** The budget counts the whole request, OpenCode's system prompt and
+tool schemas included. With OpenCode 1.18 and its default tools those take about 17,000
+to 19,000 tokens of every request (measured with provider counts), before the
+conversation starts. A budget must hold that overhead, the `reserve`, and a working margin
+for the conversation; the plugin uses 8,000 tokens, room for the task, a few tool results
+and edits. With the default reserve that gives a minimum of about 19,000 + 2,048 + 8,000 ≈
+29,000 tokens; the default 32,000 clears it. More tools (MCP servers, plugins) or a
+steering document raise the overhead.
+
+When the budget is smaller, the session raises it. On the first request that follows a
+measured reply, the plugin takes the provider's input count minus its own conversation
+estimate as the fixed overhead. It measures only while the conversation is at most a
+quarter of that count, so the estimate's error stays small; a session resumed with a long
+history is measured once its context is short. If the provider reports no usage, the
+plugin's own size estimate stands in until a provider count arrives. If budget − reserve
+leaves less than 8,000 tokens after the overhead, the effective budget becomes overhead +
+8,000 + reserve, never above the model window minus its output limit (uncapped while the
+window is unknown). The plugin then logs a `budget-too-small` event, shows a warning
+toast, and tells the model once. When the window cap leaves less than the margin, the
+notice says so; lower `reserve` or use a model with a larger window. The overhead is
+stored in `state.json`, so the raise holds after a restart, and it is measured once per
+session: switching agent or model, or adding an MCP server, later does not update it.
+`/clm` shows the fixed overhead, the usable budget (budget − reserve − overhead) and the
+effective budget when raised.
+
 A steering document carries context-management strategy (when to compact, what to keep);
 the plugin itself states only the editing protocol. The plugin reads the document once at
 load and appends it to the system prompt; `/clm` shows its name and SHA-256 prefix.
@@ -179,7 +204,7 @@ Each session has a directory `<mirrorDir>/clm-<session id>/` (mode 0700; files 0
 | file | content |
 |---|---|
 | `LIVE_CONTEXT.md` | the mirror |
-| `state.json` | enabled flag, revision, active checkpoint |
+| `state.json` | enabled flag, revision, active checkpoint, measured fixed overhead and budget decision |
 | `annotations.jsonl` | continuity annotations |
 | `events.jsonl` | one line per request, edit, reset, notice and error |
 | `revisions/rN.md` | the mirror text of each accepted revision |

package/index.ts

@@ -238,6 +238,10 @@ export const server: Plugin = async (input: PluginInput, options?: PluginOptions
 			try {
 				const result = await clm.transform(raw);
 				replaceInPlace(raw, result.messages);
+				if (result.alert) {
+					toast(result.alert, "warning");
+					log("warn", result.alert);
+				}
 			} catch (error) {
 				// Fail open: the request goes out with the raw history.
 				await clm.log({ event: "error", message: describe(error), stack: error instanceof Error ? error.stack : undefined });

package/package.json

@@ -1,26 +1,56 @@
 {
   "name": "opencode-clm",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "OpenCode plugin for Context Language Models: the model edits a file mirror of its own context, and the edited mirror becomes its next input.",
   "type": "module",
   "license": "MIT",
   "author": "B Guest",
   "homepage": "https://github.com/bcmyguest/opencode-clm#readme",
-  "bugs": { "url": "https://github.com/bcmyguest/opencode-clm/issues" },
-  "repository": { "type": "git", "url": "git+https://github.com/bcmyguest/opencode-clm.git" },
-  "keywords": ["opencode", "opencode-plugin", "context-management", "context-window", "context-language-models", "clm"],
+  "bugs": {
+    "url": "https://github.com/bcmyguest/opencode-clm/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bcmyguest/opencode-clm.git"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "context-management",
+    "context-window",
+    "context-language-models",
+    "clm"
+  ],
   "main": "./index.ts",
-  "exports": { ".": "./index.ts" },
-  "files": ["index.ts", "src/**/*.ts", "skills/**", "steering/**", "LICENSE", "NOTICE", "README.md", "CHANGELOG.md"],
-  "engines": { "bun": ">=1.2", "opencode": ">=1.18" },
-  "publishConfig": { "access": "public" },
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "src/**/*.ts",
+    "skills/**",
+    "steering/**",
+    "LICENSE",
+    "NOTICE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "bun": ">=1.2",
+    "opencode": ">=1.18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "test": "bun test",
     "typecheck": "tsc --noEmit",
     "check": "tsc --noEmit && bun test",
     "test:e2e": "OPENCODE_CLM_E2E=1 bun test test/e2e"
   },
-  "dependencies": { "@opencode-ai/plugin": "^1.18.34" },
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.18.34"
+  },
   "devDependencies": {
     "@types/bun": "1.3.14",
     "typescript": "5.9.3"

package/src/budget.ts

@@ -39,6 +39,14 @@ export const DEFAULT_BUDGET_POLICY: BudgetPolicyConfig = {
 	remindAtReserve: true,
 };
 
+/**
+ * Room the conversation needs on top of OpenCode's fixed overhead (system prompt and tool
+ * schemas) and the reserve: the pinned task, a few tool results and the model's own edits.
+ * A budget with less room than this makes the overflow guard withhold nearly every tool
+ * result; `budgetFit` then raises the session's effective budget.
+ */
+export const WORKING_MARGIN = 8000;
+
 export interface BudgetReading {
 	/** Effective budget in tokens (config or model window). */
 	budget: number;
@@ -64,6 +72,8 @@ export interface BudgetReading {
 	observedStale?: boolean;
 	/** Where `budget` came from, for status text. */
 	source: "config" | "model-window";
+	/** Set when `budget` was raised above the configured value to cover the fixed overhead (see `budgetFit`). */
+	raisedFrom?: number;
 }
 
 /** A reminder threshold in absolute tokens plus a stable label for re-arming. */
@@ -112,6 +122,115 @@ export function resolveBudget(
 	return undefined;
 }
 
+/** Budget arithmetic for status text, the TUI panel and the budget-too-small check. */
+export interface BudgetFit {
+	/** Budget before any raise (configured, or the model window). */
+	configured: number;
+	reserve: number;
+	/** OpenCode's fixed overhead per request in tokens; undefined until measured. */
+	overhead?: number;
+	/** configured − reserve − overhead: what the conversation gets without a raise (may be negative). */
+	usable?: number;
+	/** True when configured − reserve leaves less than `margin` after the overhead. */
+	tooSmall: boolean;
+	/** overhead + margin + reserve: the smallest budget that leaves the margin. */
+	minimum?: number;
+	/** The budget CLM applies: `configured`, or raised toward `minimum` (capped by `cap`). */
+	effective: number;
+	/** effective − reserve − overhead. */
+	effectiveUsable?: number;
+	raised: boolean;
+	/** True when `cap` stopped the raise short of `minimum`. */
+	capped: boolean;
+	margin: number;
+}
+
+/**
+ * Pure: how the budget compares with OpenCode's fixed overhead. When budget − reserve leaves
+ * less than `margin` after the overhead, the effective budget rises to overhead + margin +
+ * reserve, but never above `cap` (the model window minus its output limit) nor below the
+ * configured budget.
+ */
+export function budgetFit(
+	configured: number,
+	reserve: number,
+	overhead: number | undefined,
+	cap?: number,
+	margin = WORKING_MARGIN,
+): BudgetFit {
+	if (overhead === undefined) {
+		return { configured, reserve, tooSmall: false, effective: configured, raised: false, capped: false, margin };
+	}
+	const usable = configured - reserve - overhead;
+	const minimum = overhead + margin + reserve;
+	const tooSmall = usable < margin;
+	const limit = cap !== undefined && Number.isFinite(cap) && cap > 0 ? cap : Number.POSITIVE_INFINITY;
+	const effective = tooSmall ? Math.max(configured, Math.min(minimum, limit)) : configured;
+	return {
+		configured,
+		reserve,
+		overhead,
+		usable,
+		tooSmall,
+		minimum,
+		effective,
+		effectiveUsable: effective - reserve - overhead,
+		raised: effective > configured,
+		capped: tooSmall && minimum > limit,
+		margin,
+	};
+}
+
+/** Status line for `budgetFit`: fixed overhead, usable budget, and the raise if any. */
+export function budgetFitLine(fit: BudgetFit): string {
+	if (fit.overhead === undefined) return "fixed overhead (system prompt + tool schemas): not measured yet";
+	const parts = [
+		`fixed overhead (system prompt + tool schemas) ${formatTokens(fit.overhead)} tok`,
+		`usable ${formatTokens(fit.usable!)} tok (budget ${formatTokens(fit.configured)} − reserve ${formatTokens(fit.reserve)} − overhead)`,
+	];
+	if (fit.raised) {
+		parts.push(
+			`effective budget ${formatTokens(fit.effective)} tok (raised${fit.capped ? ", capped by the model window" : ""}; usable ${formatTokens(fit.effectiveUsable!)} tok)`,
+		);
+	} else if (fit.tooSmall) {
+		parts.push("too small, and the model window allows no raise");
+	}
+	return parts.join(" · ");
+}
+
+/**
+ * The one-time model notice for a budget that cannot hold OpenCode's fixed overhead plus a
+ * working margin. Text written for this package.
+ */
+export function budgetTooSmallNoticeText(fit: BudgetFit): string {
+	const head =
+		`[CLM BUDGET] The configured budget of ${formatTokens(fit.configured)} tokens is too small for this session: ` +
+		`OpenCode's system prompt and tool schemas take about ${formatTokens(fit.overhead ?? 0)} tokens of every request, ` +
+		`which leaves ${formatTokens(Math.max(0, fit.usable ?? 0))} tokens for the conversation after the ${formatTokens(fit.reserve)}-token reserve.`;
+	const left = formatTokens(Math.max(0, fit.effectiveUsable ?? 0));
+	if (fit.capped) {
+		const raise = fit.raised ? `CLM raised this session's budget to ${formatTokens(fit.effective)} tokens, the most the model window allows, ` : "The model window allows no larger budget, ";
+		return (
+			`${head} ${raise}which still leaves only ${left} tokens for the conversation. ` +
+			"The overflow guard will hold back most tool results: keep the context mirror short and read files in small parts."
+		);
+	}
+	return (
+		`${head} CLM raised this session's budget to ${formatTokens(fit.effective)} tokens, ` +
+		`about ${left} tokens for the conversation. ` +
+		"Budget reminders and the overflow guard count against the raised budget from now on."
+	);
+}
+
+/** The user-facing toast for the same case: what happened and what to change. */
+export function budgetTooSmallAlertText(fit: BudgetFit): string {
+	const head = `Budget ${formatTokens(fit.configured)} is too small: OpenCode's system prompt and tools take ~${formatTokens(fit.overhead ?? 0)} tokens.`;
+	if (fit.capped) {
+		return `${head} The model window limits this session to ${formatTokens(fit.effective)}, leaving ~${formatTokens(Math.max(0, fit.effectiveUsable ?? 0))} for the conversation; lower reserve, use fewer tools, or use a model with a larger context window.`;
+	}
+	return `${head} Raised to ${formatTokens(fit.effective)} for this session; set budget to at least ${formatTokens(fit.minimum!)}.`;
+}
+
 export function budgetTiers(policy: BudgetPolicyConfig, budget: number, reserve: number): BudgetTier[] {
 	const tiers: BudgetTier[] = policy.remindAtFractions.map((fraction) => ({
 		label: `${Math.round(fraction * 100)}%`,
@@ -176,8 +295,11 @@ function calibrated(reading: Pick<BudgetReading, "calibration">): boolean {
 
 /** One line for status text: budget, estimate, and observation, each labelled. */
 export function budgetSummaryLine(reading: BudgetReading): string {
+	const origin = reading.raisedFrom !== undefined
+		? `raised from ${formatTokens(reading.raisedFrom)} to cover the fixed overhead`
+		: reading.source === "config" ? "configured" : "model window";
 	const parts = [
-		`budget ${formatTokens(reading.budget)} tok (${reading.source === "config" ? "configured" : "model window"}, reserve ${formatTokens(reading.reserve)})`,
+		`budget ${formatTokens(reading.budget)} tok (${origin}, reserve ${formatTokens(reading.reserve)})`,
 		`estimated next request ${formatTokens(reading.estimated)}${calibrated(reading) ? ` (×${reading.calibration!.toFixed(2)} calibrated)` : ""}`,
 	];
 	parts.push(

package/src/clm.ts

@@ -37,12 +37,16 @@ import { appendFile, mkdir, 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,9 +67,11 @@ 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";
@@ -94,6 +100,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 +120,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 +201,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
@@ -215,6 +231,7 @@ export class ClmSession {
 		const loaded = await loadLiveContextState(store.directory);
 		const session = new ClmSession(sessionID, store, settings, loaded);
 		if (loaded.warning) await session.log({ event: "state-warning", warning: loaded.warning });
+		if (loaded.repaired) await session.log({ event: "state-repaired", message: loaded.repaired });
 		return session;
 	}
 
@@ -250,8 +267,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 +298,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 -------------------------------------------------------------------
 
 	/**
@@ -420,6 +533,7 @@ export class ClmSession {
 					revision,
 					checkpoint,
 					lastOutcome: { kind: "applied", message: applied, ...sizes, at },
+					...keptFields(state),
 				};
 			});
 		} catch (error) {
@@ -489,6 +603,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;
@@ -536,6 +651,9 @@ 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;
 
 		let projection = applyProjection(source, this.state.checkpoint);
 		// A late or repeated compaction signal must not swallow a later revert: rebase only
@@ -675,6 +793,7 @@ export class ClmSession {
 			this.calibrator.record(systemTokens + toolTokens + conversation, 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");
@@ -694,7 +813,7 @@ export class ClmSession {
 			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`. */
@@ -709,6 +828,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/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/presentation.ts

@@ -8,7 +8,7 @@
  * document.
  */
 
-import { budgetSummaryLine, formatTokens, type BudgetReading } from "./budget.ts";
+import { budgetFitLine, budgetSummaryLine, formatTokens, type BudgetFit, type BudgetReading } from "./budget.ts";
 import type { EditGate } from "./policy.ts";
 import { steeringStatusLine, type SteeringDocument } from "./steering.ts";
 
@@ -86,6 +86,8 @@ export interface ClmStatus {
 	guard: "withhold" | "off";
 	/** Latest budget reading; undefined before the first request. */
 	reading?: BudgetReading;
+	/** Fixed overhead, usable and effective budget (`budgetFit`); undefined while the budget is unknown. */
+	fit?: BudgetFit;
 	/** Model context window in tokens, when known. */
 	modelWindow?: number;
 	/** The accepted revision now in effect, if any. */
@@ -112,6 +114,7 @@ export function statusText(status: ClmStatus): string {
 			? `${budgetSummaryLine(status.reading)} · model window ${status.modelWindow ? formatTokens(status.modelWindow) : "unknown"}`
 			: "budget: unknown until the first request",
 	];
+	if (status.fit) lines.push(budgetFitLine(status.fit));
 	const checkpoint = status.checkpoint;
 	lines.push(
 		checkpoint

package/src/state.ts

@@ -24,6 +24,24 @@ export interface LiveContextOutcome {
 	at: string;
 }
 
+/**
+ * The once-per-session measurement of OpenCode's fixed overhead (system prompt and tool
+ * schemas). Its presence means the budget-too-small check has run; the session then derives
+ * its effective budget from `overhead` (clm.ts), so a raise survives a restart.
+ */
+export interface BudgetCheck {
+	/** Fixed overhead per request, tokens. */
+	overhead: number;
+	/** `provider`: the provider's count minus the conversation estimate; `estimate`: chars/4 sizes. */
+	source: "provider" | "estimate";
+	/** Budget and reserve in force when the check ran, and what it decided. */
+	configured: number;
+	reserve: number;
+	effective: number;
+	raised: boolean;
+	at: string;
+}
+
 export interface LiveContextState {
 	version: 1;
 	enabled: boolean;
@@ -31,12 +49,15 @@ export interface LiveContextState {
 	revision: number;
 	checkpoint?: ProjectionCheckpoint;
 	lastOutcome?: LiveContextOutcome;
+	budgetCheck?: BudgetCheck;
 }
 
 export interface LoadedState {
 	state: LiveContextState;
 	/** Set when a state file existed but could not be used; the state is then initial. */
 	warning?: string;
+	/** Set when an invalid optional field was dropped and the rest of the state kept. */
+	repaired?: string;
 }
 
 const SOURCE_KINDS = new Set(["kept", "edited", "removed", "restored", "normalized"]);
@@ -137,6 +158,24 @@ function isOutcome(value: unknown): value is LiveContextOutcome {
 	);
 }
 
+function isBudgetCheck(value: unknown): value is BudgetCheck {
+	if (!isObject(value)) return false;
+	return (
+		isCount(value.overhead) &&
+		(value.source === "provider" || value.source === "estimate") &&
+		isCount(value.configured) &&
+		isCount(value.reserve) &&
+		isCount(value.effective) &&
+		typeof value.raised === "boolean" &&
+		typeof value.at === "string"
+	);
+}
+
+/** The fields every state rewrite carries over (revision changes keep the budget check). */
+export function keptFields(state: LiveContextState): Pick<LiveContextState, "budgetCheck"> {
+	return state.budgetCheck ? { budgetCheck: state.budgetCheck } : {};
+}
+
 export function isLiveContextState(value: unknown): value is LiveContextState {
 	if (!isObject(value)) return false;
 	const state = value as Partial<LiveContextState>;
@@ -147,7 +186,8 @@ export function isLiveContextState(value: unknown): value is LiveContextState {
 		// Accept writes the checkpoint and the state with the same revision; reset moves past it.
 		(state.checkpoint === undefined ||
 			(isProjectionCheckpoint(state.checkpoint) && state.checkpoint.revision === state.revision)) &&
-		(state.lastOutcome === undefined || isOutcome(state.lastOutcome))
+		(state.lastOutcome === undefined || isOutcome(state.lastOutcome)) &&
+		(state.budgetCheck === undefined || isBudgetCheck(state.budgetCheck))
 	);
 }
 
@@ -162,6 +202,7 @@ export function resetProjectionState(
 		enabled: state.enabled,
 		revision: state.revision + 1,
 		lastOutcome: { kind: "reset", message, at },
+		...keptFields(state),
 	};
 }
 
@@ -191,10 +232,16 @@ export async function loadLiveContextState(directory: string): Promise<LoadedSta
 			warning: `${path} has unsupported version ${JSON.stringify(parsed.version)}; starting clean.`,
 		};
 	}
+	// A malformed budget check costs only itself: the session re-measures the overhead.
+	let repaired: string | undefined;
+	if (isObject(parsed) && parsed.budgetCheck !== undefined && !isBudgetCheck(parsed.budgetCheck)) {
+		delete parsed.budgetCheck;
+		repaired = `${path} had an invalid budgetCheck; dropped it, the fixed overhead is measured again.`;
+	}
 	if (!isLiveContextState(parsed)) {
 		return { state: initialLiveContextState(), warning: `${path} has an invalid shape; starting clean.` };
 	}
-	return { state: parsed };
+	return repaired ? { state: parsed, repaired } : { state: parsed };
 }
 
 /**