opencode-clm 0.2.0 → 0.4.0

package/src/clm.ts

@@ -7,6 +7,12 @@
  * during step k is read back and committed at the start of step k+1's transform, right
  * before the request it affects. As in pi-clm, the file content at that moment wins.
  *
+ * `mode notices-only` (`noticesOnly`) skips steps 1, 2 and 4: the accepted revision, if any,
+ * stays in state.json but is not applied, nothing is rendered or committed, and the request
+ * carries the raw history (reasoning view, cap and guard still apply) with every notice.
+ * Switching back to `edit` applies the kept revision again while it still matches the
+ * history; a mismatch then takes the usual restore-or-reset path.
+ *
  *   transform(raw)  0. pinned = everything up to and including the first user message;
  *                      source = flatten(rest), the raw prefix a checkpoint digests
  *                   1. commit: read the mirror; if it differs from the last render,
@@ -54,17 +60,20 @@ import {
 	AnnotationStore,
 	ContinuitySizeTracker,
 	continuitySizeNoticeText,
+	forkAnnotations,
 	formatContinuityMessage,
 	type ContinuityBlockSource,
 	type LiveContextAnnotation,
 } from "./continuity.ts";
 import { classifyMirrorToolCall } from "./mirror-guard.ts";
-import { MirrorStore } from "./mirror-store.ts";
+import { MirrorDirectoryError, MirrorStore } from "./mirror-store.ts";
 import { capObservations } from "./observation.ts";
 import { flatten, noteMessage, unflatten, withoutReasoning, type OcInfo, type OcMessage } from "./opencode.ts";
+import { sizeTrailer } from "./compaction.ts";
 import { applyOverflowGuard, overflowGuardLimit, overflowNoticeText } from "./overflow.ts";
 import type { ClmStatus } from "./presentation.ts";
-import { applyProjection, createProjectionCheckpoint, type ProjectionCheckpoint } from "./projection.ts";
+import { applyProjection, createProjectionCheckpoint, digestSourceContent, type ProjectionCheckpoint } from "./projection.ts";
+import { clearHistory, loadHistory, remapProjection, saveHistoryEntry, type HistoryEntry } from "./history.ts";
 import type { ClmSettings } from "./settings.ts";
 import {
 	keptFields,
@@ -86,6 +95,8 @@ export interface ModelLimits {
 	context?: number;
 	/** Model output limit, tokens; subtracted from the window by `resolveBudget`. */
 	output?: number;
+	/** Model input limit, tokens, when the provider sets one; only OpenCode's threshold reads it (src/compaction.ts). */
+	input?: number;
 }
 
 /** Sizes of the request parts the plugin does not see in the messages hook. */
@@ -96,6 +107,11 @@ export interface RequestScope {
 	toolTokens?: number;
 }
 
+/** Toast when edits keep being dropped (pi `compositionWarningText`, reworded for OpenCode). */
+export const COMPOSITION_WARNING = "CLM edits keep being dropped: OpenCode's history changed between consecutive requests. " +
+	"Another plugin that rewrites already-sent messages (experimental.chat.messages.transform) is the usual cause; " +
+	"load opencode-clm before it (earlier in the `plugin` list), or turn CLM off for this session with /clm off.";
+
 export interface TransformResult {
 	/** The messages to send; the caller writes them into OpenCode's array in place. */
 	messages: OcMessage[];
@@ -104,8 +120,10 @@ 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. */
+	/** User-facing warning for a toast (budget too small, composition warning, ignored saved settings); set on one request only. */
 	alert?: string;
+	/** User-facing errors for toasts: the mirror could not be read or refreshed, a revision could not be saved. */
+	errors?: string[];
 }
 
 export interface MirrorCheck {
@@ -188,6 +206,12 @@ export class ClmSession {
 	accepted = 0;
 	rejected = 0;
 	limits: ModelLimits = {};
+	/**
+	 * Set once the system transform has seen the model, with or without a window. Until then
+	 * a fallback budget is provisional: the guard, fit gate, reminders and trailer stand down.
+	 * A model that reports no window keeps the fallback, which then applies in full.
+	 */
+	limitsKnown = false;
 	scope: RequestScope = {};
 	/** Set by `experimental.session.compacting`: the next transform carries OpenCode's compaction input. */
 	compacting = false;
@@ -196,6 +220,23 @@ export class ClmSession {
 	 * `experimental.compaction.autocontinue` hook); the next transform rebases onto the summary.
 	 */
 	compacted = false;
+	/**
+	 * Set by the plugin when OpenCode's session metadata names another session as the origin
+	 * (a fork, `Session.fork` copies metadata). The first transform restores the newest of the
+	 * origin's checkpoints whose source the forked history still contains, then clears it.
+	 */
+	forkOrigin?: { sessionID: string; directory: string; /** The fork's creation time (ms), when OpenCode reported it. */ created?: number };
+	/** The origin's annotations from cloned session metadata (a fork without a mirror); used when the origin's store yields none. */
+	forkPersisted?: LiveContextAnnotation[];
+	/** Set when a fork's first request copied annotations in; the plugin then persists them (no mirror). */
+	annotationsImported = false;
+	/**
+	 * Why no mirror directory could be used, set by the plugin (M1). The store then sits in a
+	 * private temporary directory the model is never told about; requests carry the raw
+	 * history plus the continuity annotations and their size notice, as pi-clm does when its
+	 * mirror store fails to initialize.
+	 */
+	mirrorUnavailable?: string;
 	/** What the last transform rendered; the next transform commits the mirror against it. */
 	baseline?: Baseline;
 	/** The snapshot now in the mirror file; continuity tools resolve block ids against it. */
@@ -205,9 +246,21 @@ export class ClmSession {
 	requests = 0;
 
 	private pendingNotices: string[] = [];
+	/** Errors for the user (toasts), returned with the next transform result. */
+	private pendingErrors: string[] = [];
+	/** The mirror could not be written last time; its error toast is not repeated until a write succeeds. */
+	private refreshFailing = false;
+	/** Why the steering document in the settings did not load, for snapshot.json (the panel). */
+	steeringError?: 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;
+	/** The composition warning toast is shown once per session (pi: `compositionWarned`). */
+	private compositionWarned = false;
+	/** User-facing warnings for the next transform result (`alert`). */
+	private pendingAlerts: string[] = [];
+	/** The settings warning last shown to the user, so a new or changed one toasts once. */
+	private shownSettingsWarning?: string;
 	/**
 	 * Per-process seed of the stable document id. Fresh on every open, so a document id never
 	 * repeats even when a corrupt state file resets the revision counter to 0.
@@ -244,11 +297,14 @@ export class 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).
+	 * document the base settings name, already loaded; undefined when it failed to load at start
+	 * (each session then retries the path and records the error in `settingsWarning`).
 	 */
 	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 store = await MirrorStore.create(sessionID, settings.mirrorDir).catch((error: unknown) => {
+			throw new MirrorDirectoryError(settings.mirrorDir, error);
+		});
 		const loaded = await loadLiveContextState(store.directory);
 		const session = new ClmSession(sessionID, store, settings, loaded, options.steering);
 		if (loaded.warning) await session.log({ event: "state-warning", warning: loaded.warning });
@@ -262,6 +318,11 @@ export class ClmSession {
 		return this.overrides.editing ?? this.state.enabled;
 	}
 
+	/** `mode notices-only`: notices and the guard run, the model cannot edit its context. */
+	get noticesOnly(): boolean {
+		return this.settings.mode === "notices-only";
+	}
+
 	/** Base and effective values, for the settings table. */
 	settingsValues(): { base: SettingsValues; effective: SettingsValues } {
 		return {
@@ -277,7 +338,7 @@ export class ClmSession {
 			base: this.baseSettings,
 			baseEditing: this.state.enabled,
 			projectDirectory,
-			format: { modelWindow: this.limits.context },
+			format: { modelWindow: this.limits.context, modelOutput: this.limits.output },
 		};
 	}
 
@@ -309,29 +370,51 @@ export class ClmSession {
 		} catch (error) {
 			warnings.push(`ignored saved settings: ${describe(error)}`);
 			overrides = {};
-			staged = { settings: this.baseSettings, ...(this.baseSteering ? { steering: this.baseSteering } : {}) };
+			// The base settings resolved at load; staging them again keeps a base steering error.
+			staged = stageSettings(this.baseSettings, {}, { strict: false, loaded: this.baseSteering });
+		}
+		// Only warnings about saved settings toast here. The base steering document failing
+		// again (no override names another path) already toasted once at load (index.ts).
+		const alerting = [...warnings];
+		if (staged.steeringError) {
+			const warning = `steering document not loaded: ${staged.steeringError}`;
+			warnings.push(warning);
+			if (staged.settings.steeringPath !== this.baseSettings.steeringPath) alerting.push(warning);
 		}
-		if (staged.steeringError) warnings.push(`steering document not loaded: ${staged.steeringError}`);
+		this.steeringError = staged.steeringError;
 		await this.activateSettings(staged, overrides);
 		this.settingsWarning = warnings.length > 0 ? warnings.join("; ") : undefined;
+		const alert = alerting.length > 0 ? alerting.join("; ") : undefined;
+		if (alert && alert !== this.shownSettingsWarning) {
+			this.pendingAlerts.push(`saved settings partly ignored: ${alert}`);
+		}
+		this.shownSettingsWarning = alert;
 	}
 
 	private async activateSettings(staged: StagedSettings, overrides: ClmOverrides): Promise<void> {
 		const before = this.settings.budget;
 		const after = staged.settings.budget;
 		const wasEnabled = this.enabled;
+		const wasMode = this.settings.mode;
 		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 ||
+		if (before.contextBudget !== after.contextBudget || before.contextFraction !== after.contextFraction || before.reserve !== after.reserve ||
 			before.remindAtFractions.join(",") !== after.remindAtFractions.join(",") || before.remindAtReserve !== after.remindAtReserve) {
 			this.tracker.reset();
 		}
 		if (wasEnabled !== this.enabled) {
 			this.baseline = undefined;
+			this.tracker.clearCooldown();
 			if (!this.enabled) this.continuitySize.observe(0);
 		}
+		if (wasMode !== this.settings.mode) {
+			// The render the baseline holds no longer describes what the model is sent.
+			this.baseline = undefined;
+			this.lastSnapshot = undefined;
+			this.tracker.clearCooldown();
+		}
 		if (changed) await this.log({ event: "settings", overrides });
 	}
 
@@ -341,6 +424,34 @@ export class ClmSession {
 
 	// ---- measurement -------------------------------------------------------------------
 
+	/**
+	 * 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.
+	 */
+	private scopeSize(): { measuredOverhead?: number; scopeTokens: number } {
+		const { systemTokens, toolTokens } = this.scope;
+		const measuredOverhead = this.state.budgetCheck?.source === "provider"
+			? Math.max(this.state.budgetCheck.overhead, (systemTokens ?? 0) + (toolTokens ?? 0))
+			: undefined;
+		return { ...(measuredOverhead !== undefined ? { measuredOverhead } : {}), scopeTokens: measuredOverhead ?? this.calibrator.apply((systemTokens ?? 0) + (toolTokens ?? 0)) };
+	}
+
+	/**
+	 * `/clm-compact`: about how large the next request would be, from the stored history
+	 * (as OpenCode sends it, see `filterCompacted`) through the accepted revision (continuity and notices not
+	 * counted). Undefined when the history holds no message to compact.
+	 */
+	idleEstimate(raw: OcMessage[]): number | undefined {
+		const pinned = pinnedCount(raw);
+		const source = flatten(raw.slice(pinned));
+		if (source.length === 0) return undefined;
+		const projection = applyProjection(source, this.state.checkpoint);
+		const effective = projection.valid ? projection.messages : source;
+		return this.scopeSize().scopeTokens + this.estimate(flatten(raw.slice(0, pinned))) + this.estimate(effective);
+	}
+
 	/** Uncalibrated tokens of a text: chars/4 × estimateFactor. */
 	textTokens(text: string): number {
 		return Math.ceil((text.length / CHARS_PER_TOKEN) * this.settings.estimateFactor);
@@ -368,10 +479,10 @@ export class ClmSession {
 	}
 
 	/**
-	 * The budget in force: the configured one (or the model window), raised when the
+	 * The budget in force: the resolved one (`resolveBudget`), 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 {
+	resolvedBudget(): Pick<BudgetReading, "budget" | "reserve" | "source" | "fraction" | "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());
@@ -380,7 +491,7 @@ export class ClmSession {
 
 	/** 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;
+		return resolveBudget({ ...this.settings.budget, contextBudget: undefined, contextFraction: undefined }, this.limits.context, this.limits.output)?.budget;
 	}
 
 	/**
@@ -392,10 +503,19 @@ export class ClmSession {
 		return base ? budgetFit(base.budget, base.reserve, this.state.budgetCheck?.overhead, this.windowCap()) : undefined;
 	}
 
-	/** budget − reserve, or undefined while the budget is unknown. */
+	/**
+	 * budget − reserve: the limit the overflow guard enforces. Undefined while the budget is
+	 * unknown or a fallback (`FALLBACK_BUDGET`, model window not yet known): the guard then
+	 * withholds nothing.
+	 */
+	/** A fallback budget read before the model's limits arrived (see `limitsKnown`). */
+	private provisional(resolved: Pick<BudgetReading, "source">): boolean {
+		return resolved.source === "fallback" && !this.limitsKnown;
+	}
+
 	guardLimit(): number | undefined {
 		const resolved = this.resolvedBudget();
-		return resolved ? overflowGuardLimit(resolved.budget, resolved.reserve) : undefined;
+		return resolved && !this.provisional(resolved) ? overflowGuardLimit(resolved.budget, resolved.reserve) : undefined;
 	}
 
 	/**
@@ -469,7 +589,7 @@ export class ClmSession {
 			...(previous ? { replaces: previous.source, previousOverhead: previous.overhead } : {}),
 		});
 		if (!warn) return undefined;
-		this.pendingNotices.push(budgetTooSmallNoticeText(fit));
+		this.pendingNotices.push(budgetTooSmallNoticeText(fit, { noticesOnly: this.noticesOnly }));
 		return budgetTooSmallAlertText(fit);
 	}
 
@@ -511,6 +631,7 @@ export class ClmSession {
 	async setEnabled(enabled: boolean): Promise<void> {
 		await this.updateState((state) => ({ ...state, enabled }));
 		this.baseline = undefined;
+		this.tracker.clearCooldown();
 		if (!enabled) this.continuitySize.observe(0);
 	}
 
@@ -520,6 +641,9 @@ export class ClmSession {
 		this.baseline = undefined;
 		this.tracker.reset();
 		this.continuitySize.reset();
+		// The user dropped the edits on purpose: a later revert must not bring one back. Queued
+		// behind any history write in flight; writes queued later see no checkpoint and skip.
+		await this.historyTask(() => clearHistory(this.store.directory));
 		await this.log({ event: "reset", revision: next.revision, reason });
 	}
 
@@ -560,7 +684,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.enabled) return undefined;
+		if (!this.settings.enabled || !this.enabled || this.noticesOnly) return undefined;
 		if (classifyMirrorToolCall(tool, args ?? {}, cwd, this.mirrorPath) !== "write") return undefined;
 		const check = this.validateMirror(this.store.readSync());
 		if (!check) return undefined;
@@ -570,8 +694,39 @@ export class ClmSession {
 			: `[CLM] Mirror edit would be refused: ${check.message} Correct the file before this step ends, or the context stays as it is.`;
 	}
 
+	/**
+	 * `setting trailer`: the size trailer for one tool result (the last reading plus the
+	 * result's calibrated estimate, against the budget in force); undefined when off or while
+	 * the budget is unknown or a provisional fallback.
+	 */
+	sizeTrailer(output: string): string | undefined {
+		if (!this.settings.enabled || !this.enabled || !this.settings.trailer || this.mirrorUnavailable !== undefined) return undefined;
+		const resolved = this.resolvedBudget();
+		// A fallback budget is a placeholder: "~N of 32,000" would report a limit nothing enforces.
+		if (!resolved || this.provisional(resolved)) return undefined;
+		return sizeTrailer(this.lastReading?.estimated ?? 0, this.calibrator.apply(this.textTokens(output)), resolved.budget);
+	}
+
+	/**
+	 * Before an OpenCode compaction (`experimental.session.compacting`): commit the edit the
+	 * model made in its final step. No request followed that step (e.g. the user typed
+	 * /compact next), so the commit at the start of a transform has not run; without this the
+	 * compaction would summarize the pre-edit context and the edit would be lost.
+	 */
+	async commitBeforeCompaction(): Promise<void> {
+		await this.refreshSettings();
+		if (!this.settings.enabled || !this.enabled || this.noticesOnly) return;
+		await this.commit();
+	}
+
+	/** Adds a notice to the next request (e.g. from a bus event). */
+	queueNotice(text: string): void {
+		this.pendingNotices.push(text);
+	}
+
 	/** The mirror block the model last saw, for continuity annotations. */
 	blockSource(blockId: string): ContinuityBlockSource | undefined {
+		if (this.noticesOnly) throw new Error("CLM runs in notices-only mode: there is no context mirror, so no block can be annotated.");
 		const snapshot = this.lastSnapshot;
 		const block = snapshot?.blocks.find((candidate) => candidate.id === blockId);
 		return snapshot && block ? { message: block.source, revision: snapshot.revision } : undefined;
@@ -587,6 +742,7 @@ export class ClmSession {
 			text = await this.store.read();
 		} catch (error) {
 			this.pendingNotices.push(`[CLM] Could not read the mirror: ${describe(error)}`);
+			this.pendingErrors.push(`could not read the mirror, the edit was not applied: ${describe(error)}`);
 			return;
 		}
 		if (text === undefined || text.trim() === baseline.snapshot.text.trim()) return;
@@ -639,9 +795,12 @@ export class ClmSession {
 		} catch (error) {
 			// Persist before activate: an unsaved revision would vanish on restart.
 			this.pendingNotices.push(`[CLM] Revision ${revision} was not applied: it could not be saved (${describe(error)}); the previous context stays in effect.`);
+			this.pendingErrors.push(`revision ${revision} could not be saved, the previous context stays in effect: ${describe(error)}`);
 			return;
 		}
 		this.accepted += 1;
+		this.tracker.editAccepted();
+		await this.remember({ version: 1, checkpoint, contentDigest: digestSourceContent(baseline.rawMessages) });
 		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);
@@ -746,6 +905,7 @@ export class ClmSession {
 			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 } } : {}),
+			...(this.steeringError ? { steeringError: this.steeringError } : {}),
 			sizes: { estimated: input.estimated, ...(input.observed !== undefined ? { observedPrevious: input.observed } : {}) },
 			input: {
 				raw: input.raw,
@@ -812,6 +972,172 @@ export class ClmSession {
 		await this.log({ event: "compacted", revision: next.revision, previous, summary: summaryId, written });
 	}
 
+	// ---- checkpoint history (revert and fork) ------------------------------------------
+
+	/** History writes and clears run one at a time (`/clm reset` runs outside the transform queue). */
+	private historyQueue: Promise<void> = Promise.resolve();
+
+	private historyTask(task: () => Promise<void>): Promise<void> {
+		const run = this.historyQueue.then(task).catch(() => undefined);
+		this.historyQueue = run;
+		return run;
+	}
+
+	/**
+	 * Add an accepted checkpoint to `checkpoints/`. Best effort: the revision is already saved.
+	 * Skipped when the checkpoint is no longer the active one by the time the write runs (a
+	 * `/clm reset` came in between), so a reset edit never lands in the history.
+	 */
+	private remember(entry: HistoryEntry): Promise<void> {
+		return this.historyTask(async () => {
+			if (this.state.checkpoint?.revision !== entry.checkpoint.revision) return;
+			await saveHistoryEntry(this.store.directory, entry)
+				.catch((error: unknown) => this.log({ event: "history-error", revision: entry.checkpoint.revision, error: describe(error) }));
+		});
+	}
+
+	/**
+	 * Make `entry`'s projection, with `projected` standing for `source`, the next revision.
+	 * Persisted before it takes effect, like an accepted edit.
+	 */
+	private async activateRestored(
+		entry: HistoryEntry,
+		source: readonly LiveContextMessage[],
+		projected: readonly LiveContextMessage[],
+		describeRestore: (revision: number) => string,
+	): Promise<boolean> {
+		const at = new Date().toISOString();
+		const old = entry.checkpoint;
+		const revision = this.state.revision + 1;
+		let checkpoint: ProjectionCheckpoint;
+		try {
+			checkpoint = createProjectionCheckpoint({
+				revision,
+				sourceMessages: source,
+				projectedMessages: projected,
+				beforeEstimate: old.beforeEstimate,
+				afterEstimate: old.afterEstimate,
+				estimateUnit: old.estimateUnit,
+				createdAt: at,
+				...(old.editTrace ? { editTrace: old.editTrace } : {}),
+			});
+		} catch {
+			return false;
+		}
+		const message = describeRestore(revision);
+		try {
+			await this.updateState((state) => {
+				if (state.revision + 1 !== revision) throw new Error("the session state changed while the revision was restored");
+				return {
+					version: 1,
+					enabled: state.enabled,
+					revision,
+					checkpoint,
+					lastOutcome: { kind: "applied", message, beforeEstimate: old.beforeEstimate, afterEstimate: old.afterEstimate, estimateUnit: old.estimateUnit, at },
+					...keptFields(state),
+				};
+			});
+		} catch {
+			return false;
+		}
+		this.tracker.reset();
+		await this.remember({ version: 1, checkpoint, contentDigest: entry.contentDigest });
+		this.pendingNotices.push(`[CLM] ${message} The mirror shows it.`);
+		return true;
+	}
+
+	/**
+	 * The active revision no longer fits the history (a revert cut into its prefix): restore
+	 * the newest older checkpoint that still fits, as pi-clm restores the checkpoint of the
+	 * branch `/tree` selects. False when none fits; the caller then resets.
+	 */
+	private async restoreAfterMismatch(source: readonly LiveContextMessage[], reason: string): Promise<boolean> {
+		const dropped = this.state.checkpoint?.revision;
+		const { entries, ignored } = await loadHistory(this.store.directory);
+		if (ignored.length > 0) await this.log({ event: "history-ignored", files: ignored });
+		for (const entry of entries) {
+			if (entry.checkpoint.revision === dropped) continue;
+			const candidate = applyProjection(source, entry.checkpoint);
+			if (!candidate.valid) continue;
+			const from = entry.checkpoint.revision;
+			const prefix = source.slice(0, entry.checkpoint.sourceMessageCount);
+			const restored = await this.activateRestored(entry, prefix, entry.checkpoint.projectedMessages, (revision) =>
+				`Revision ${dropped} no longer matches OpenCode's history: ${reason.replace(/\.\s*$/, "")}; restored revision ${from}, which still does, as revision ${revision}.`);
+			if (!restored) return false;
+			await this.log({ event: "restored", revision: this.state.revision, from, dropped, reason });
+			return true;
+		}
+		return false;
+	}
+
+	/**
+	 * First request of a forked session: find the newest origin checkpoint whose source the
+	 * fork's history starts with (compared without message ids, which the fork renews) and
+	 * restore it with the ids mapped to the fork's.
+	 */
+	private async restoreFromFork(origin: { sessionID: string; directory: string }, source: readonly LiveContextMessage[]): Promise<boolean> {
+		const { entries, ignored } = await loadHistory(origin.directory);
+		if (ignored.length > 0) await this.log({ event: "history-ignored", origin: origin.sessionID, files: ignored });
+		for (const entry of entries) {
+			const count = entry.checkpoint.sourceMessageCount;
+			if (count > source.length) continue;
+			const prefix = source.slice(0, count);
+			if (digestSourceContent(prefix) !== entry.contentDigest) continue;
+			const from = entry.checkpoint.revision;
+			const restored = await this.activateRestored(entry, prefix, remapProjection(entry.checkpoint, prefix), (revision) =>
+				`This session is a fork of ${origin.sessionID}; restored its revision ${from} as revision ${revision}.`);
+			if (!restored) return false;
+			await this.log({ event: "restored", revision: this.state.revision, from, origin: origin.sessionID });
+			return true;
+		}
+		return false;
+	}
+
+	/**
+	 * First request of a forked session: copy the origin's annotations made up to the fork
+	 * point, their sources re-pointed at the fork's messages (`forkAnnotations`). The fork
+	 * point is the newest completion among the messages created before the fork itself
+	 * (OpenCode keeps message times in a fork); newer messages are the fork's own.
+	 */
+	private async copyForkAnnotations(origin: { sessionID: string; directory: string; created?: number }, raw: readonly OcMessage[], effective: readonly LiveContextMessage[]): Promise<void> {
+		let annotations: LiveContextAnnotation[] = [];
+		try {
+			annotations = await new AnnotationStore(origin.directory).list();
+		} catch (error) {
+			await this.log({ event: "annotations-unreadable", origin: origin.sessionID, error: describe(error) });
+		}
+		// Without a mirror the origin's directory is usually out of reach too: fall back to the
+		// set the origin kept in OpenCode's metadata, which the fork cloned (index.ts).
+		if (annotations.length === 0) annotations = this.forkPersisted ?? [];
+		this.forkPersisted = undefined;
+		if (annotations.length === 0) return;
+		let cutoff: number | undefined;
+		for (const { info } of raw) {
+			const created = Number(info.time?.created ?? 0);
+			if (origin.created !== undefined && created >= origin.created) continue;
+			const end = Number(info.time?.completed ?? 0) || created;
+			if (cutoff === undefined || end > cutoff) cutoff = end;
+		}
+		const copied = forkAnnotations(annotations, effective, { sessionId: this.sessionID, ...(cutoff !== undefined ? { cutoff } : {}) });
+		try {
+			const written = await this.annotations.importAll(copied);
+			// Without the fork's creation time the fork's own new messages count too, so origin
+			// annotations made between the fork and its first request are carried as well.
+			if (written > 0) {
+				this.annotationsImported = true;
+				await this.log({
+					event: "annotations-forked",
+					origin: origin.sessionID,
+					count: written,
+					mapped: copied.filter((annotation) => annotation.source.sessionId === this.sessionID).length,
+					cutoff: origin.created === undefined ? "unbounded" : cutoff ?? null,
+				});
+			}
+		} catch (error) {
+			await this.log({ event: "annotations-fork-error", origin: origin.sessionID, error: describe(error) });
+		}
+	}
+
 	private async loadAnnotations(): Promise<LiveContextAnnotation[]> {
 		try {
 			return await this.annotations.list();
@@ -821,13 +1147,47 @@ export class ClmSession {
 		}
 	}
 
+	/**
+	 * Without a mirror (`mirrorUnavailable`): the raw history, then the continuity message and
+	 * its size notice. Nothing is projected, rendered or measured; queued notices name the
+	 * mirror, so they are dropped. pi-clm src/index.ts `context` handler, `!store` branch.
+	 */
+	private async transformWithoutMirror(raw: OcMessage[]): Promise<TransformResult> {
+		this.baseline = undefined;
+		this.compacted = false;
+		this.pendingNotices = [];
+		if (this.compacting) {
+			this.compacting = false;
+			return { messages: raw, notices: [] };
+		}
+		this.requests += 1;
+		const origin = this.forkOrigin;
+		this.forkOrigin = undefined;
+		if (origin) await this.copyForkAnnotations(origin, raw, flatten(raw));
+		const continuity = formatContinuityMessage({ annotations: await this.loadAnnotations(), effectiveMessages: flatten(raw) });
+		const tokens = continuity ? this.textTokens(continuity) : 0;
+		const notices = this.continuitySize.observe(tokens) ? [continuitySizeNoticeText(tokens)] : [];
+		const context = this.context(raw);
+		const messages = [
+			...raw,
+			...(continuity ? [noteMessage(continuity, "continuity", context)] : []),
+			...(notices.length > 0 ? [noteMessage(notices.join("\n\n"), `notice:${this.requests}`, context)] : []),
+		];
+		this.lastRequest = { rawMessages: raw.length, sentMessages: messages.length, mirrorBlocks: 0 };
+		const errors = this.pendingErrors;
+		this.pendingErrors = [];
+		return { messages, notices, ...(errors.length > 0 ? { errors } : {}) };
+	}
+
 	private async transformNow(raw: OcMessage[]): Promise<TransformResult> {
 		await this.refreshSettings();
 		if (!this.settings.enabled || !this.enabled) {
 			this.baseline = undefined;
 			this.compacting = false;
-			return { messages: raw, notices: [] };
+			return { messages: raw, notices: [], ...this.drainAlerts() };
 		}
+		if (this.mirrorUnavailable !== undefined) return await this.transformWithoutMirror(raw);
+		const noticesOnly = this.noticesOnly;
 		const pinned = pinnedCount(raw);
 		const pinnedMessages = raw.slice(0, pinned);
 		const context = this.context(raw);
@@ -835,17 +1195,26 @@ export class ClmSession {
 		// OpenCode's compaction passes a head slice of the history through this hook. Apply
 		// the accepted revision when it still covers that slice; never commit, render,
 		// notify or reset (the slice is shorter than the history the checkpoint covers).
+		// A pending edit was committed by `commitBeforeCompaction` just before.
 		if (this.compacting) {
 			this.compacting = false;
+			// notices-only: the summary is made from the history the model was sent, the raw one.
+			if (noticesOnly) return { messages: raw, notices: [], ...this.drainAlerts() };
 			const projection = applyProjection(flatten(raw.slice(pinned)), this.state.checkpoint);
-			if (!projection.valid || !this.state.checkpoint) return { messages: raw, notices: [] };
-			return { messages: [...pinnedMessages, ...unflatten(projection.messages, context)], notices: [] };
+			if (!projection.valid || !this.state.checkpoint) return { messages: raw, notices: [], ...this.drainAlerts() };
+			return { messages: [...pinnedMessages, ...unflatten(projection.messages, context)], notices: [], ...this.drainAlerts() };
 		}
 
-		await this.commit();
+		if (noticesOnly) {
+			// No render to commit against; a mirror written meanwhile is never applied.
+			this.baseline = undefined;
+			this.lastSnapshot = undefined;
+		} else await this.commit();
 		this.requests += 1;
-		const compacted = this.compacted;
-		this.compacted = false;
+		// notices-only leaves a compaction signal pending: back in `edit`, the kept revision
+		// rebases onto the summary as it would have at the time.
+		const compacted = noticesOnly ? false : this.compacted;
+		if (!noticesOnly) this.compacted = false;
 
 		// The raw source prefix is digested as flattened, before any view, cap or guard.
 		const source = flatten(raw.slice(pinned));
@@ -858,23 +1227,36 @@ export class ClmSession {
 		// overhead (built-in tool schemas) as undercounting; start calibration over.
 		if (measured?.source === "provider") this.calibrator.reset();
 
-		let projection = applyProjection(source, this.state.checkpoint);
+		// notices-only: the kept revision is ignored, not dropped (see the header comment).
+		let projection = applyProjection(source, noticesOnly ? undefined : this.state.checkpoint);
 		// A late or repeated compaction signal must not swallow a later revert: rebase only
 		// onto a summary the active checkpoint does not already cover.
 		const summaryId = compacted ? compactionSummaryId(raw) : undefined;
 		const rebase = summaryId !== undefined && !projection.valid && this.state.checkpoint !== undefined &&
 			!this.state.checkpoint.sourceIds.includes(summaryId);
-		if (rebase) {
+		if (noticesOnly) {
+			// Raw history: nothing to rebase, restore or reset.
+		} else if (rebase) {
 			await this.rebaseAfterCompaction(summaryId);
 			projection = applyProjection(source, undefined);
+		} else if (!projection.valid && (await this.restoreAfterMismatch(source, projection.reason))) {
+			// A revert cut into the active revision's prefix; an older revision still fits.
+			this.invalidationStreak = 0;
+			projection = applyProjection(source, this.state.checkpoint);
 		} else if (!projection.valid) {
 			const dropped = this.state.checkpoint?.revision;
+			// The edit the cooldown measures from no longer applies.
+			this.tracker.clearCooldown();
 			this.invalidationStreak += 1;
 			const reason = projection.reason;
 			await this.updateState((state) => resetProjectionState(state, reason), true).catch(() => undefined);
 			let notice = `[CLM] Revision ${dropped} was dropped because OpenCode's history changed under it: ${projection.reason} The mirror now shows the stored history.`;
 			if (this.invalidationStreak >= 2) {
 				notice += " This happened on consecutive requests; edits keep being dropped until the start of the history stops changing.";
+				if (!this.compositionWarned) {
+					this.compositionWarned = true;
+					this.pendingAlerts.push(COMPOSITION_WARNING);
+				}
 			}
 			this.pendingNotices.push(notice);
 			await this.log({ event: "projection-reset", revision: dropped, reason: projection.reason });
@@ -882,28 +1264,33 @@ export class ClmSession {
 		} else if (this.state.checkpoint) {
 			this.invalidationStreak = 0;
 		}
-		const checkpoint = this.state.checkpoint;
+		const origin = this.forkOrigin;
+		this.forkOrigin = undefined;
+		if (origin && !noticesOnly && !this.state.checkpoint && this.state.revision === 0 && (await this.restoreFromFork(origin, source))) {
+			projection = applyProjection(source, this.state.checkpoint);
+		}
+		const checkpoint = noticesOnly ? undefined : this.state.checkpoint;
 		const suffixLength = projection.valid ? projection.suffix.length : 0;
 
 		let effective = projection.messages;
 		if (!this.settings.reasoning) effective = withoutReasoning(effective);
 		effective = capObservations(effective, this.settings.observationCap);
 
+		if (origin) await this.copyForkAnnotations(origin, raw, effective);
 		const annotations = await this.loadAnnotations();
 		const continuityText = (messages: LiveContextMessage[]) =>
 			formatContinuityMessage({ annotations, effectiveMessages: messages });
 		const pinnedTokens = this.estimate(flatten(pinnedMessages));
 		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.
+		// Model limits arrive one request late, so the first request of a process reads the
+		// FALLBACK_BUDGET placeholder. Withholding, reminding or refusing an edit against it is
+		// undone on the next request (a prompt-cache miss, a spurious notice, an edit the real
+		// budget would accept), so none acts on a fallback: `guardLimit()` is undefined, which
+		// also leaves the fit gate unlimited, as with no budget at all.
+		const limit = this.guardLimit();
+		const provisional = resolved !== undefined && this.provisional(resolved);
 		const { systemTokens, toolTokens } = this.scope;
-		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 { measuredOverhead, scopeTokens } = this.scopeSize();
 		const excluded = measuredOverhead !== undefined ? [] : [
 			...(systemTokens === undefined ? ["the system prompt"] : []),
 			...(toolTokens === undefined ? ["tool schemas"] : []),
@@ -925,7 +1312,7 @@ export class ClmSession {
 			if (guarded.withheld.length > 0) {
 				effective = guarded.messages;
 				withheldCount = guarded.withheld.length;
-				this.pendingNotices.push(overflowNoticeText(guarded, limit));
+				this.pendingNotices.push(overflowNoticeText(guarded, limit, { noticesOnly }));
 				await this.log({
 					event: "overflow-guard",
 					withheld: guarded.withheld.map((record) => ({ id: record.toolCallId, tokens: record.tokens, file: record.file })),
@@ -940,27 +1327,33 @@ export class ClmSession {
 			this.pendingNotices.push(continuitySizeNoticeText(this.textTokens(continuity ?? "")));
 		}
 
-		const snapshot = renderContextDocument(effective, {
+		// notices-only: no mirror is rendered or written, so no edit can be validated or applied.
+		const snapshot = noticesOnly ? undefined : renderContextDocument(effective, {
 			revision: this.state.revision,
 			protectedIndexes: new Set<number>(),
 			// Constant until the next accepted edit or reset, so header ids read on one call
 			// remain valid on the next; bodies are escaped accordingly.
 			documentSeed: `${this.sessionID}:${this.nonce}:${checkpoint?.sourceDigest ?? "raw"}`,
 		});
-		try {
-			await this.store.write(snapshot.text);
-			this.lastSnapshot = snapshot;
-			this.baseline = {
-				rawMessages: source,
-				effectiveMessages: effective,
-				snapshot,
-				// The fit gate measures the editable context alone; the system prompt, tool
-				// schemas, pinned task and continuity message take their share of budget − reserve first.
-				limit: limit === undefined ? undefined : Math.max(1, limit - scopeTokens - pinnedTokens - continuityTokens),
-			};
-		} catch (error) {
-			this.baseline = undefined;
-			this.pendingNotices.push(`[CLM] Could not refresh the mirror: ${describe(error)}`);
+		if (snapshot) {
+			try {
+				await this.store.write(snapshot.text);
+				this.refreshFailing = false;
+				this.lastSnapshot = snapshot;
+				this.baseline = {
+					rawMessages: source,
+					effectiveMessages: effective,
+					snapshot,
+					// The fit gate measures the editable context alone; the system prompt, tool
+					// schemas, pinned task and continuity message take their share of budget − reserve first.
+					limit: limit === undefined ? undefined : Math.max(1, limit - scopeTokens - pinnedTokens - continuityTokens),
+				};
+			} catch (error) {
+				this.baseline = undefined;
+				this.pendingNotices.push(`[CLM] Could not refresh the mirror: ${describe(error)}`);
+				if (!this.refreshFailing) this.pendingErrors.push(`could not refresh the mirror, edits are off until it can be written: ${describe(error)}`);
+				this.refreshFailing = true;
+			}
 		}
 
 		const conversationTokens = pinnedTokens + this.estimate(effective) + continuityTokens;
@@ -976,10 +1369,16 @@ export class ClmSession {
 				// The measured request was answered inside the prefix the active revision replaced.
 				observedStale: observed !== undefined && checkpoint !== undefined && checkpoint.sourceIds.includes(observed.messageID),
 			};
-			const tier = this.tracker.observe(reading, budgetTiers(this.settings.budget, resolved.budget, resolved.reserve));
+			// A fallback reading skips the tracker: no tier fires or is marked fired, and a pending
+			// cooldown waits, so reminders start from the real budget once the window is known.
+			const { tier, suppressed, cooldownUntil } = provisional ? { tier: undefined, suppressed: [] } : this.tracker.check(
+				reading, budgetTiers(this.settings.budget, resolved.budget, resolved.reserve), this.settings.budget.reminderCooldown);
+			for (const skipped of suppressed) {
+				await this.log({ event: "budget-notice-suppressed", tier: skipped.label, estimated: reading.estimated, cooldownUntil });
+			}
 			if (tier) {
 				// With the guard off nothing is withheld, so the notice must not describe it.
-				this.pendingNotices.push(budgetNoticeText(reading, tier, this.mirrorPath, this.settings.guard === "off" ? null : limit));
+				this.pendingNotices.push(budgetNoticeText(reading, tier, noticesOnly ? undefined : this.mirrorPath, this.settings.guard === "off" ? null : limit, { noticesOnly }));
 				await this.log({ event: "budget-notice", tier: tier.label, estimated: reading.estimated });
 			}
 			this.lastReading = reading;
@@ -1007,7 +1406,7 @@ export class ClmSession {
 		}
 
 		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 };
+		this.lastRequest = { rawMessages: raw.length, sentMessages: messages.length, mirrorBlocks: snapshot?.blocks.length ?? 0 };
 		if (this.settings.dumpRequests) {
 			const directory = join(this.store.directory, "requests");
 			await mkdir(directory, { recursive: true, mode: 0o700 }).catch(() => undefined);
@@ -1034,7 +1433,8 @@ export class ClmSession {
 			users: raw.filter((message) => message.info.role === "user").length,
 			raw: raw.length,
 			sent: messages.length,
-			blocks: snapshot.blocks.length,
+			blocks: snapshot?.blocks.length ?? 0,
+			...(noticesOnly ? { mode: "notices-only" } : {}),
 			withheld: withheldCount,
 			estimated: reading?.estimated ?? requestTokens,
 			observedPrevious: observed?.tokens,
@@ -1043,19 +1443,40 @@ export class ClmSession {
 			calibration: this.calibrator.factor,
 			notices: notices.map((notice) => notice.slice(0, 80)),
 		});
-		return { messages, notices, estimated: reading?.estimated ?? requestTokens, reading, ...(alert ? { alert } : {}) };
+		return {
+			messages,
+			notices,
+			estimated: reading?.estimated ?? requestTokens,
+			reading,
+			...this.drainAlerts(alert),
+		};
+	}
+
+	/** The queued toasts (`alert`, `errors`) for a transform result, cleared once taken. */
+	private drainAlerts(alert?: string): Pick<TransformResult, "alert" | "errors"> {
+		const alerts = [...(alert ? [alert] : []), ...this.pendingAlerts];
+		this.pendingAlerts = [];
+		const errors = this.pendingErrors;
+		this.pendingErrors = [];
+		return {
+			...(alerts.length > 0 ? { alert: alerts.join("\n") } : {}),
+			...(errors.length > 0 ? { errors } : {}),
+		};
 	}
 
 	/** Inputs for presentation.ts `statusText` / `statusLine`. */
 	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 });
+		const changed = changedSummary(base, effective, { modelWindow: this.limits.context, modelOutput: this.limits.output });
 		return {
 			...(changed ? { changed } : {}),
 			...(this.settingsWarning ? { settingsWarning: this.settingsWarning } : {}),
 			sessionID: this.sessionID,
-			mirrorPath: this.mirrorPath,
+			mirrorPath: this.mirrorUnavailable !== undefined
+				? `unavailable, requests carry the raw history (${this.mirrorUnavailable})`
+				: this.noticesOnly ? "not used (mode notices-only)" : this.mirrorPath,
+			...(this.noticesOnly ? { mode: "notices-only" as const } : {}),
 			revision: this.state.revision,
 			accepted: this.accepted,
 			rejected: this.rejected,