opencode-clm 0.3.0 → 0.4.1

package/NOTICE

@@ -22,7 +22,7 @@ Derived from pi-clm (code and model-facing text, adapted for OpenCode):
   src/steering.ts               src/steering.ts
   src/types.ts                  src/types.ts
   steering/house-brief.md       steering/house-brief.md (byte-identical copy)
-  skills/clm-context/SKILL.md   src/skills/live-context/SKILL.md
+  .agents/skills/clm-context/SKILL.md   src/skills/live-context/SKILL.md
   src/panel/timeline.ts         src/timeline.ts (context chart and its zoom levels)
   src/panel/diff.ts             src/diff.ts (side-by-side diff)
   src/panel/view.ts             src/viewer.ts (panel pages)
@@ -45,5 +45,5 @@ Context Language Models
   Two design choices follow its harness: the fit/shrink edit gate and the default
   25/50/75% reminder steps. pi-clm's skill guidance on edit cost (batch edits, mind the
   tail below an edit, write detailed summaries), carried into
-  skills/clm-context/SKILL.md, covers the same points as the harness prompt in
+  .agents/skills/clm-context/SKILL.md, covers the same points as the harness prompt in
   different words.

package/README.md

@@ -30,9 +30,10 @@ opencode plugin -g opencode-clm     # global: opencode.json(c) and tui.json in ~
 ```
 
 The package holds two plugins: the server plugin (`index.ts`: mirror, edits, budget,
-`/clm`, `/clm-compact`) and the TUI plugin (`tui.ts`: the `/clm` panel). `opencode plugin`
-writes the spec to both files. By hand, add it to both `plugin` lists; options go on the
-`opencode.json` entry only, and the TUI plugin reads them from there:
+`/clm`, `/clm-compact`) and the TUI plugin (`tui.ts`: the `/clm` panel). Install both:
+without the TUI plugin there is no panel, and each `/clm` command costs a model turn.
+`opencode plugin` writes the spec to both files. By hand, add it to both `plugin` lists;
+options go on the `opencode.json` entry only, and the TUI plugin reads them from there:
 
 ```jsonc
 // opencode.json
@@ -47,17 +48,19 @@ writes the spec to both files. By hand, add it to both `plugin` lists; options g
 |---------|--------------|
 | `/clm` | open the panel: **overview** (context size per request + every accepted edit) <br><img src="https://raw.githubusercontent.com/bcmyguest/opencode-clm/main/.github/images/overview.png" alt="The overview page: context size per request, with the requests after which the model edited its context" width="720"> <br> **input** (what the next request contains) · **edits** (per-revision side-by-side diff) <br><img src="https://raw.githubusercontent.com/bcmyguest/opencode-clm/main/.github/images/edits.png" alt="The edits page: a tool result before and after the model shortened it" width="720"> |
 | `/clm overview` / `input` / `edits` / `settings` | open the panel on that page (`timeline` and `edit` also work); without the TUI plugin, print it as text |
-| `/clm status` | a toast: on or off, revision, last request size, budget, fixed overhead, last outcome |
+| `/clm status` | a toast: on or off, revision, last request size, budget, fixed overhead, last outcome; `mode notices-only` when set |
 | `/clm config` | open **settings**; `/clm config <setting> <value>` changes one, `/clm config reset` drops this session's changes <br><img src="https://raw.githubusercontent.com/bcmyguest/opencode-clm/main/.github/images/settings.png" alt="The settings page: sizes, files, and every setting" width="720"> |
 | `/clm-compact [instructions]` | ask the model to compact its own context now; anything you add (e.g. what to keep) is passed along. The result shows on the **edits** page |
 | `/clm on` / `off` / `reset` / `path` | enable, use raw context, discard the accepted revision, show the mirror's path |
-| `/clm budget [value]` | show or change the budget, the same as `/clm config budget` |
+| `/clm budget [value]` | show or change the budget, the same as `/clm config budget`: a share of the model window (default `50%`), tokens (`64k`), or `window` |
+| `/clm config mode notices-only` | keep the budget notices, reminders and overflow guard but take away editing: no mirror, no protocol prompt, raw history. For comparing "telling the model its budget" with "letting it edit"; `/clm config mode edit` switches back |
 
 With the TUI plugin, typed `/clm …` lines run in the TUI and cost no model turn, and Tab
 completes their subcommands, setting names and values;
 `/clm reset` is handed to the server plugin, also without a turn. The right of the
 session prompt shows `clm <size> / <budget> · r<revision>` (`~` before the size marks an
-estimate the provider has not confirmed; `clm off · r<revision>` while CLM is off).
+estimate the provider has not confirmed; `clm off · r<revision>` while CLM is off;
+`clm notices-only <size> / <budget> · r<revision>` in notices-only mode).
 
 In the panel: `1–4` or `Tab` switch pages, `← →` step through the overview's markers or
 the edits page's revisions, `z` zooms the chart, `Enter` opens the selection, `r`
@@ -89,13 +92,20 @@ notes: 49 requests, 16 accepted edits, 0 rejected. The server reused cache after
 and prefilled 11,240 tokens in total, where a prefix-only cache would have prefilled
 214,585 (95% less); requests of 20–48k tokens prefilled 34–3,523 tokens each.
 
+**Nine agent tasks in OpenCode** (find and fix, opencode-clm 0.3.0, 1 run each), CLM
+at a 32k budget vs CLM off: both solved 9/9; CLM took 55.5 s per task vs 91.3 s and
+prefilled 2,868 tokens vs 7,317 on average. CLM accepted only 1 edit in 9 runs because no
+task came near the budget, so most of the gain looks behavioural: told its budget, the
+model makes fewer tool calls. One CLM run read files outside its workspace and is not
+comparable.
+
 Flash-Next was not trained for CLM, so it makes more edit mistakes than the paper's
 trained models. Hosted APIs are untested.
 
 ## Docs
 
 - [How it works](docs/how-it-works.md) — the mirror, what runs without the model, the panel, model and server support, safety.
-- [Configuration](docs/configuration.md) — every setting (editing, budget, reserve, reminders, gate, guard, compaction, cap, steering, one-tool, trailer, compact-prompt, reasoning), plugin options and environment variables.
+- [Configuration](docs/configuration.md) — every setting (editing, budget, reserve, reminders, reminder-cooldown, gate, guard, compaction, cap, steering, mode, one-tool, trailer, compact-prompt, reasoning), plugin options and environment variables.
 - [Architecture](docs/architecture.md) — modules, session files, design notes, known limitations.
 - [Development](docs/development.md) — setup, checks, the integration suites, releasing.
 

package/index.ts

@@ -504,7 +504,7 @@ export const server: Plugin = async (input: PluginInput, options?: PluginOptions
 	async function configCommand(clm: ClmSession, words: string[]): Promise<string> {
 		const [name, ...valueWords] = words;
 		const { base, effective } = clm.settingsValues();
-		const format = { modelWindow: clm.limits.context };
+		const format = { modelWindow: clm.limits.context, modelOutput: clm.limits.output };
 		if (!name) return settingsText(base, effective, format, clm.settingsWarning);
 		if (name.toLowerCase() === "reset" && valueWords.length === 0) {
 			await clearSettings(clm);
@@ -522,12 +522,13 @@ export const server: Plugin = async (input: PluginInput, options?: PluginOptions
 		const budget = fallbackBudget(clm.settings, clm.limits);
 		const model = buildPanelModel(files, budget ? { budget } : {});
 		model.enabled = clm.enabled;
+		if (clm.noticesOnly) model.noticesOnly = true;
 		// No mirror: name why, never the temporary directory (the text reaches the model).
 		if (clm.mirrorUnavailable !== undefined) {
 			model.mirrorUnavailable = clm.mirrorUnavailable;
 			model.mirrorPath = `unavailable (${clm.mirrorUnavailable})`;
 		}
-		const format = { ...(clm.limits.context ? { modelWindow: clm.limits.context } : {}) };
+		const format = { ...(clm.limits.context ? { modelWindow: clm.limits.context } : {}), ...(clm.limits.output ? { modelOutput: clm.limits.output } : {}) };
 		model.settings = settingsView(clm.settingsValues(), model, { format, ...(clm.settingsWarning ? { warning: clm.settingsWarning } : {}) });
 		return panelPageText(model, page);
 	}
@@ -550,7 +551,8 @@ export const server: Plugin = async (input: PluginInput, options?: PluginOptions
 				return text;
 			}
 			case "path":
-				return clm.mirrorUnavailable === undefined ? `CLM mirror: ${clm.mirrorPath}` : `CLM mirror: unavailable (${clm.mirrorUnavailable})`;
+				if (clm.mirrorUnavailable !== undefined) return `CLM mirror: unavailable (${clm.mirrorUnavailable})`;
+				return clm.noticesOnly ? "CLM mirror: not used (mode notices-only)" : `CLM mirror: ${clm.mirrorPath}`;
 			case "on":
 			case "off": {
 				// The same override the TUI and `/clm config editing` write.
@@ -561,6 +563,11 @@ export const server: Plugin = async (input: PluginInput, options?: PluginOptions
 						? "CLM is on for this session. No mirror is available: requests carry the raw history plus the continuity annotations."
 						: "CLM is off for this session: requests carry the raw history.";
 				}
+				if (clm.noticesOnly) {
+					return argument === "on"
+						? "CLM is on for this session in notices-only mode: requests carry the raw history plus the budget notices; the model cannot edit its context."
+						: "CLM is off for this session: requests carry the raw history and no notices.";
+				}
 				return argument === "on"
 					? "CLM is on for this session: the mirror is refreshed before the next request."
 					: "CLM is off for this session: requests carry the raw history and the mirror is no longer read.";
@@ -823,9 +830,11 @@ export const server: Plugin = async (input: PluginInput, options?: PluginOptions
 			if (!clm.enabled || clm.mirrorUnavailable !== undefined) return;
 			const limit = (hookInput.model as { limit?: { context?: number; input?: number; output?: number } } | undefined)?.limit;
 			if (limit) clm.limits = { context: limit.context || undefined, output: limit.output || undefined, ...(limit.input ? { input: limit.input } : {}) };
-			const sections = [systemGuidance(clm.mirrorPath, clm.resolvedBudget()?.budget)];
+			if (hookInput.model) clm.limitsKnown = true;
+			// notices-only: no protocol section (there is no mirror); the steering document stays.
+			const sections = clm.noticesOnly ? [] : [systemGuidance(clm.mirrorPath, clm.resolvedBudget()?.budget)];
 			if (clm.steering) sections.push(steeringPromptSection(clm.steering));
-			output.system.push(sections.join("\n\n"));
+			if (sections.length > 0) output.system.push(sections.join("\n\n"));
 			clm.scope = { ...clm.scope, systemTokens: clm.textTokens(output.system.join("\n")) };
 		},
 
@@ -872,7 +881,7 @@ export const server: Plugin = async (input: PluginInput, options?: PluginOptions
 				if (cancelled && usable !== undefined) {
 					await clm.log({ event: "compaction-cancelled", reason: "threshold", setting: cancelled.by, count: cancelled.count, usable });
 					if (cancelled.by === "off") {
-						clm.queueNotice(thresholdCancelledNoticeText(clm.mirrorPath));
+						clm.queueNotice(thresholdCancelledNoticeText(clm.noticesOnly ? undefined : clm.mirrorPath));
 						toast(thresholdCancelledText(cancelled.count, usable));
 					} else toast(thresholdPausedText(cancelled.count, usable, clm.guardLimit()));
 				}
@@ -945,7 +954,7 @@ export const server: Plugin = async (input: PluginInput, options?: PluginOptions
 			// Automatic compaction only (manual /compact does not reach this hook).
 			const overflow = hookInput.overflow === true;
 			await clm.log({ event: "native-compaction", reason: overflow ? "overflow" : "threshold", setting: clm.settings.compaction });
-			toast(nativeCompactionText(overflow, clm.settings.compaction));
+			toast(nativeCompactionText(overflow, clm.settings.compaction, clm.noticesOnly));
 		},
 
 		async event({ event }) {
@@ -986,9 +995,11 @@ export const server: Plugin = async (input: PluginInput, options?: PluginOptions
 					toast("The provider rejected the request as too long, and OpenCode's automatic compaction is off. Run /compact.", "warning");
 					return;
 				}
-				clm.queueNotice(overflowNotCompactedText(clm.mirrorPath));
+				clm.queueNotice(overflowNotCompactedText(clm.noticesOnly ? undefined : clm.mirrorPath));
 				await clm.log({ event: "overflow-not-compacted", setting: clm.settings.compaction });
-				toast("The provider rejected the request as too long, and OpenCode's automatic compaction is off. Edit the mirror or run /compact.", "warning");
+				toast(clm.noticesOnly
+					? "The provider rejected the request as too long, and OpenCode's automatic compaction is off. Run /compact."
+					: "The provider rejected the request as too long, and OpenCode's automatic compaction is off. Edit the mirror or run /compact.", "warning");
 				return;
 			}
 			if (event.type !== "session.compacted") return;
@@ -1054,7 +1065,15 @@ export const server: Plugin = async (input: PluginInput, options?: PluginOptions
 					// pi-clm's compactCommand: nothing for the model to edit, so nothing is asked of it.
 					toast(`The context mirror is unavailable, so the model cannot edit its context (${clm.mirrorUnavailable}).`, "warning");
 					text = relay("[CLM] The context mirror is unavailable, so the model cannot edit its context.");
-				} else text = await compactCommand(clm, hookInput.sessionID, argument);
+				} else {
+					await clm.refreshSettings();
+					if (clm.noticesOnly) {
+						// The compaction prompt asks for a mirror edit; notices-only has no mirror.
+						const message = "CLM runs in notices-only mode for this session, so the model cannot edit its context. Switch with /clm config mode edit.";
+						toast(message, "warning");
+						text = relay(`[CLM] ${message}`);
+					} else text = await compactCommand(clm, hookInput.sessionID, argument);
+				}
 			} catch (error) {
 				const message = `/${hookInput.command} failed: ${describe(error)}`;
 				toast(message, "error");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-clm",
-  "version": "0.3.0",
+  "version": "0.4.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",
@@ -31,7 +31,7 @@
     "index.ts",
     "tui.ts",
     "src/**/*.ts",
-    "skills/**",
+    ".agents/skills/clm-context/**",
     "steering/**",
     "LICENSE",
     "NOTICE",

package/src/budget.ts

@@ -21,22 +21,39 @@
 export interface BudgetPolicyConfig {
 	/**
 	 * Context budget in tokens the reminders are measured against. Advisory: requests are
-	 * never blocked or rolled back. `undefined` means "use the model context window".
+	 * never blocked or rolled back. When undefined, `contextFraction` decides; when both are
+	 * undefined, the budget is the model context window (the `window` setting).
 	 */
 	contextBudget?: number;
+	/**
+	 * Budget as a fraction (0 < f <= 1) of the model window minus its output limit, used when
+	 * `contextBudget` is undefined (the `50%` setting). With the window unknown the budget is
+	 * `FALLBACK_BUDGET`.
+	 */
+	contextFraction?: number;
 	/** Generation headroom reserved below the budget. The final reminder fires at budget - reserve. */
 	reserve: number;
 	/** Fractions of the budget at which escalating reminders fire (0 < f < 1), ascending. */
 	remindAtFractions: readonly number[];
 	/** Whether to fire the final "budget - reserve" reminder. */
 	remindAtReserve: boolean;
+	/**
+	 * Share of the budget (0 <= f < 1) the context must grow past its size after an accepted
+	 * edit before percentage reminders fire again; 0 turns the cooldown off. The
+	 * budget − reserve reminder is exempt.
+	 */
+	reminderCooldown: number;
 }
 
+/** Budget when a percentage budget meets an unknown model window. */
+export const FALLBACK_BUDGET = 32_000;
+
 export const DEFAULT_BUDGET_POLICY: BudgetPolicyConfig = {
-	contextBudget: 32000,
+	contextFraction: 0.5,
 	reserve: 2048,
 	remindAtFractions: [0.25, 0.5, 0.75],
 	remindAtReserve: true,
+	reminderCooldown: 0.1,
 };
 
 /**
@@ -70,23 +87,44 @@ export interface BudgetReading {
 	 * describes a context that no longer exists. The notice says so.
 	 */
 	observedStale?: boolean;
-	/** Where `budget` came from, for status text. */
-	source: "config" | "model-window";
+	/**
+	 * Where `budget` came from, for status text: `config` (a token count), `model-window`
+	 * (the window, or a token count capped by it), `window-fraction` (`fraction` of the
+	 * window), `fallback` (`FALLBACK_BUDGET`: a percentage with the window unknown).
+	 */
+	source: BudgetSource;
+	/** The configured fraction, for `window-fraction` and `fallback`. */
+	fraction?: number;
 	/** Set when `budget` was raised above the configured value to cover the fixed overhead (see `budgetFit`). */
 	raisedFrom?: number;
 }
 
+export type BudgetSource = "config" | "model-window" | "window-fraction" | "fallback";
+
 /** A reminder threshold in absolute tokens plus a stable label for re-arming. */
 export interface BudgetTier {
 	label: string;
 	tokens: number;
 }
 
+/**
+ * Defaults plus `overrides`, validated. An own `contextBudget` key without an own
+ * `contextFraction` key replaces the default fraction (`{ contextBudget: undefined }` still
+ * means "the model window"); a defined `contextBudget` always clears `contextFraction`.
+ */
 export function resolveBudgetPolicy(overrides: Partial<BudgetPolicyConfig> | undefined): BudgetPolicyConfig {
 	const merged: BudgetPolicyConfig = { ...DEFAULT_BUDGET_POLICY, ...(overrides ?? {}) };
+	const budgetGiven = overrides !== undefined && Object.hasOwn(overrides, "contextBudget");
+	const fractionGiven = overrides !== undefined && Object.hasOwn(overrides, "contextFraction");
+	if (merged.contextBudget !== undefined || (budgetGiven && !fractionGiven)) delete merged.contextFraction;
 	if (merged.contextBudget !== undefined && (!Number.isFinite(merged.contextBudget) || merged.contextBudget <= 0)) {
 		throw new Error(`contextBudget must be a positive number of tokens, got ${String(merged.contextBudget)}`);
 	}
+	if (merged.contextFraction !== undefined && (!Number.isFinite(merged.contextFraction) || merged.contextFraction <= 0 || merged.contextFraction > 1)) {
+		throw new Error(`contextFraction must be in (0, 1], got ${String(merged.contextFraction)}`);
+	}
+	if (merged.contextFraction === undefined) delete merged.contextFraction;
+	if (merged.contextBudget === undefined) delete merged.contextBudget;
 	if (!Number.isFinite(merged.reserve) || merged.reserve < 0) {
 		throw new Error(`reserve must be a nonnegative number of tokens, got ${String(merged.reserve)}`);
 	}
@@ -97,25 +135,35 @@ export function resolveBudgetPolicy(overrides: Partial<BudgetPolicyConfig> | und
 		}
 	}
 	fractions.sort((left, right) => left - right);
+	if (!Number.isFinite(merged.reminderCooldown) || merged.reminderCooldown < 0 || merged.reminderCooldown >= 1) {
+		throw new Error(`reminderCooldown must be in [0, 1) (0 = off), got ${String(merged.reminderCooldown)}`);
+	}
 	return { ...merged, remindAtFractions: fractions };
 }
 
 /**
- * Effective budget: the configured budget (default 32,000), capped by the model's context
- * window minus its output allowance when that is smaller. `undefined` contextBudget means
- * "use the window". An output limit that is not finite, <= 0, or >= the window is ignored.
+ * Effective budget against the model window minus its output allowance (the base): a token
+ * count, capped by the base when that is smaller; else `contextFraction` of the base
+ * (default 50%), or `FALLBACK_BUDGET` with the window unknown; else the base itself. An
+ * output limit that is not finite, <= 0, or >= the window is ignored. Undefined only for
+ * the `window` setting with the window unknown.
  */
 export function resolveBudget(
 	policy: BudgetPolicyConfig,
 	modelContextWindow: number | undefined,
 	modelOutputLimit = 0,
-): Pick<BudgetReading, "budget" | "reserve" | "source"> | undefined {
+): Pick<BudgetReading, "budget" | "reserve" | "source" | "fraction"> | undefined {
 	const window = modelContextWindow !== undefined && Number.isFinite(modelContextWindow) && modelContextWindow > 0
 		? modelContextWindow - (Number.isFinite(modelOutputLimit) && modelOutputLimit > 0 && modelOutputLimit < modelContextWindow ? modelOutputLimit : 0)
 		: undefined;
 	if (policy.contextBudget !== undefined && (window === undefined || policy.contextBudget <= window)) {
 		return { budget: policy.contextBudget, reserve: Math.min(policy.reserve, policy.contextBudget), source: "config" };
 	}
+	const fraction = policy.contextBudget === undefined ? policy.contextFraction : undefined;
+	if (fraction !== undefined) {
+		const budget = window !== undefined ? Math.max(1, Math.floor(window * fraction)) : FALLBACK_BUDGET;
+		return { budget, reserve: Math.min(policy.reserve, budget), source: window !== undefined ? "window-fraction" : "fallback", fraction };
+	}
 	if (window !== undefined) {
 		return { budget: window, reserve: Math.min(policy.reserve, window), source: "model-window" };
 	}
@@ -202,7 +250,7 @@ export function budgetFitLine(fit: BudgetFit): string {
  * 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 {
+export function budgetTooSmallNoticeText(fit: BudgetFit, options: NoticeOptions = {}): 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, ` +
@@ -212,7 +260,9 @@ export function budgetTooSmallNoticeText(fit: BudgetFit): string {
 		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."
+			(options.noticesOnly
+				? "The overflow guard will hold back most tool results: read files in small parts."
+				: "The overflow guard will hold back most tool results: keep the context mirror short and read files in small parts.")
 		);
 	}
 	return (
@@ -252,35 +302,93 @@ export function governingTokens(reading: Pick<BudgetReading, "estimated">): numb
 	return reading.estimated;
 }
 
+/** The outcome of one `BudgetTracker.check`. */
+export interface BudgetCheck {
+	/** The highest newly crossed tier to announce, if any. */
+	tier?: BudgetTier;
+	/** Tiers crossed during a reminder cooldown: consumed without a notice. */
+	suppressed: BudgetTier[];
+	/** Governing size at which the active cooldown ends; undefined without one. */
+	cooldownUntil?: number;
+}
+
 /**
  * Escalating, re-arming tier tracker over absolute token thresholds. Re-derives its state
  * when the tier set changes (for example after the budget changes).
+ *
+ * Reminder cooldown: `editAccepted()` marks an accepted context edit. The next check records
+ * the governing size E; until the size reaches E + cooldown × budget, crossed percentage tiers
+ * are marked fired without a notice (consumed, not deferred). The budget-reserve tier is
+ * exempt. A later accepted edit restarts the cooldown; a reset, `clearCooldown` or a tier change ends it.
  */
 export class BudgetTracker {
 	private fired = new Set<string>();
 	private tierKey = "";
+	/** An edit was accepted and the next check has not yet recorded its size. */
+	private cooldownPending = false;
+	/** Governing size recorded after the last accepted edit, while the cooldown runs. */
+	private cooldownStart: number | undefined;
 
 	reset(): void {
 		this.fired.clear();
+		this.clearCooldown();
+	}
+
+	/** End the reminder cooldown; fired tiers stay fired. */
+	clearCooldown(): void {
+		this.cooldownPending = false;
+		this.cooldownStart = undefined;
+	}
+
+	/** Start (or restart) the reminder cooldown from the next reading. */
+	editAccepted(): void {
+		this.cooldownPending = true;
+		this.cooldownStart = undefined;
 	}
 
 	/** Returns the highest newly crossed tier, or undefined when nothing new fired. */
-	observe(reading: BudgetReading, tiers: readonly BudgetTier[]): BudgetTier | undefined {
+	observe(reading: BudgetReading, tiers: readonly BudgetTier[], cooldown = 0): BudgetTier | undefined {
+		return this.check(reading, tiers, cooldown).tier;
+	}
+
+	/** `observe` with the tiers a cooldown suppressed. `cooldown`: share of the budget, 0 = off. */
+	check(reading: BudgetReading, tiers: readonly BudgetTier[], cooldown = 0): BudgetCheck {
 		const key = tiers.map((tier) => `${tier.label}:${tier.tokens}`).join("|");
 		if (key !== this.tierKey) {
 			this.tierKey = key;
 			this.fired.clear();
+			this.cooldownStart = undefined;
 		}
 		const tokens = governingTokens(reading);
 		this.fired = new Set([...this.fired].filter((label) => {
 			const tier = tiers.find((candidate) => candidate.label === label);
 			return tier !== undefined && tokens >= tier.tokens;
 		}));
-		const crossed = tiers.filter((tier) => tokens >= tier.tokens && !this.fired.has(tier.label));
-		if (crossed.length === 0) return undefined;
+		if (this.cooldownPending) {
+			this.cooldownPending = false;
+			this.cooldownStart = tokens;
+		}
+		let cooldownUntil: number | undefined;
+		if (this.cooldownStart !== undefined) {
+			const until = this.cooldownStart + cooldown * reading.budget;
+			// cooldown 0 (off, possibly set mid-cooldown) ends it outright.
+			if (cooldown > 0 && tokens < until) cooldownUntil = until;
+			else this.cooldownStart = undefined;
+		}
+		let crossed = tiers.filter((tier) => tokens >= tier.tokens && !this.fired.has(tier.label));
+		const suppressed: BudgetTier[] = [];
+		if (cooldownUntil !== undefined) {
+			for (const tier of crossed) {
+				if (tier.label === "budget-reserve") continue;
+				suppressed.push(tier);
+				this.fired.add(tier.label);
+			}
+			crossed = crossed.filter((tier) => tier.label === "budget-reserve");
+		}
+		if (crossed.length === 0) return { suppressed, cooldownUntil };
 		const top = crossed[crossed.length - 1]!;
 		for (const tier of tiers) if (tier.tokens <= top.tokens) this.fired.add(tier.label);
-		return top;
+		return { tier: top, suppressed, cooldownUntil };
 	}
 }
 
@@ -293,11 +401,27 @@ function calibrated(reading: Pick<BudgetReading, "calibration">): boolean {
 	return reading.calibration !== undefined && reading.calibration > 1.005;
 }
 
+/** `0.5` → `50%`, `0.125` → `12.5%`. */
+export function formatPercent(fraction: number): string {
+	return `${Number((fraction * 100).toFixed(2))}%`;
+}
+
+/** Short origin label of a budget: `configured`, `model window`, `50% of model window`, … */
+export function budgetOrigin(reading: Pick<BudgetReading, "source" | "fraction">): string {
+	const percent = reading.fraction !== undefined ? formatPercent(reading.fraction) : "";
+	switch (reading.source) {
+		case "config": return "configured";
+		case "model-window": return "model window";
+		case "window-fraction": return `${percent} of model window`;
+		case "fallback": return `fallback, ${percent} of an unknown model window`;
+	}
+}
+
 /** 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";
+		: budgetOrigin(reading);
 	const parts = [
 		`budget ${formatTokens(reading.budget)} tok (${origin}, reserve ${formatTokens(reading.reserve)})`,
 		`estimated next request ${formatTokens(reading.estimated)}${calibrated(reading) ? ` (×${reading.calibration!.toFixed(2)} calibrated)` : ""}`,
@@ -310,17 +434,24 @@ export function budgetSummaryLine(reading: BudgetReading): string {
 	return parts.join(" · ");
 }
 
+/** Model-facing notice variants. `noticesOnly`: the session runs `mode notices-only`, so no text may point the model at a mirror. */
+export interface NoticeOptions {
+	noticesOnly?: boolean;
+}
+
 /**
  * The model-facing reminder. States the estimate and the provider count separately, the
  * budget and the tokens left, the mirror path, and, from the third tier up, what the
  * overflow guard does above `overflowLimit` (default budget - reserve). Pass `null` when the
- * guard is off: the notice then leaves the guard out.
+ * guard is off: the notice then leaves the guard out. `noticesOnly` keeps the measurement,
+ * the budget, the tokens left and the guard sentence, and drops every invitation to edit.
  */
 export function budgetNoticeText(
 	reading: BudgetReading,
 	tier: BudgetTier,
 	mirrorPath: string | undefined,
 	overflowLimit: number | null = reading.budget - reading.reserve,
+	options: NoticeOptions = {},
 ): string {
 	const governing = governingTokens(reading);
 	const remaining = Math.max(0, reading.budget - governing);
@@ -334,6 +465,19 @@ export function budgetNoticeText(
 	const overflow = overflowLimit === null
 		? ""
 		: ` Above ${formatTokens(overflowLimit)} tokens the overflow guard holds back the oldest new tool results and saves them to files.`;
+	if (options.noticesOnly) {
+		const fraction = tier.tokens / reading.budget;
+		if (tier.label === "budget-reserve") {
+			return (
+				`[CLM BUDGET] Context is at ${formatTokens(governing)} of a ${formatTokens(reading.budget)}-token budget ` +
+				`(${measurement}). Only ${formatTokens(remaining)} tokens remain, which is inside the ${formatTokens(reading.reserve)}-token generation reserve.${overflow}`
+			);
+		}
+		const base =
+			`[CLM BUDGET] Context crossed ${tier.label} of a ${formatTokens(reading.budget)}-token budget: ${measurement}. ` +
+			`${formatTokens(remaining)} tokens remain; the final reminder comes at ${formatTokens(reading.budget - reading.reserve)} tokens.`;
+		return fraction <= 0.5 ? base : `${base}${overflow}`;
+	}
 	if (tier.label === "budget-reserve") {
 		return (
 			`[CLM BUDGET] Context is at ${formatTokens(governing)} of a ${formatTokens(reading.budget)}-token budget ` +