opencode-clm 0.1.1 → 0.3.0

package/src/commands.ts

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

package/src/compaction.ts

@@ -0,0 +1,243 @@
+// The `compaction`, `one-tool` and `trailer` settings: pure decisions for index.ts.
+// Semantics follow pi-clm's `PI_CLM_NATIVE_COMPACTION`, `oneToolPerTurn` and `sizeTrailer`
+// (pi-clm src/index.ts, MIT, Copyright 2026 Emanuel Casco); texts and the OpenCode mapping
+// are this package's.
+//
+// OpenCode 1.18.34 has one flag for automatic compaction, `compaction.auto` in the config.
+// It gates both threshold compaction (session/overflow.ts:28, checked at
+// session/processor.ts:491 after each step and session/prompt.ts:1161 before the next) and
+// recovery from a provider overflow error (session/processor.ts:620-628). Every check reads
+// `config.get()`, the object the plugin's `config` hook received (plugin/index.ts:152,245-252;
+// config/config.ts:620-622), so setting the key on that object takes effect at once, for
+// every session of the instance.
+
+import type { CompactionMode } from "./settings.ts";
+
+/**
+ * The `compaction.auto` value a mode asks for outside a pause; undefined = the user's own
+ * config value. pi's `on` is "Pi's default" (its handler leaves compaction alone), so `on`
+ * keeps the user's configuration. pi's `auto` cancels threshold compaction while the guard
+ * enforces a budget; here `auto` keeps the configuration and index.ts turns the flag off
+ * per request only when the threshold can fire (`thresholdReachable`, K1).
+ */
+export function compactionAuto(mode: CompactionMode, userAuto: boolean | undefined): boolean | undefined {
+	return mode === "off" ? false : userAuto;
+}
+
+/** Sets `config.compaction.auto` for `mode`, restoring the user's value (or its absence) for `auto`. */
+export function applyCompactionMode(config: { compaction?: { auto?: boolean } }, mode: CompactionMode, userAuto: boolean | undefined): void {
+	const value = compactionAuto(mode, userAuto);
+	if (value === undefined) {
+		if (config.compaction && "auto" in config.compaction) delete config.compaction.auto;
+		return;
+	}
+	(config.compaction ??= {}).auto = value;
+}
+
+/** Toast after OpenCode compacted a session on its own. */
+export function nativeCompactionText(overflow: boolean, mode: CompactionMode): string {
+	const why = overflow ? "after the provider reported a context overflow" : "at its token threshold";
+	const hint = mode === "off" ? "" : " Set /clm config compaction off to keep the model's own edits instead.";
+	return `OpenCode compacted this session ${why}; CLM continues from the summary.${hint}`;
+}
+
+/** Model notice when a provider overflow was not compacted because `compaction.auto` was false. */
+export function overflowNotCompactedText(mirrorPath: string): string {
+	return `[CLM] The provider rejected the last request as too long, and OpenCode's automatic compaction is off, so nothing was compacted. Shrink the context by editing ${mirrorPath}, or ask the user to run /compact.`;
+}
+
+/**
+ * Per-session count of tool calls since the session's last model request. `next` must run
+ * synchronously at the start of `tool.execute.before`: parallel calls of one response
+ * reach the hook concurrently, so "first" means first to arrive, not first in the response.
+ */
+export class ToolCallCounter {
+	private readonly counts = new Map<string, number>();
+
+	/** Called for every model request of the session. */
+	reset(sessionID: string): void {
+		this.counts.delete(sessionID);
+	}
+
+	/** This call's position (1-based) in the current response. */
+	next(sessionID: string): number {
+		const count = (this.counts.get(sessionID) ?? 0) + 1;
+		this.counts.set(sessionID, count);
+		return count;
+	}
+}
+
+/** The error a blocked call returns to the model. */
+export function oneToolText(tool: string, position: number): string {
+	return `[CLM] One tool call per response (setting one-tool): this ${tool} call was #${position} in the response and did not run. Call it again on its own in your next response.`;
+}
+
+/** `\n[context: ~N of B tokens after this result]`, appended to a tool result. */
+export function sizeTrailer(estimated: number, resultTokens: number, budget: number): string {
+	const format = (value: number) => value.toLocaleString("en-US");
+	return `\n[context: ~${format(estimated + resultTokens)} of ${format(budget)} tokens after this result]`;
+}
+
+// ---- `auto`: pausing threshold compaction while the guard enforces a budget (K1, K5) ----
+//
+// pi's `auto` cancels every threshold compaction while the overflow guard enforces a budget
+// (pi-clm src/index.ts `session_before_compact`) and leaves overflow recovery to Pi. OpenCode
+// gives no cancel hook and one flag for both. So before each request the plugin predicts
+// whether OpenCode's threshold check on that request's count can fire, and sets the flag false
+// only then; below the threshold the user's value (and with it overflow recovery) stays.
+//
+// The threshold check reads the count of one finished request (`tokens.total`, input plus
+// output) after that request's step (session/processor.ts:491) and again before the next
+// step (session/prompt.ts:1161, `lastFinished`); both run after this request's transform and
+// before the next one, so the flag set here governs exactly this request's count.
+
+/** OpenCode's default output cap (provider/transform.ts:18 `OUTPUT_TOKEN_MAX`). */
+export const OPENCODE_OUTPUT_TOKEN_MAX = 32_000;
+/** OpenCode's `COMPACTION_BUFFER` (session/overflow.ts:8). */
+const OPENCODE_COMPACTION_BUFFER = 20_000;
+
+/** The model limits OpenCode's threshold reads (`Provider.Model.limit`). */
+export interface ThresholdModel {
+	context?: number;
+	input?: number;
+	output?: number;
+}
+
+/** `ProviderTransform.maxOutputTokens` (provider/transform.ts:1481-1483). */
+export function openCodeMaxOutput(output: number | undefined, outputTokenMax = OPENCODE_OUTPUT_TOKEN_MAX): number {
+	return Math.min(output ?? 0, outputTokenMax) || outputTokenMax;
+}
+
+/**
+ * The `OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX` runtime flag (effect/runtime-flags.ts:52), a
+ * positive integer; undefined when unset or invalid.
+ */
+export function outputTokenMaxFlag(env: Record<string, string | undefined> = process.env): number | undefined {
+	const value = Number(env.OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX);
+	return Number.isInteger(value) && value > 0 ? value : undefined;
+}
+
+/**
+ * OpenCode's threshold (session/overflow.ts:10-20 `usable`); undefined when the window is
+ * unknown or 0 (OpenCode then never compacts at a threshold). processor.ts:491 calls it
+ * without the output-cap flag and prompt.ts:1161 with it; the lower of the two is returned.
+ */
+export function openCodeUsable(model: ThresholdModel, reserved: number | undefined, outputTokenMax?: number): number | undefined {
+	const context = model.context ?? 0;
+	if (context <= 0) return undefined;
+	const usable = (cap: number) => {
+		const maxOutput = openCodeMaxOutput(model.output, cap);
+		const reserve = reserved ?? Math.min(OPENCODE_COMPACTION_BUFFER, maxOutput);
+		return model.input ? Math.max(0, model.input - reserve) : Math.max(0, context - maxOutput);
+	};
+	return Math.min(usable(OPENCODE_OUTPUT_TOKEN_MAX), usable(outputTokenMax ?? OPENCODE_OUTPUT_TOKEN_MAX));
+}
+
+/** Token fields of an OpenCode assistant message (`SessionV1.Assistant["tokens"]`). */
+export interface StepTokens {
+	total?: number;
+	input?: number;
+	output?: number;
+	cache?: { read?: number; write?: number };
+}
+
+/** The count OpenCode compares with the threshold (session/overflow.ts:31-32). */
+export function openCodeCount(tokens: StepTokens): number {
+	const parts = Number(tokens.input ?? 0) + Number(tokens.output ?? 0) + Number(tokens.cache?.read ?? 0) + Number(tokens.cache?.write ?? 0);
+	return Number(tokens.total ?? 0) || parts;
+}
+
+/**
+ * `auto` with the guard on: whether OpenCode's threshold check can fire on this request, i.e.
+ * the request's estimate plus the most it may generate reaches the threshold. The output
+ * allowance is OpenCode's own output cap for the request, so the prediction errs toward
+ * pausing (pi pauses every threshold compaction).
+ */
+export function thresholdReachable(estimated: number, usable: number, maxOutput: number): boolean {
+	return estimated + maxOutput >= usable;
+}
+
+/**
+ * Per-session record of the flag the plugin set for each request and of threshold
+ * crossings, for K5: a step whose count reached the threshold while the plugin held the flag
+ * false is a threshold compaction the plugin cancelled. Reported once per crossing; a step
+ * below the threshold or a compaction re-arms it.
+ */
+export class ThresholdWatch {
+	private readonly sessions = new Map<string, { by?: "auto" | "off"; checked?: string; crossing: boolean }>();
+
+	/**
+	 * The flag this session's request ran under: `by` names the mode that turned it off
+	 * against the user's value (`auto` paused it, `off` forced it); undefined when it was not.
+	 */
+	set(sessionID: string, by: "auto" | "off" | undefined): void {
+		const entry = this.sessions.get(sessionID) ?? { crossing: false };
+		entry.by = by;
+		this.sessions.set(sessionID, entry);
+	}
+
+	/** The mode that turned the flag off for the session's last request, if any. */
+	by(sessionID: string): "auto" | "off" | undefined {
+		return this.sessions.get(sessionID)?.by;
+	}
+
+	/** A compaction ran: the next crossing is a new one. */
+	reset(sessionID: string): void {
+		const entry = this.sessions.get(sessionID);
+		if (entry) entry.crossing = false;
+	}
+
+	/**
+	 * The newest finished step of the session (not a summary), seen at the next transform.
+	 * Returns its count and the mode when the plugin's flag cancelled a threshold compaction on
+	 * it and this crossing was not reported yet; undefined otherwise. Each step is judged once.
+	 */
+	observe(sessionID: string, step: { id: string; count: number } | undefined, usable: number | undefined): { count: number; by: "auto" | "off" } | undefined {
+		const entry = this.sessions.get(sessionID);
+		if (!entry || !step || step.id === entry.checked) return undefined;
+		entry.checked = step.id;
+		if (usable === undefined || step.count < usable) {
+			entry.crossing = false;
+			return undefined;
+		}
+		if (!entry.by || entry.crossing) return undefined;
+		entry.crossing = true;
+		return { count: step.count, by: entry.by };
+	}
+}
+
+/** Toast when `auto` paused a threshold compaction (pi: toast only). */
+export function thresholdPausedText(count: number, usable: number, guardLimit: number | undefined): string {
+	const format = (value: number) => value.toLocaleString("en-US");
+	const guard = guardLimit !== undefined ? `; the overflow guard keeps the context under ~${format(guardLimit)} tokens` : "";
+	return `Paused OpenCode's threshold compaction: the last request counted ${format(count)} of OpenCode's ${format(usable)}-token threshold${guard}. Set /clm config compaction on to let OpenCode compact.`;
+}
+
+/** Model notice when `off` cancelled a threshold compaction (pi: notice and toast). */
+export function thresholdCancelledNoticeText(mirrorPath: string): string {
+	return `[CLM] OpenCode's automatic compaction (threshold) was cancelled: CLM manages this context. Free space by editing ${mirrorPath}.`;
+}
+
+/** Toast when `off` cancelled a threshold compaction. */
+export function thresholdCancelledText(count: number, usable: number): string {
+	const format = (value: number) => value.toLocaleString("en-US");
+	return `Cancelled OpenCode's threshold compaction (setting compaction off): the last request counted ${format(count)} of ${format(usable)} tokens.`;
+}
+
+/**
+ * The step OpenCode's pre-step check reads (`MessageV2.latest(...).finished`,
+ * session/message-v2.ts:586-602): the newest assistant message with `finish` set, by
+ * creation time then id. Undefined when there is none or it is a compaction summary
+ * (prompt.ts:1163 skips summaries).
+ */
+export function lastFinishedStep(raw: readonly { info: { id: string; role: string; [key: string]: any } }[]): { id: string; count: number } | undefined {
+	let finished: { id: string; role: string; [key: string]: any } | undefined;
+	for (const { info } of raw) {
+		if (info.role !== "assistant" || !info.finish) continue;
+		const created = Number(info.time?.created ?? 0);
+		const newest = Number(finished?.time?.created ?? 0);
+		if (!finished || created > newest || (created === newest && info.id > finished.id)) finished = info;
+	}
+	if (!finished || finished.summary === true || !finished.tokens) return undefined;
+	return { id: finished.id, count: openCodeCount(finished.tokens as StepTokens) };
+}

package/src/context-document.ts

@@ -132,7 +132,8 @@ export function estimateContextCharacters(messages: LiveContextMessage[]): numbe
 	return messages.reduce((total, message) => total + renderMessage(message).length, 0);
 }
 
-function blockId(message: LiveContextMessage, index: number): string {
+/** The mirror block id of `message` at position `index` of the rendered messages. */
+export function blockId(message: LiveContextMessage, index: number): string {
 	const digest = createHash("sha256").update(canonicalMessage(message)).digest("hex").slice(0, 12);
 	return `${index + 1}-${digest}`;
 }

package/src/continuity.ts

@@ -17,7 +17,7 @@ import { resolve } from "node:path";
 
 import type { ToolContext, ToolDefinition, tool } from "@opencode-ai/plugin";
 
-import { digestMessages, renderMessage } from "./context-document.ts";
+import { blockId, digestMessages, renderMessage } from "./context-document.ts";
 import type { LiveContextMessage } from "./types.ts";
 
 export const ANNOTATIONS_FILE = "annotations.jsonl";
@@ -413,6 +413,113 @@ export interface CreateAnnotationInput {
  */
 const fileQueues = new Map<string, Promise<unknown>>();
 
+/**
+ * The origin's annotations as a fork of it carries them (pi: a branch carries the annotation
+ * entries on its path). OpenCode's `Session.fork` copies messages with new ids
+ * (session/session.ts:691-730) and keeps their times, and an annotation's `contentHash` and
+ * block id digest the source message with its id. So:
+ * - an annotation created after `cutoff` (ms; the fork's newest copied message) belongs to
+ *   the origin's later history and is left out; one resolved after it is carried unresolved;
+ * - a source found in the fork's `messages` by its rendered text (role and text, or the head
+ *   of a truncated snapshot) is re-pointed at the fork's copy: hash, block id (its position
+ *   in `messages`) and session; an unmatched source keeps the origin's values and
+ *   stays recallable from its stored text. Identical messages (a repeated prompt, the same
+ *   tool output twice) map to the first copy: same text and hash, possibly another block id.
+ *   Block ids index `messages` as the caller passes them (the effective messages before the
+ *   overflow guard, which replaces results in place and so keeps positions).
+ * Ids, titles, text, creation times and `source.revision` (the origin's revision) are kept.
+ */
+export function forkAnnotations(
+	annotations: readonly LiveContextAnnotation[],
+	messages: readonly LiveContextMessage[],
+	options: { sessionId: string; cutoff?: number },
+): LiveContextAnnotation[] {
+	const rendered = messages.map((message) => renderMessage(message));
+	const before = (iso: string | undefined) => iso !== undefined && (options.cutoff === undefined || Date.parse(iso) <= options.cutoff);
+	const out: LiveContextAnnotation[] = [];
+	for (const annotation of annotations) {
+		if (!before(annotation.createdAt)) continue;
+		const copy: LiveContextAnnotation = { ...annotation, source: { ...annotation.source } };
+		if (copy.resolvedAt !== undefined && !before(copy.resolvedAt)) {
+			delete copy.resolvedAt;
+			delete copy.resolution;
+		}
+		const { source } = copy;
+		const index = messages.findIndex((message, position) =>
+			message.role === source.role &&
+			(source.truncated ? rendered[position]!.startsWith(source.text) : rendered[position] === source.text));
+		if (index >= 0) {
+			copy.source = { ...source, sessionId: options.sessionId, contentHash: sourceContentHash(messages[index]!), blockId: blockId(messages[index]!, index) };
+		}
+		out.push(copy);
+	}
+	return out;
+}
+
+/** Bound on the annotations a session without a mirror keeps in OpenCode's session metadata, bytes of JSON. */
+export const PERSISTED_ANNOTATIONS_BYTES = 64 * 1024;
+
+/**
+ * Annotations of a session without a mirror, as kept in OpenCode's session metadata
+ * (`metadata.clm.annotations`) so they survive a restart; the session's files then live in a
+ * per-process temp directory. `resolved` records every resolution (small); `annotations`
+ * holds full snapshots, active ones first, as many as fit the byte bound.
+ */
+export interface PersistedAnnotations {
+	version: 1;
+	resolved: Array<{ id: string; resolvedAt: string; resolution?: string }>;
+	annotations: LiveContextAnnotation[];
+}
+
+/** The record for `metadata.clm.annotations`, at most `maxBytes` of JSON. */
+export function persistAnnotations(annotations: readonly LiveContextAnnotation[], maxBytes = PERSISTED_ANNOTATIONS_BYTES): PersistedAnnotations {
+	const out: PersistedAnnotations = { version: 1, resolved: [], annotations: [] };
+	let size = Buffer.byteLength(JSON.stringify(out));
+	const fits = (value: unknown) => {
+		const added = Buffer.byteLength(JSON.stringify(value)) + 1;
+		if (size + added > maxBytes) return false;
+		size += added;
+		return true;
+	};
+	for (const annotation of annotations) {
+		if (annotation.resolvedAt === undefined) continue;
+		const stub = { id: annotation.id, resolvedAt: annotation.resolvedAt, ...(annotation.resolution !== undefined ? { resolution: annotation.resolution } : {}) };
+		if (fits(stub)) out.resolved.push(stub);
+	}
+	const rank = (annotation: LiveContextAnnotation) => (annotation.resolvedAt === undefined && annotation.retention !== "archive" ? 0 : 1);
+	for (const annotation of [...annotations].sort((left, right) => rank(left) - rank(right))) {
+		if (fits(annotation)) out.annotations.push(annotation);
+	}
+	return out;
+}
+
+/**
+ * Snapshots to append to a store holding `current` so it reflects `persisted` (a
+ * `PersistedAnnotations` read back from metadata; anything else yields nothing): annotations
+ * the store lacks, then resolutions of ones it holds unresolved.
+ */
+export function restorePersisted(current: readonly LiveContextAnnotation[], persisted: unknown): LiveContextAnnotation[] {
+	if (!persisted || typeof persisted !== "object") return [];
+	const record = persisted as Partial<PersistedAnnotations>;
+	if (record.version !== 1) return [];
+	const byId = new Map(current.map((annotation) => [annotation.id, annotation]));
+	const out: LiveContextAnnotation[] = [];
+	for (const annotation of Array.isArray(record.annotations) ? record.annotations : []) {
+		if (!isLiveContextAnnotation(annotation) || byId.has(annotation.id)) continue;
+		byId.set(annotation.id, annotation);
+		out.push(annotation);
+	}
+	for (const stub of Array.isArray(record.resolved) ? record.resolved : []) {
+		if (!stub || typeof stub !== "object" || typeof stub.id !== "string" || typeof stub.resolvedAt !== "string") continue;
+		const annotation = byId.get(stub.id);
+		if (!annotation || annotation.resolvedAt !== undefined) continue;
+		const resolved = resolveAnnotation(annotation, typeof stub.resolution === "string" ? stub.resolution : undefined, stub.resolvedAt);
+		byId.set(stub.id, resolved);
+		out.push(resolved);
+	}
+	return out;
+}
+
 /** Append-only `annotations.jsonl` in one session directory. */
 export class AnnotationStore {
 	readonly filePath: string;
@@ -492,6 +599,25 @@ export class AnnotationStore {
 		});
 	}
 
+	/** Appends snapshots as they are (`restorePersisted`); the latest per id wins on load. */
+	appendAll(annotations: readonly LiveContextAnnotation[]): Promise<void> {
+		return this.serialize(async () => {
+			for (const annotation of annotations) await this.append(annotation);
+		});
+	}
+
+	/**
+	 * Writes another session's annotations into this store as they are (`forkAnnotations`),
+	 * only while this store holds none; returns how many were written.
+	 */
+	importAll(annotations: readonly LiveContextAnnotation[]): Promise<number> {
+		return this.serialize(async () => {
+			if (annotations.length === 0 || (await this.list()).length > 0) return 0;
+			for (const annotation of annotations) await this.append(annotation);
+			return annotations.length;
+		});
+	}
+
 	async recall(
 		id: string,
 		maxTokens?: number,

package/src/history.ts

@@ -0,0 +1,109 @@
+// Checkpoint history: every accepted revision's checkpoint, kept in
+// `<session dir>/checkpoints/rN.json` (the newest HISTORY_CAP files). pi-clm rebuilds its
+// history from the session entries on the active branch (pi-clm src/index.ts `restore`,
+// MIT, Copyright 2026 Emanuel Casco) and restores the checkpoint valid on the branch `/tree`
+// selects. OpenCode has no branches; its equivalents are revert
+// (packages/opencode/src/session/revert.ts), which cuts the history, and `Session.fork`
+// (packages/opencode/src/session/session.ts:691-731), which copies it into a new session
+// under new message ids. clm.ts uses this history to restore the newest older revision that
+// still fits after either. Written for this package.
+import { mkdir, readdir, readFile, rm } from "node:fs/promises";
+import { join } from "node:path";
+
+import { writeJsonAtomic } from "./atomic.ts";
+import { sourceMessageId, type ProjectionCheckpoint } from "./projection.ts";
+import { isProjectionCheckpoint } from "./state.ts";
+import type { LiveContextMessage } from "./types.ts";
+
+export const HISTORY_DIR = "checkpoints";
+/** Checkpoints kept per session; each holds a whole projected context, so the count is small. */
+export const HISTORY_CAP = 8;
+
+const FILE_RE = /^r(\d+)\.json$/;
+
+export interface HistoryEntry {
+	version: 1;
+	checkpoint: ProjectionCheckpoint;
+	/** `digestSourceContent` of the checkpoint's source: matches a forked copy of it. */
+	contentDigest: string;
+}
+
+export interface LoadedHistory {
+	/** Newest revision first. */
+	entries: HistoryEntry[];
+	/** Files that were skipped (unreadable, malformed, or naming another revision). */
+	ignored: string[];
+}
+
+export function historyDirectory(sessionDirectory: string): string {
+	return join(sessionDirectory, HISTORY_DIR);
+}
+
+function isHistoryEntry(value: unknown): value is HistoryEntry {
+	if (!value || typeof value !== "object") return false;
+	const entry = value as Partial<HistoryEntry>;
+	return entry.version === 1 && isProjectionCheckpoint(entry.checkpoint) &&
+		typeof entry.contentDigest === "string" && /^[a-f0-9]{64}$/.test(entry.contentDigest);
+}
+
+/** Write one checkpoint, then delete all but the newest `cap` files. */
+export async function saveHistoryEntry(sessionDirectory: string, entry: HistoryEntry, cap = HISTORY_CAP): Promise<void> {
+	const directory = historyDirectory(sessionDirectory);
+	await mkdir(directory, { recursive: true, mode: 0o700 });
+	await writeJsonAtomic(join(directory, `r${entry.checkpoint.revision}.json`), entry);
+	const revisions = (await readdir(directory))
+		.map((name) => FILE_RE.exec(name))
+		.filter((match): match is RegExpExecArray => match !== null)
+		.map((match) => Number(match[1]))
+		.sort((left, right) => right - left);
+	await Promise.all(revisions.slice(Math.max(1, cap)).map((revision) =>
+		rm(join(directory, `r${revision}.json`), { force: true })));
+}
+
+/** All usable entries, newest first. Never throws: a missing directory is an empty history. */
+export async function loadHistory(sessionDirectory: string): Promise<LoadedHistory> {
+	const directory = historyDirectory(sessionDirectory);
+	let names: string[];
+	try {
+		names = await readdir(directory);
+	} catch {
+		return { entries: [], ignored: [] };
+	}
+	const entries: HistoryEntry[] = [];
+	const ignored: string[] = [];
+	for (const name of names) {
+		const match = FILE_RE.exec(name);
+		if (!match) continue;
+		try {
+			const parsed: unknown = JSON.parse(await readFile(join(directory, name), "utf8"));
+			if (isHistoryEntry(parsed) && parsed.checkpoint.revision === Number(match[1])) entries.push(parsed);
+			else ignored.push(name);
+		} catch {
+			ignored.push(name);
+		}
+	}
+	entries.sort((left, right) => right.checkpoint.revision - left.checkpoint.revision);
+	return { entries, ignored };
+}
+
+/** Forget every checkpoint (`/clm reset`: the user dropped the edits on purpose). */
+export async function clearHistory(sessionDirectory: string): Promise<void> {
+	await rm(historyDirectory(sessionDirectory), { recursive: true, force: true });
+}
+
+/**
+ * The checkpoint's projected messages with the source session's message ids replaced by
+ * the fork's, position by position over the source prefix (`source` is the fork's prefix,
+ * same length as `checkpoint.sourceIds`). Ids outside the prefix stay as they are.
+ */
+export function remapProjection(checkpoint: ProjectionCheckpoint, source: readonly LiveContextMessage[]): LiveContextMessage[] {
+	const ids = new Map<string, string>();
+	checkpoint.sourceIds.forEach((id, index) => {
+		const next = source[index] ? sourceMessageId(source[index]) : "";
+		if (id && next && !ids.has(id)) ids.set(id, next);
+	});
+	return checkpoint.projectedMessages.map((message) => {
+		const id = typeof message.ocMessageID === "string" ? ids.get(message.ocMessageID) : undefined;
+		return id === undefined ? message : { ...message, ocMessageID: id };
+	});
+}

package/src/mirror-store.ts

@@ -1,8 +1,9 @@
 // Adapted from pi-clm src/mirror-store.ts (MIT, Copyright 2026 Emanuel Casco).
 
 import { readFileSync } from "node:fs";
-import { chmod, lstat, mkdir, readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
+import { constants } from "node:fs";
+import { chmod, lstat, mkdir, mkdtemp, open, readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
 import { basename, join } from "node:path";
 import { randomUUID } from "node:crypto";
 
@@ -14,7 +15,14 @@ export function defaultMirrorParent(): string {
 	return join(stateHome, "opencode-clm", "mirrors");
 }
 
-function safeSessionId(sessionId: string): string {
+/** The session directory under a mirror parent could not be created or was refused. */
+export class MirrorDirectoryError extends Error {
+	constructor(readonly parent: string, readonly cause: unknown) {
+		super(`could not use ${parent}: ${cause instanceof Error ? cause.message : String(cause)}`);
+	}
+}
+
+export function safeSessionId(sessionId: string): string {
 	const safe = sessionId.replace(/[^a-zA-Z0-9_-]/g, "-").slice(0, 64);
 	return safe || "session";
 }
@@ -76,6 +84,36 @@ async function assertPrivateDirectory(directory: string): Promise<void> {
 	}
 }
 
+/** A fresh private (0700) directory under the OS temp directory, for sessions without a usable mirror directory. */
+export function privateTemporaryParent(): Promise<string> {
+	return mkdtemp(join(tmpdir(), "opencode-clm-"));
+}
+
+/**
+ * Copies `name` from `fromDirectory` into `toDirectory` (mode 0600), only when the source
+ * directory passes the store's own check (a real directory owned by this user) and the file
+ * is a regular file. Never overwrites. Returns whether a copy was made; never throws.
+ */
+export async function copyPrivateFile(fromDirectory: string, toDirectory: string, name: string): Promise<boolean> {
+	try {
+		await assertPrivateDirectory(fromDirectory);
+		// O_NOFOLLOW and a check on the open handle: a file swapped for a symlink is not followed.
+		// O_NONBLOCK: opening a FIFO must not block before the isFile() check.
+		const handle = await open(join(fromDirectory, name), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+		let content: Buffer;
+		try {
+			if (!(await handle.stat()).isFile()) return false;
+			content = await handle.readFile();
+		} finally {
+			await handle.close();
+		}
+		await writeFile(join(toDirectory, name), content, { mode: 0o600, flag: "wx" });
+		return true;
+	} catch {
+		return false;
+	}
+}
+
 export class MirrorStore {
 	readonly directory: string;
 	readonly filePath: string;

package/src/opencode.ts

@@ -337,3 +337,62 @@ export function unflatten(messages: readonly LiveContextMessage[], context: Unfl
 export function replaceInPlace(target: OcMessage[], next: readonly OcMessage[]): void {
 	target.splice(0, target.length, ...next);
 }
+
+/**
+ * The part of a stored history OpenCode sends to the model: port of OpenCode 1.18.34
+ * `MessageV2.filterCompacted` (packages/opencode/src/session/message-v2.ts:525-576), which
+ * the prompt loop applies to the stored stream (session/prompt.ts:1092). `client.session.messages`
+ * returns the full history, oldest first (no filter); OpenCode's `stream` walks it newest
+ * first, so this walks `messages` backwards. After a completed compaction the result is
+ * [compaction user message, summary, retained tail (`tail_start_id`), newer messages];
+ * without one it is `messages` unchanged.
+ */
+export function filterCompacted(messages: readonly OcMessage[]): OcMessage[] {
+	const result: OcMessage[] = [];
+	const completed = new Set<string>();
+	let retain: string | undefined;
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const message = messages[i]!;
+		result.push(message);
+		if (retain) {
+			if (message.info.id === retain) break;
+			continue;
+		}
+		if (message.info.role === "user" && completed.has(message.info.id)) {
+			const part = message.parts.find((item) => item.type === "compaction");
+			if (!part) continue;
+			if (!part.tail_start_id) break;
+			retain = String(part.tail_start_id);
+			if (message.info.id === retain) break;
+			continue;
+		}
+		if (message.info.role === "assistant" && message.info.summary && message.info.finish && !message.info.error) {
+			completed.add(message.info.parentID);
+		}
+	}
+	result.reverse();
+	const isTailCompaction = (item: OcPart) => item.type === "compaction" && item.tail_start_id !== undefined;
+	let compactionIndex = -1;
+	for (let i = result.length - 1; i >= 0; i--) {
+		const message = result[i]!;
+		if (message.info.role === "user" && message.parts.some(isTailCompaction)) {
+			compactionIndex = i;
+			break;
+		}
+	}
+	const compaction = result[compactionIndex];
+	const part = compaction?.parts.find(isTailCompaction);
+	const summaryIndex = compaction
+		? result.findIndex((message, index) =>
+			index > compactionIndex && message.info.role === "assistant" && message.info.summary && message.info.parentID === compaction.info.id)
+		: -1;
+	const tailIndex = part?.tail_start_id ? result.findIndex((message) => message.info.id === part.tail_start_id) : -1;
+	if (tailIndex >= 0 && tailIndex < compactionIndex && summaryIndex > compactionIndex) {
+		return [
+			...result.slice(compactionIndex, summaryIndex + 1),
+			...result.slice(tailIndex, compactionIndex),
+			...result.slice(summaryIndex + 1),
+		];
+	}
+	return result;
+}