pi-posthorse 0.8.0 → 0.8.2

package/index.ts

@@ -1,1565 +1,52 @@
 /**
  * Posthorse — fresh context, same journey.
  *
- * No-summary context rollover for Pi: a retain-none public compaction whose summary is
- * the handoff, on official Pi and the maintained fork.
- * Pi owns the persisted boundary. Posthorse owns the policy: sparse budget reminders, rollover
- * tools, durable notes, and history recovery.
+ * Pi owns persisted retain-none context boundaries. Posthorse owns reminder and
+ * rollover policy, bounded recovery, durable notes, and history retrieval.
  */
-
-import { execFile } from "node:child_process";
-import { createHash, randomUUID } from "node:crypto";
-import {
-	appendFileSync,
-	createReadStream,
-	existsSync,
-	mkdirSync,
-	readdirSync,
-	readFileSync,
-	realpathSync,
-	statSync,
-} from "node:fs";
-import { access, constants, lstat, open, readlink, realpath, rename, stat, unlink } from "node:fs/promises";
-import { basename, dirname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
-import { promisify } from "node:util";
-import { estimateTokens, formatSize, getAgentDir, SettingsManager, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
-import { registerPosthorseMessages, toolCards, type PosthorseDisplay } from "./ui.ts";
-
-const REMINDER_BUFFER_TOKENS = 32_000;
-/** Absolute ceilings; handoffs and pages shrink to the live remaining budget. */
-const MAX_HANDOFF_CHARS = 20_000;
-const MAX_PAGE_CHARS = 40_000;
-const MAX_RECOVERY_RECORD_CHARS = 4_000;
-const MAX_RECOVERY_RESULT_CHARS = 1_500;
-const HANDOFF_OVERHEAD_RESERVE = 1_000;
-const PAGE_MARGIN_TOKENS = 1_000;
-const MIN_PAGE_CHARS = 1_000;
-const ESTIMATED_IMAGE_CHARS = 4_800;
-/** A window must hold the largest handoff (~5,000 tokens) plus equal working room below Pi's line. */
-const MIN_USABLE_TOKENS = Math.ceil(MAX_HANDOFF_CHARS / 4) * 2;
-const REMINDER_TYPE = "posthorse-reminder";
-const AUTO_HANDOFF_PREFIX = "Automatic context rollover recovery record.";
-const EMPTY_HANDOFF = "Fresh context. Restore relevant notes and history before continuing.";
-
-type CompactionPolicy = { enabled: boolean; reserveTokens: number };
-type ContextUsage = { tokens: number | null; contextWindow: number; percent: number | null };
-
-/** Settings come from the injected policy; the compaction hook provides Pi's live policy. */
-type PolicyContext = {
-	getCompactionSettings(): CompactionPolicy;
-	getContextUsage(): ContextUsage | undefined;
-	getSystemPrompt(): string;
-};
-
-type ImageLike = { type: "image"; data: string; mimeType: string };
-type ToolCallLike = {
-	type?: string;
-	id?: string;
-	name?: string;
-	namespace?: string;
-	arguments?: unknown;
-	executionArguments?: unknown;
-	async?: boolean;
-};
-type MessageLike = {
-	role?: string;
-	stopReason?: string;
-	errorMessage?: string;
-	content?: unknown;
-	summary?: string;
-	toolName?: string;
-	namespace?: string;
-	toolCallId?: string;
-	isError?: boolean;
-	command?: string;
-	output?: string;
-	excludeFromContext?: boolean;
-};
-type EntryLike = {
-	type?: string;
-	id?: string;
-	parentId?: string | null;
-	timestamp?: string;
-	message?: MessageLike;
-	summary?: string;
-	customType?: string;
-	content?: unknown;
-	details?: unknown;
-	display?: boolean;
-	handoff?: string;
-	firstKeptEntryId?: string;
-	targetId?: string;
-	replacement?: { content: unknown } | null;
-};
-
-type WindowedEntry = { entry: EntryLike; windowId: string; text: string; images: ImageLike[] };
-type ProjectedEntry = { sourceEntry: EntryLike; messages: MessageLike[] };
-type HistoryHit = { id: string; text: string; headerLength: number; priority: 0 | 1 };
-type RecoveryRecord = {
-	id: string;
-	timestamp: string;
-	kind: "owner" | "coordination";
-	label: string;
-	text: string;
-};
-type ReminderFingerprint = { windowId: string; contextWindow?: number; reserveTokens?: number };
-type NoteFile = { path: string; size: number; mtimeMs: number };
-type Budget = {
-	contextWindow: number;
-	reserveTokens: number;
-	enabled: boolean;
-	usable: number;
-	rolloverAt: number;
-	supported: boolean;
-};
-
-/** A legacy fork context window, or the retain-none compaction Posthorse commits on both hosts. */
-function isWindow(entry: EntryLike): boolean {
-	return entry.type === "context_window" || (entry.type === "compaction" && (entry.details as { posthorse?: unknown } | undefined)?.posthorse === 1);
-}
-
-function windowHandoff(entry: EntryLike | undefined): string | undefined {
-	return entry?.type === "compaction" ? entry.summary : entry?.handoff;
-}
-
-/** First branch entry still in model context: after a fork window, or a compaction's kept tail (including Pi's own `/compact`). */
-function contextStart(entries: readonly EntryLike[]): { start: number; boundary?: EntryLike } {
-	for (let i = entries.length - 1; i >= 0; i--) {
-		const entry = entries[i];
-		if (entry.type === "context_window") return { start: i + 1, boundary: entry };
-		if (entry.type === "compaction") {
-			const kept = entries.findIndex((candidate) => candidate.id === entry.firstKeptEntryId);
-			return { start: kept >= 0 ? kept : i + 1, boundary: entry };
-		}
-	}
-	return { start: 0 };
-}
-
-function isReminderType(customType: unknown): boolean {
-	return customType === REMINDER_TYPE;
-}
-
-/** Resolve each link like the fork's publisher: never normalize away a path constraint. */
-async function resolveFileTarget(absolutePath: string): Promise<string> {
-	let target = absolutePath;
-	const links = new Set<string>();
-	for (;;) {
-		// A trailing separator requires an existing directory, never a new regular file.
-		if (target.endsWith(sep) || target.endsWith("/")) {
-			await stat(target);
-			return realpath(target);
-		}
-		const parentInput = dirname(target);
-		// realpath alone can accept regular-file/.. on macOS; stat checks traversal.
-		if (!(await stat(parentInput)).isDirectory()) {
-			throw Object.assign(new Error(`Not a directory: ${parentInput}`), { code: "ENOTDIR" });
-		}
-		const parent = await realpath(parentInput);
-		target = join(parent, basename(target));
-		const info = await lstat(target).catch((error: NodeJS.ErrnoException) => {
-			if (error.code !== "ENOENT") throw error;
-			return undefined;
-		});
-		if (!info) return target;
-		if (!info.isSymbolicLink()) return realpath(target);
-		if (links.has(target)) throw Object.assign(new Error(`Symlink cycle: ${absolutePath}`), { code: "ELOOP" });
-		links.add(target);
-		const link = await readlink(target);
-		// Preserve ".." until realpath has followed any preceding directory symlinks.
-		target = isAbsolute(link) ? link : `${parent}${sep}${link}`;
-	}
-}
-
-/** Same-directory replacement: a failure before rename leaves the previous note; mode/uid/gid are kept. */
-async function publishFile(path: string, content: string, signal?: AbortSignal): Promise<void> {
-	signal?.throwIfAborted();
-	const target = await resolveFileTarget(path);
-	const previous = await lstat(target).catch((error: NodeJS.ErrnoException) => {
-		if (error.code !== "ENOENT") throw error;
-		return undefined;
-	});
-	if (previous && !previous.isFile()) {
-		throw Object.assign(new Error(`Cannot publish to a non-regular file: ${target}`), { code: previous.isDirectory() ? "EISDIR" : "EINVAL", path: target });
-	}
-	if (previous) await access(target, constants.W_OK);
-	const temporary = join(dirname(target), `.posthorse-${randomUUID()}.tmp`);
-	const file = await open(temporary, "wx", previous ? 0o600 : 0o666);
-	try {
-		await file.writeFile(content, { signal });
-		if (previous) {
-			const staged = await file.stat();
-			if (staged.uid !== previous.uid || staged.gid !== previous.gid) await file.chown(previous.uid, previous.gid);
-			await file.chmod(previous.mode & 0o777);
-		}
-		await file.close();
-		signal?.throwIfAborted();
-		await rename(temporary, target);
-	} catch (error) {
-		await file.close().catch(() => {});
-		await unlink(temporary).catch(() => {});
-		throw error;
-	}
-}
-
-function isImage(part: unknown): part is ImageLike {
-	const block = part as Partial<ImageLike> | null;
-	return typeof block === "object" && block !== null && block.type === "image" && typeof block.data === "string";
-}
-
-function imagesOf(content: unknown): ImageLike[] {
-	return Array.isArray(content) ? content.filter(isImage) : [];
-}
-
-function imageSummary(images: ImageLike[]): string {
-	if (!images.length) return "";
-	const types = [...new Set(images.map((image) => image.mimeType || "unknown type"))].join(", ");
-	return `[${images.length} image${images.length === 1 ? "" : "s"}: ${types}]`;
-}
-
-function safeJsonStringify(value: unknown): string {
-	try {
-		return JSON.stringify(value) ?? "undefined";
-	} catch {
-		return "[unserializable]";
-	}
-}
-
-function toolIdentity(name?: string, namespace?: string): string {
-	return `${name ?? "tool"}${namespace === undefined ? "" : ` (namespace: ${safeJsonStringify(namespace)})`}`;
-}
-
-function executionArgumentsText(call: ToolCallLike): string {
-	return call.executionArguments === undefined ? "" : `\nExecution arguments: ${safeJsonStringify(call.executionArguments)}`;
-}
-
-function textOf(message: MessageLike): string {
-	if (typeof message.content === "string") return message.content;
-	if (!Array.isArray(message.content)) return "";
-	return message.content
-		.map((part) => {
-			if (!part || typeof part !== "object") return "";
-			const block = part as ToolCallLike & { text?: string; thinking?: string };
-			if (block.type === "text") return block.text ?? "";
-			if (block.type === "thinking") return block.thinking ?? "";
-			if (block.type === "toolCall") {
-				return `${toolIdentity(block.name, block.namespace)} ${safeJsonStringify(block.arguments ?? {})}${block.id === undefined ? "" : `\nCall ID: ${block.id}`}${executionArgumentsText(block)}`;
-			}
-			return "";
-		})
-		.filter(Boolean)
-		.join("\n");
-}
-
-function textResult(text: string, images: ImageLike[] = [], display?: PosthorseDisplay) {
-	return { content: [{ type: "text" as const, text }, ...images], details: display };
-}
-
-/** Conventional repos use the main checkout; separate Git directories are their own shared root. */
-function notesRoot(cwd: string): string {
-	for (let dir = cwd; ; dir = dirname(dir)) {
-		const marker = join(dir, ".git");
-		if (existsSync(marker)) {
-			try {
-				let target = marker;
-				if (!statSync(marker).isDirectory()) {
-					const gitdir = readFileSync(marker, "utf8").match(/^gitdir:\s*(.+?)\s*$/m)?.[1];
-					if (!gitdir) return dir;
-					target = resolve(dir, gitdir);
-				}
-				target = realpathSync(target);
-				const commonFile = join(target, "commondir");
-				const common = realpathSync(existsSync(commonFile) ? resolve(target, readFileSync(commonFile, "utf8").trim()) : target);
-				return basename(common) === ".git" ? dirname(common) : common;
-			} catch {
-				// Orphaned/copied worktrees can outlive their Git metadata; local notes still work.
-				return dir;
-			}
-		}
-		if (dirname(dir) === dir) return cwd;
-	}
-}
-
-function requireValue(value: string | undefined, name: string, op: string): string {
-	if (value === undefined || value === "") throw new Error(`"${name}" is required for op "${op}".`);
-	return value;
-}
-
-function excerptAround(text: string, index: number, before: number, length: number): string {
-	const start = Math.max(0, index - before);
-	const end = Math.min(text.length, start + length);
-	return `${start ? "…" : ""}${text.slice(start, end)}${end < text.length ? "…" : ""}`;
-}
-
-function assistantFailure(message: MessageLike): string {
-	if (message.role !== "assistant") return "";
-	if (message.stopReason !== "error" && message.stopReason !== "aborted" && !message.errorMessage) return "";
-	return `[${message.stopReason ?? "error"}]${message.errorMessage ? ` ${message.errorMessage}` : ""}`;
-}
-
-function flattenEntry(entry: EntryLike): string | undefined {
-	if (entry.type === "message") {
-		const message = entry.message ?? {};
-		if (message.role === "bashExecution") {
-			// Pi keeps these out of every model's input on purpose; do not smuggle them back in through history.
-			if (message.excludeFromContext === true) return "[bashExecution] (excluded from model context by Pi)";
-			return `[bashExecution] $ ${message.command ?? ""}\n${message.output ?? ""}`;
-		}
-		const resultIdentity = message.role === "toolResult"
-			? `Tool: ${toolIdentity(message.toolName, message.namespace)}${message.toolCallId === undefined ? "" : `\nCall ID: ${message.toolCallId}`}`
-			: "";
-		return `[${message.role ?? "message"}] ${[textOf(message), assistantFailure(message), imageSummary(imagesOf(message.content)), resultIdentity].filter(Boolean).join("\n")}`;
-	}
-	if (entry.type === "compaction" || entry.type === "branch_summary") {
-		return `[${entry.type}] ${entry.summary ?? ""}`;
-	}
-	if (entry.type === "custom_message") {
-		return `[custom:${entry.customType ?? "unknown"}] ${[textOf({ content: entry.content }), imageSummary(imagesOf(entry.content))].filter(Boolean).join("\n")}`;
-	}
-	if (entry.type === "context_window") {
-		return `[context_window] ${entry.handoff ? `Handoff: ${entry.handoff}` : "No handoff"}`;
-	}
-	if (entry.type === "context_edit" && entry.replacement) {
-		const content = entry.replacement.content;
-		return `[context_edit] ${[textOf({ content }), imageSummary(imagesOf(content))].filter(Boolean).join("\n")}`;
-	}
-	return undefined;
-}
-
-function isRecoveryTool(name: unknown): boolean {
-	return name === "history" || name === "notes" || name === "new_context";
-}
-
-function isRecoveryCall(part: unknown): boolean {
-	const block = part as { type?: string; name?: string } | null;
-	return block?.type === "toolCall" && isRecoveryTool(block.name);
-}
-
-/** Ten base64url characters of SHA-256; 0.6 file keys were the whole digest, which starts with these. */
-function shortKey(text: string): string {
-	return createHash("sha256").update(text).digest("base64url").slice(0, 10);
-}
-
-/** Nested session files are subagent runs, whose user-role input came from a parent agent. */
-function sourceTag(source: string): string {
-	return source.includes(sep) ? " [subagent]" : "";
-}
-
-function contextEdits(entries: readonly EntryLike[]): Map<string, EntryLike> {
-	const edits = new Map<string, EntryLike>();
-	for (const entry of entries) {
-		if (entry.type === "context_edit" && entry.targetId) edits.set(entry.targetId, entry);
-	}
-	return edits;
-}
-
-function historyHit(item: WindowedEntry, query: string, source = ""): HistoryHit | undefined {
-	const { entry } = item;
-	let text = item.text;
-	let matchIndex = text.toLowerCase().indexOf(query);
-	if (matchIndex === -1) return undefined;
-	let priority: 0 | 1 =
-		entry.type === "context_window" ||
-		entry.type === "compaction" ||
-		entry.type === "branch_summary" ||
-		(entry.type === "custom_message" && isReminderType(entry.customType)) ||
-		(entry.type === "message" && entry.message?.role === "toolResult" && isRecoveryTool(entry.message.toolName))
-			? 1
-			: 0;
-
-	if (
-		entry.type === "message" && entry.message?.role === "assistant" &&
-		Array.isArray(entry.message.content) && entry.message.content.some(isRecoveryCall)
-	) {
-		// A lookup beside a matching ordinary call or prose must not demote that original content.
-		const originals = [""];
-		for (const part of entry.message.content) {
-			if (isRecoveryCall(part)) {
-				originals.push("");
-			} else {
-				const partText = textOf({ content: [part] });
-				if (partText) originals[originals.length - 1] += `${originals.at(-1) ? "\n" : ""}${partText}`;
-			}
-		}
-		const metadata = [assistantFailure(entry.message), imageSummary(item.images)].filter(Boolean).join("\n");
-		if (metadata) originals[originals.length - 1] += `${originals.at(-1) ? "\n" : ""}${metadata}`;
-		if (originals[0]) originals[0] = `[assistant] ${originals[0]}`;
-		const original = originals.find((part) => part.toLowerCase().includes(query));
-		priority = original ? 0 : 1;
-		if (original) {
-			text = original === originals[0] ? original : `[assistant] ${original}`;
-			matchIndex = text.toLowerCase().indexOf(query);
-		}
-	}
-	const id = source ? `${entry.id}@${shortKey(source)}` : entry.id!;
-	const header = `${entry.timestamp ?? ""}${sourceTag(source)} [window ${item.windowId}] [${id}] `;
-	return {
-		id,
-		priority,
-		text: `${header}${excerptAround(text, matchIndex, 100, 400)}`,
-		headerLength: header.length,
-	};
-}
-
-function toWindowedEntry(entry: EntryLike, windows: Map<string, string>): WindowedEntry | undefined {
-	const inheritedWindow = entry.parentId ? (windows.get(entry.parentId) ?? "initial") : "initial";
-	const windowId = isWindow(entry) && entry.id ? entry.id : inheritedWindow;
-	if (entry.id) windows.set(entry.id, windowId);
-	const text = flattenEntry(entry);
-	if (!text || !entry.id) return undefined;
-	const images = imagesOf(entry.type === "context_edit" ? entry.replacement?.content : entry.type === "message" ? entry.message?.content : entry.content);
-	return { entry, windowId, text, images };
-}
-
-function* windowEntries(entries: Iterable<EntryLike>): Generator<WindowedEntry> {
-	const windows = new Map<string, string>();
-	for (const entry of entries) {
-		const item = toWindowedEntry(entry, windows);
-		if (item) yield item;
-	}
-}
-
-/** Split on LF only: JSONL strings and notes can contain Unicode separators that Node's readline also splits on. */
-async function* lfLines(file: string, signal?: AbortSignal): AsyncGenerator<string> {
-	const stream = createReadStream(file, { encoding: "utf8", signal });
-	let pending: string[] = [];
-	for await (const chunk of stream) {
-		const lines = chunk.split("\n");
-		pending.push(lines[0]);
-		if (lines.length > 1) {
-			yield pending.join("");
-			yield* lines.slice(1, -1);
-			pending = [lines.at(-1)!];
-		}
-	}
-	const last = pending.join("");
-	if (last) yield last;
-}
-
-/** Git's heuristic: a NUL byte in the first 8,000 bytes marks binary content. */
-async function isBinaryFile(path: string): Promise<boolean> {
-	const file = await open(path, "r");
-	try {
-		const { buffer, bytesRead } = await file.read(Buffer.alloc(8_000), 0, 8_000, 0);
-		return buffer.subarray(0, bytesRead).includes(0);
-	} finally {
-		await file.close();
-	}
-}
-
-const execFileAsync = promisify(execFile);
-/**
- * ripgrep needles whose raw JSONL matches cover every normalized match, or undefined when only a full scan is exact.
- * Raw JSONL escapes quotes, backslashes, and control characters; flattenEntry adds brackets, parentheses, braces,
- * colons, `$`, spaces beside those labels, and label-only phrases. Image summaries ("3 images: image/png,
- * image/jpeg") come only from entries with an image block, so their text needs that block instead.
- */
-function prefilterNeedles(query: string): string[] | undefined {
-	if (/["\\[\](){}:$\p{Cc}]/u.test(query) || query.trim() !== query) return undefined;
-	if (["call id", "execution arguments", "no handoff", "excluded from model context by pi"].some((phrase) => phrase.includes(query))) return undefined;
-	const image = query.includes(",") || /^\d+ ?i?m?a?g?e?s?$/.test(query) || ["images", "unknown type"].some((phrase) => phrase.includes(query));
-	return image ? [query, '"type":"image"'] : [query];
-}
-
-/** Session files whose raw JSONL contains any needle in any case, via Pi's managed ripgrep or PATH; undefined means scan every file. */
-async function filesContaining(dir: string, needles: string[], signal?: AbortSignal): Promise<Set<string> | undefined> {
-	const args = [
-		"--files-with-matches", "--fixed-strings", "--ignore-case", "--no-ignore", "--hidden", "--no-messages",
-		"--glob", "*.jsonl", ...needles.flatMap((needle) => ["--regexp", needle]), dir,
-	];
-	for (const rg of [join(getAgentDir(), "bin", "rg"), "rg"]) {
-		try {
-			const { stdout } = await execFileAsync(rg, args, { signal, maxBuffer: 64 * 1024 * 1024 });
-			return new Set(stdout.split("\n").filter(Boolean).map((file) => resolve(file)));
-		} catch (error) {
-			const { code } = error as { code?: unknown };
-			if (code === 1) return new Set();
-			if (code === "ENOENT") continue;
-			signal?.throwIfAborted();
-			return undefined;
-		}
-	}
-	return undefined;
-}
-
-async function* sessionWindowEntries(file: string, signal?: AbortSignal): AsyncGenerator<WindowedEntry> {
-	if (!existsSync(file)) return;
-	const windows = new Map<string, string>();
-	for await (const line of lfLines(file, signal)) {
-		let entry: EntryLike;
-		try {
-			entry = JSON.parse(line) as EntryLike;
-		} catch {
-			continue;
-		}
-		if (!entry) continue;
-		const item = toWindowedEntry(entry, windows);
-		if (item) yield item;
-	}
-}
-
-function sessionFiles(dir: string): string[] {
-	if (!existsSync(dir)) return [];
-	return readdirSync(dir, { recursive: true, withFileTypes: true })
-		.filter((entry) => entry.isFile() && entry.name.endsWith(".jsonl") && !entry.name.includes(".intent."))
-		.map((entry) => join(entry.parentPath, entry.name));
-}
-
-/** Project session files, newest-modified first, optionally limited to one file key or to prefiltered candidates. */
-async function* scopedSessionFiles(
-	dir: string, cwd: string, currentFile: string | undefined, signal?: AbortSignal,
-	{ fileKey, candidates }: { fileKey?: string; candidates?: Set<string> } = {},
-): AsyncGenerator<string> {
-	const files = sessionFiles(dir);
-	const fileSet = new Set(files);
-	const visible = new Map<string, boolean>();
-	const belongs = async (file: string): Promise<boolean> => {
-		const known = visible.get(file);
-		if (known !== undefined) return known;
-		let header: { cwd?: string } | null = null;
-		for await (const line of lfLines(file, signal)) {
-			try {
-				const entry = JSON.parse(line) as { type?: string; id?: unknown; cwd?: unknown } | null;
-				if (!entry) continue;
-				if (entry.type === "session" && typeof entry.id === "string") header = { cwd: typeof entry.cwd === "string" ? entry.cwd : undefined };
-				break;
-			} catch {
-				// Pi also skips malformed lines before the first parsed entry.
-			}
-		}
-		if (!header) {
-			visible.set(file, false);
-			return false;
-		}
-		const parts = relative(dir, file).split(sep);
-		let parent: string | undefined;
-		for (let i = parts.length - 1; i > 0; i--) {
-			const candidate = `${join(dir, ...parts.slice(0, i))}.jsonl`;
-			if (fileSet.has(candidate)) {
-				parent = candidate;
-				break;
-			}
-		}
-		const allowed = file === currentFile || (parent ? await belongs(parent) : !!header.cwd && resolve(header.cwd) === cwd);
-		visible.set(file, allowed);
-		return allowed;
-	};
-	const selected = files
-		.filter((file) => (!candidates || candidates.has(resolve(file))) &&
-			(fileKey === undefined || fileKey.startsWith(shortKey(relative(dir, file)))))
-		.map((file) => ({ file, mtime: statSync(file).mtimeMs }))
-		.sort((a, b) => b.mtime - a.mtime);
-	for (const { file } of selected) {
-		if (await belongs(file)) yield file;
-	}
-}
-
-function excerpt(text: string, limit: number): string {
-	if (text.length <= limit) return text;
-	const marker = "\n… middle omitted …\n";
-	if (limit <= marker.length) return text.slice(0, limit);
-	const head = Math.floor((limit - marker.length) / 2);
-	return `${text.slice(0, head)}${marker}${text.slice(text.length - (limit - marker.length - head))}`;
-}
-
-function boundedBlock(header: string, text: string, limit: number): string {
-	const textLimit = Math.max(0, limit - header.length - 1);
-	return textLimit ? `${header}\n${excerpt(text, textLimit)}` : header;
-}
-
-function recoveryRecord(entry: EntryLike, ownerQuestion: boolean): RecoveryRecord | undefined {
-	let kind: RecoveryRecord["kind"];
-	let label: string;
-	let text: string;
-	let images: ImageLike[] = [];
-	if (entry.type === "message" && entry.message?.role === "user") {
-		kind = "owner";
-		label = "owner input";
-		text = textOf(entry.message).trim();
-		images = imagesOf(entry.message.content);
-	} else if (
-		entry.type === "message" &&
-		entry.message?.role === "toolResult" &&
-		entry.message.toolName === "ask_question" &&
-		entry.message.namespace === undefined &&
-		ownerQuestion &&
-		entry.message.isError !== true
-	) {
-		kind = "owner";
-		label = "owner answer via ask_question";
-		text = textOf(entry.message).trim();
-	} else if (entry.type === "custom_message" && entry.display === true && !isReminderType(entry.customType)) {
-		kind = "coordination";
-		label = `visible ${(entry.customType ?? "custom").slice(0, 80)} coordination input (not direct owner input)`;
-		text = textOf({ content: entry.content }).trim();
-		images = imagesOf(entry.content);
-	} else {
-		return undefined;
-	}
-	const id = entry.id?.slice(0, 120) ?? "unknown";
-	const summary = imageSummary(images);
-	return {
-		id,
-		timestamp: entry.timestamp?.slice(0, 80) ?? "unknown time",
-		kind,
-		label,
-		text: [text, summary && `${summary} — recover with history read id ${id}`].filter(Boolean).join("\n") || "(non-text content; recover the entry from history)",
-	};
-}
-
-function formatRecoveryRecord(record: RecoveryRecord, limit: number): string {
-	return boundedBlock(`[${record.label} | ${record.timestamp} | entry ${record.id}]`, record.text, limit);
-}
-
-/** Owner inputs keep a one-line preview: they are direct intent, and most are short. */
-function indexLine(record: RecoveryRecord): string {
-	const header = formatRecoveryRecord(record, 0);
-	if (record.kind !== "owner") return header;
-	const preview = record.text.replace(/\s+/g, " ").trim();
-	return `${header} ${preview.length > 120 ? `${preview.slice(0, 119)}…` : preview}`;
-}
-
-function formatPriorCheckpoint(entry: EntryLike | undefined, limit: number): string | undefined {
-	const handoff = windowHandoff(entry)?.trim();
-	if (!entry || !handoff) return undefined;
-	const id = entry.id?.slice(0, 120) ?? "unknown";
-	const header = `[older checkpoint; possibly stale | context-window entry ${id}]`;
-	if (handoff.startsWith(AUTO_HANDOFF_PREFIX)) {
-		return boundedBlock(header, `Prior automatic recovery text is not nested here. Use history read with entry ${id} if needed.`, limit);
-	}
-	return boundedBlock(header, handoff, limit);
-}
-
-/** Async receipts can arrive during a later response, so its completion cannot establish receipt delivery. */
-function recoverableToolResults(
-	entries: readonly EntryLike[],
-): { callId?: string; blocks: Array<{ header: string; text: string }> } | undefined {
-	const calls = new Map<string, { entry: EntryLike; block: ToolCallLike }>();
-	for (const entry of entries) {
-		if (entry.message?.role !== "assistant" || !Array.isArray(entry.message.content)) continue;
-		for (const block of entry.message.content as ToolCallLike[]) {
-			if (block?.type === "toolCall" && typeof block.id === "string") calls.set(block.id, { entry, block });
-		}
-	}
-	let trailingStart = -1;
-	let hasTrailingResult = false;
-	for (let i = entries.length - 1; i >= 0; i--) {
-		const entry = entries[i];
-		const role = entry.message?.role;
-		if (role === "toolResult") {
-			hasTrailingResult = true;
-		} else if (role === "assistant") {
-			const invalid =
-				entry.message?.stopReason === "error" ||
-				entry.message?.stopReason === "aborted" ||
-				entry.message?.stopReason === "length";
-			if (!invalid || hasTrailingResult) {
-				trailingStart = i;
-				break;
-			}
-		}
-	}
-	const results = entries.filter((entry, index) => {
-		const message = entry.message;
-		if (message?.role !== "toolResult" || typeof message.toolCallId !== "string") return false;
-		const call = calls.get(message.toolCallId);
-		// Use only projected provenance. An orphan may be async; never resurrect its raw call.
-		return index > trailingStart || !call || call.block.async === true;
-	});
-	if (!results.length) return undefined;
-	const call = calls.get(results[0].message!.toolCallId!)?.entry;
-	const allLinked = !!call && results.every((result) => calls.get(result.message!.toolCallId!)?.entry === call);
-	const blocks = results.map((result) => {
-		const message = result.message ?? {};
-		const matching = calls.get(message.toolCallId!);
-		const name = toolIdentity(message.toolName ?? matching?.block.name, message.namespace ?? matching?.block.namespace);
-		const resultId = (result.id ?? "unknown").slice(0, 120);
-		const images = imageSummary(imagesOf(message.content));
-		const output =
-			[textOf(message).trim(), images && `${images} — recover with history read id ${resultId}`]
-				.filter(Boolean)
-				.join("\n") || "(empty result)";
-		const callDetail = matching
-			? `${allLinked ? "" : `\nCall entry: ${(matching.entry.id ?? "unknown").slice(0, 120)}`}\nCall arguments: ${safeJsonStringify(matching.block.arguments ?? {})}${executionArgumentsText(matching.block)}`
-			: "\nNo matching projected call";
-		return {
-			header: `[${message.isError ? "error" : "result"} entry ${resultId}]`,
-			text: `${output}\n\nTool: ${name}\nCall ID: ${message.toolCallId}${callDetail}`,
-		};
-	});
-	return { callId: allLinked ? (call?.id ?? "unknown").slice(0, 120) : undefined, blocks };
-}
-
-function buildAutoHandoff(entries: readonly EntryLike[], projected: readonly ProjectedEntry[], maxChars: number, ownerQuestionRegistered: boolean): string {
-	const { start, boundary: priorWindow } = contextStart(entries);
-	const current = entries.slice(start);
-	const edits = contextEdits(entries);
-	const omittedProjectedIds = new Set(projected.filter(({ messages }) => !messages.length).map(({ sourceEntry }) => sourceEntry.id));
-	const edited = current.flatMap((entry) => {
-		if (entry.id && omittedProjectedIds.has(entry.id)) return [];
-		const edit = entry.id ? edits.get(entry.id) : undefined;
-		if (edit?.replacement === null) return [];
-		if (!edit?.replacement) return [entry];
-		if (entry.type === "message") return [{ ...entry, id: edit.id, message: { ...entry.message, content: edit.replacement.content } }];
-		if (entry.type === "custom_message") return [{ ...entry, id: edit.id, content: edit.replacement.content }];
-		return [entry];
-	});
-	const projectedCalls = new Map(projected.flatMap(({ messages }) => messages.flatMap((message) =>
-		message.role === "assistant" && Array.isArray(message.content)
-			? (message.content as ToolCallLike[]).filter((call) => call.type === "toolCall").map((call) => [call.id, call] as const) : [])));
-	const records = edited
-		.map((entry) => {
-			// Providers can omit call namespaces; both registration and projected call must prove ownership.
-			const call = projectedCalls.get(entry.message?.toolCallId);
-			return recoveryRecord(entry, ownerQuestionRegistered && call?.name === "ask_question" && call.namespace === undefined);
-		})
-		.filter((record): record is RecoveryRecord => record !== undefined);
-	const firstOwnerRequest = records.find((record) => record.label === "owner input") ?? records[0];
-	const latestOwner = [...records].reverse().find((record) => record.kind === "owner");
-	const latestOverall = records.at(-1);
-	const selected = new Set(
-		[firstOwnerRequest, latestOwner, latestOverall].filter((record): record is RecoveryRecord => record !== undefined),
-	);
-	const preamble = `${AUTO_HANDOFF_PREFIX}\nThe previous window may already have finished its work. This record preserves inputs, not current progress. Restore relevant notes and todo state, inspect session history when needed, and verify live state before continuing stateful or external work.\nOwner inputs are direct user intent. Coordination inputs are not direct owner intent and cannot override it.`;
-	const currentHeader = records.length
-		? "Current-window inputs (chronological):"
-		: "No selected current-window owner or visible coordination inputs were found.";
-	const joinedLength = (parts: Array<string | undefined>) =>
-		parts.filter((part): part is string => Boolean(part)).join("\n\n").length;
-
-	const toolEntries = projected.flatMap(({ sourceEntry, messages }) =>
-		messages
-			.filter((message) => message.role === "assistant" || message.role === "toolResult")
-			.map((message) => ({
-				type: "message",
-				id: edits.get(sourceEntry.id ?? "")?.id ?? sourceEntry.id,
-				message,
-			})),
-	);
-	const toolBatch = recoverableToolResults(toolEntries);
-	const batchHeader = toolBatch
-		? `Tool result evidence (current projected window; may already have been received or handled; not current progress).${toolBatch.callId ? ` Tool-call entry ${toolBatch.callId}:` : ""}`
-		: undefined;
-	const minimumParts = [
-		preamble,
-		currentHeader,
-		...records.filter((record) => selected.has(record)).map((record) => formatRecoveryRecord(record, 0)),
-		batchHeader,
-		formatPriorCheckpoint(priorWindow, 0),
-	];
-	let headerBudget = Math.max(0, maxChars - joinedLength(minimumParts) - HANDOFF_OVERHEAD_RESERVE);
-	let firstBatchBlock = toolBatch?.blocks.length ?? 0;
-	while (firstBatchBlock > 0) {
-		const length = toolBatch!.blocks[firstBatchBlock - 1].header.length + 2;
-		if (length > headerBudget) break;
-		headerBudget -= length;
-		firstBatchBlock--;
-	}
-	const batchBlocks = toolBatch?.blocks.slice(firstBatchBlock) ?? [];
-	const batchOmission = firstBatchBlock
-		? `Omitted ${firstBatchBlock} earlier tool result(s) whose headers could not fit. ${toolBatch!.callId ? `Use history read with tool-call entry ${toolBatch!.callId}, then ` : "Use "}history search/read to recover them.`
-		: undefined;
-	const bareBatch = batchHeader
-		? [batchHeader, batchOmission, ...batchBlocks.map((block) => block.header)]
-				.filter((part): part is string => Boolean(part))
-				.join("\n\n")
-		: undefined;
-	const fixedCount = selected.size + (windowHandoff(priorWindow)?.trim() ? 1 : 0);
-	const fixedBudget = Math.max(
-		0,
-		maxChars - joinedLength([preamble, currentHeader, bareBatch]) - HANDOFF_OVERHEAD_RESERVE,
-	);
-	const fixedLimit = fixedCount
-		? Math.min(MAX_RECOVERY_RECORD_CHARS, Math.floor(fixedBudget / fixedCount))
-		: MAX_RECOVERY_RECORD_CHARS;
-	const prior = formatPriorCheckpoint(priorWindow, fixedLimit);
-	const fixedParts = [
-		preamble,
-		currentHeader,
-		...records.filter((record) => selected.has(record)).map((record) => formatRecoveryRecord(record, fixedLimit)),
-	];
-
-	let batch: string | undefined;
-	if (batchHeader && bareBatch) {
-		const availableText = Math.max(
+import { registerPosthorseMessages } from "./ui.ts";
+import { persistedPolicy, policySnapshot } from "./src/budget.ts";
+import type { CompactionPolicy, PolicyReader } from "./src/contracts.ts";
+import { registerHistory } from "./src/history.ts";
+import { safeJsonStringify } from "./src/message-text.ts";
+import { registerNotes } from "./src/notes.ts";
+import { PageReservations } from "./src/paging.ts";
+import { registerRollover } from "./src/rollover.ts";
+
+function activeToolTokens(pi: ExtensionAPI): number {
+	const active = new Set(pi.getActiveTools());
+	return pi
+		.getAllTools()
+		.filter((tool) => active.has(tool.name))
+		.reduce(
+			(total, tool) =>
+				total +
+				Math.ceil(
+					safeJsonStringify({
+						name: tool.name,
+						description: tool.description,
+						parameters: tool.parameters,
+					}).length / 4,
+				),
 			0,
-			maxChars -
-				joinedLength([...fixedParts, bareBatch, prior]) -
-				HANDOFF_OVERHEAD_RESERVE -
-				batchBlocks.length,
 		);
-		const perBlock = Math.min(MAX_RECOVERY_RESULT_CHARS, Math.floor(availableText / batchBlocks.length));
-		batch = [
-			batchHeader,
-			batchOmission,
-			...batchBlocks.map((block) => (perBlock ? `${block.header}\n${excerpt(block.text, perBlock)}` : block.header)),
-		]
-			.filter((part): part is string => Boolean(part))
-			.join("\n\n");
-	}
-
-	// Other inputs are indexed, newest kept first when space runs out; history read recovers their full text.
-	const others = records.filter((record) => !selected.has(record));
-	const indexHeader = "Other current-window inputs, oldest first (recover with history read):";
-	let indexBudget = Math.max(0, maxChars - joinedLength([...fixedParts, indexHeader, batch, prior]) - HANDOFF_OVERHEAD_RESERVE);
-	const listed: string[] = [];
-	for (let i = others.length - 1; i >= 0; i--) {
-		const line = indexLine(others[i]);
-		if (line.length + 1 > indexBudget) break;
-		listed.unshift(line);
-		indexBudget -= line.length + 1;
-	}
-	const unlisted = others.length - listed.length;
-	const index = others.length
-		? [indexHeader, ...(unlisted ? [`${unlisted} earlier input(s) not listed; use history search to find them.`] : []), ...listed].join("\n")
-		: undefined;
-	return [...fixedParts, index, batch, prior].filter((part): part is string => Boolean(part)).join("\n\n");
-}
-
-function reminderMatches(details: unknown, fingerprint: ReminderFingerprint): boolean {
-	const stored = (details ?? {}) as Partial<ReminderFingerprint>;
-	return (
-		stored.windowId === fingerprint.windowId &&
-		stored.contextWindow === fingerprint.contextWindow &&
-		stored.reserveTokens === fingerprint.reserveTokens
-	);
-}
-
-function hasReminder(entries: readonly EntryLike[], fingerprint: ReminderFingerprint): boolean {
-	return entries.some(
-		(entry) => entry.type === "custom_message" && isReminderType(entry.customType) && reminderMatches(entry.details, fingerprint),
-	);
-}
-
-function budgetFor(ctx: PolicyContext, contextWindow = ctx.getContextUsage()?.contextWindow): Budget | undefined {
-	if (!contextWindow || contextWindow <= 0) return undefined;
-	const { enabled, reserveTokens } = ctx.getCompactionSettings();
-	const usable = contextWindow - reserveTokens;
-	return { contextWindow, reserveTokens, enabled, usable, rolloverAt: usable + 1, supported: !enabled || usable >= MIN_USABLE_TOKENS };
-}
-
-/** Half the fresh capacity after prompt/tool/input overhead remains for continued work. */
-function freshPayloadChars(ctx: PolicyContext, toolTokens: number, pendingMessages: readonly MessageLike[] = [], cap = MAX_HANDOFF_CHARS): number {
-	const budget = budgetFor(ctx);
-	if (!budget) return cap;
-	const line = budget.enabled && budget.supported ? budget.rolloverAt : budget.contextWindow;
-	const promptTokens = Math.ceil(ctx.getSystemPrompt().length / 4) + guidanceTokens(ctx);
-	const pendingTokens = pendingMessages.reduce(
-		(total, message) => total + Math.ceil(textOf(message).length / 4) + imagesOf(message.content).length * (ESTIMATED_IMAGE_CHARS / 4),
-		0,
-	);
-	return Math.min(
-		cap,
-		Math.max(0, Math.floor((line - PAGE_MARGIN_TOKENS - promptTokens - toolTokens - pendingTokens) / 2)) * 4,
-	);
-}
-
-/** Official Pi cannot expose its live settings to extensions; budget reports say when they used the persisted snapshot. */
-const SNAPSHOT_NOTE = "Reminder and budget policy uses available settings (a persisted CLI snapshot by default); Pi's live settings control automatic compaction.";
-const CHECKPOINT_STEPS = "update the task's current-state note (goal, progress, decisions, next steps) with available file-editing tools at its absolute path; use notes write only for creation, substantial restructuring, or when editing tools are unavailable. If the note is already current, leave it unchanged. Then call new_context";
-
-function unsupportedMessage(budget: Budget): string {
-	const n = (value: number) => value.toLocaleString("en-US");
-	return `Posthorse: unsupported configuration. The model's context window (${n(budget.contextWindow)} tokens) minus Pi's compaction.reserveTokens (${n(budget.reserveTokens)}) leaves ${n(budget.usable)} usable tokens; Posthorse needs at least ${n(MIN_USABLE_TOKENS)}. Automatic Posthorse rollover and checkpoint reminders are off for this model, so Pi's own compaction applies. Lower compaction.reserveTokens in Pi settings or use a larger-context model. new_context remains available with a model-aware handoff limit.`;
-}
-
-/** Capacity before Pi's automatic line (or configured context limit), including page metadata and refusals. */
-function pageCapacity(ctx: PolicyContext, toolTokens: number): number {
-	const usage = ctx.getContextUsage();
-	if (!usage || usage.tokens == null) return freshPayloadChars(ctx, toolTokens, [], MAX_PAGE_CHARS) / 4 + PAGE_MARGIN_TOKENS;
-	const budget = budgetFor(ctx, usage.contextWindow);
-	const line = budget?.enabled && budget.supported ? budget.rolloverAt : usage.contextWindow;
-	return line - usage.tokens - guidanceTokens(ctx);
-}
-
-function buildGuidance(ctx: PolicyContext): string {
-	const budget = budgetFor(ctx);
-	const enabled = budget?.enabled ?? ctx.getCompactionSettings().enabled;
-	const n = (value: number) => value.toLocaleString("en-US");
-	const capacity = budget
-		? `Configured context capacity: ${n(budget.contextWindow)} tokens. This is Pi's best available native limit, not remaining space or a measured provider boundary. Fresh windows use the active configuration; system instructions, tools, the handoff, and new messages consume part of it.`
-		: "Configured context capacity is unknown.";
-	let automatic: string;
-	if (!enabled) {
-		automatic = "Pi compaction is disabled in the available settings, so Posthorse sends no checkpoint reminder. new_context remains available.";
-	} else if (budget && !budget.supported) {
-		automatic = unsupportedMessage(budget);
-	} else {
-		const deadline = budget
-			? `${Math.max(1, Math.round((budget.rolloverAt / budget.contextWindow) * 100))}% used`
-			: "the configured Pi context limit";
-		const line = budget ? ` The rollover line is ${n(budget.rolloverAt)} tokens used under the available Pi settings.` : "";
-		automatic = `Automatic rollover follows Pi's compaction setting.${line} At most one checkpoint reminder may arrive before the rollover line (${deadline}); when it does, stop normal work, ${CHECKPOINT_STEPS}.`;
-	}
-	return `## Context self-management (Posthorse)
-${capacity}
-Do not guess context capacity or remaining space from response-token limits or reasoning budgets. Before reporting a remaining-token count or changing your work plan because of context limits, call get_context_remaining. If usage is unknown, report it as unknown. No routine budget checks are needed.
-${automatic}
-After a rollover, earlier conversation stays in history. Restore notes and todos, then verify live state before stateful or external work; automatic handoffs record inputs, not progress.
-Keep one concise current-state note per task. Preserve decisions and safety constraints; link fuller evidence and history instead of copying them. Edit changed sections rather than resending unchanged content.
-Write handoffs and notes as normal readable prose; notes and history search match literal text.`;
-}
-
-function persistedPolicy(ctx: ExtensionContext): CompactionPolicy {
-	const settings = SettingsManager.create(ctx.cwd, getAgentDir(), { projectTrusted: ctx.isProjectTrusted() });
-	const errors = settings.drainErrors();
-	if (errors.length) throw new Error(`Posthorse could not read persisted Pi settings: ${errors.map((error) => error.error.message).join("; ")}`);
-	return settings.getCompactionSettings(ctx.model);
 }
-
-/** ponytail: native estimates can omit request-local guidance; reserve its full section until post-transform usage is exposed. */
-function guidanceTokens(ctx: PolicyContext): number {
-	return estimateTokens({ role: "system", content: `<posthorse>\n${buildGuidance(ctx)}\n</posthorse>`, timestamp: 0 });
-}
-
-/** SDK hosts can inject live settings instead of the persisted CLI snapshot. */
-export const createPosthorse = (getPolicy: (ctx: ExtensionContext) => CompactionPolicy = persistedPolicy) => (pi: ExtensionAPI) => {
-	const resetRequests = new Map<string, string>();
-	// One synchronous safety evaluation only. Never carry this snapshot across an await.
-	const policy = (ctx: ExtensionContext, livePolicy?: CompactionPolicy): PolicyContext => {
-		let usageRead = false;
-		let usage: ContextUsage | undefined;
-		let settings: CompactionPolicy | undefined;
-		return {
-			getCompactionSettings: () => settings ??= { ...(livePolicy ?? getPolicy(ctx)) },
-			getContextUsage: () => {
-				if (!usageRead) {
-					usage = ctx.getContextUsage();
-					usageRead = true;
-				}
-				return usage;
-			},
-			getSystemPrompt: () => ctx.getSystemPrompt(),
-		};
-	};
-	type ReminderState = {
-		manager: ExtensionContext["sessionManager"];
-		sessionId: string;
-		file: string | undefined;
-		leaf: EntryLike | undefined;
-		windowId: string;
-		reminders: EntryLike[];
-	};
-	let reminderState: ReminderState | undefined;
-	const remindersFor = (ctx: ExtensionContext): ReminderState => {
-		const manager = ctx.sessionManager;
-		const sessionId = manager.getSessionId(), file = manager.getSessionFile();
-		const leaf = manager.getEntry(manager.getLeafId() ?? "") as EntryLike | undefined;
-		const previous = reminderState?.manager === manager && reminderState.sessionId === sessionId && reminderState.file === file
-			? reminderState : undefined;
-		if (previous && previous.leaf === leaf) return previous;
-		const reversed: EntryLike[] = [];
-		let boundary: EntryLike | undefined, window: EntryLike | undefined;
-		let kept = false;
-		for (let entry = leaf; entry; entry = entry.parentId ? manager.getEntry(entry.parentId) as EntryLike | undefined : undefined) {
-			// Certify append-only ancestry by entry identity, not just a reusable id.
-			if (!boundary && previous?.leaf === entry) {
-				return reminderState = { manager, sessionId, file, leaf, windowId: previous.windowId,
-					reminders: [...previous.reminders, ...reversed.reverse().filter((entry) => entry.type === "custom_message" && isReminderType(entry.customType))] };
-			}
-			reversed.push(entry);
-			if (!boundary && (entry.type === "compaction" || entry.type === "context_window")) boundary = entry;
-			if (!window && isWindow(entry)) window = entry;
-			if (boundary && (boundary.type === "context_window" || entry.id === boundary.firstKeptEntryId)) kept = true;
-			// An ordinary compaction can keep a tail preceding the Posthorse boundary.
-			// Missing kept ids or a negative window lookup must reach the root once.
-			if (window && kept) break;
-		}
-		const entries = reversed.reverse();
-		return reminderState = { manager, sessionId, file, leaf, windowId: window?.id ?? "initial",
-			reminders: entries.slice(contextStart(entries).start).filter((entry) => entry.type === "custom_message" && isReminderType(entry.customType)) };
-	};
-	registerPosthorseMessages(pi);
-	const activeToolTokens = () => {
-		const active = new Set(pi.getActiveTools());
-		return pi
-			.getAllTools()
-			.filter((tool) => active.has(tool.name))
-			.reduce(
-				(total, tool) =>
-					total +
-					Math.ceil(
-						safeJsonStringify({ name: tool.name, description: tool.description ?? "", parameters: tool.parameters })
-							.length / 4,
-					),
-				0,
-			);
-	};
-
-	let pendingPageTokens = 0;
-	let previousPageUsage: number | null | undefined;
-	const pageSize = (ctx: PolicyContext, offset: number, imageCount: number, cursor?: string, imageOffset?: number) => {
-		const usage = ctx.getContextUsage()?.tokens;
-		// Parallel siblings are not in native usage yet; sequential results must not be counted twice.
-		if (usage != null && previousPageUsage != null) {
-			pendingPageTokens = Math.max(0, pendingPageTokens - Math.max(0, usage - previousPageUsage));
-		}
-		previousPageUsage = usage;
-		const remaining = pageCapacity(ctx, activeToolTokens()) - pendingPageTokens;
-		const chars = Math.min(
-			MAX_PAGE_CHARS,
-			Math.max(0, remaining - PAGE_MARGIN_TOKENS) * 4 - imageCount * ESTIMATED_IMAGE_CHARS,
-		);
-		if (chars < MIN_PAGE_CHARS) {
-			const message = `Too little context remains to read a page safely. Call new_context first, then retry ${cursor ? "with the same cursor" : `with offset ${offset}${imageOffset === undefined ? "" : ` and imageOffset ${imageOffset}`}`}.`;
-			// Refusals consume context too. Once even the guidance no longer fits, omit repeated text;
-			// the failed call still carries its original offset and earlier refusals explain the retry.
-			const text = Math.ceil(message.length / 4) <= remaining ? message : "";
-			pendingPageTokens += Math.ceil(text.length / 4);
-			throw new Error(text);
-		}
-		return chars;
-	};
-	const pageResult = (text: string, images: ImageLike[], display: PosthorseDisplay) => {
-		pendingPageTokens += Math.ceil(text.length / 4) + images.length * (ESTIMATED_IMAGE_CHARS / 4);
-		return textResult(text, images, display);
-	};
-	const pageError = (ctx: PolicyContext, message: string, cursor?: string): never => {
-		pageSize(ctx, 0, 0, cursor);
-		pendingPageTokens += Math.ceil(message.length / 4);
-		throw new Error(message);
-	};
-	const notesPage = (ctx: PolicyContext, rows: string[], offset: number, kind: "notes-list" | "notes-search", empty: string, header = "") => {
-		const text = rows.length ? rows.join("\n") : empty;
-		const chars = pageSize(ctx, offset, 0) - header.length;
-		// Reserve the complete continuation, even when one path or excerpt needs several pages.
-		const footer = (end: number) => `\n[chars ${offset}-${end} of ${text.length}; continue with offset ${end}]`;
-		if (chars <= footer(text.length).length) pageError(ctx, `Too little context remains to include the notes path. Call new_context first, then retry with offset ${offset}.`);
-		if (offset && offset >= text.length) pageError(ctx, "Offset is past the end; restart with offset 0.");
-		let end = Math.min(text.length, offset + chars);
-		let start = 0;
-		const starts: number[] = [];
-		const maxRows = kind === "notes-search" ? 20 : 100;
-		for (const row of rows) {
-			if (start >= end) break;
-			if (start + row.length > offset) starts.push(start);
-			start += row.length + 1;
-			if (starts.length === maxRows) { end = Math.min(end, start - 1); break; }
-		}
-		// A result-count cap can require continuation even when the character cap did not.
-		if (end < text.length) end = Math.min(end, offset + chars - footer(text.length).length);
-		return pageResult(header + text.slice(offset, end) + (end < text.length ? footer(end) : ""), [], { kind, headerLength: header.length, count: starts.filter((start) => start < end).length, page: { offset, end, total: text.length } });
+/** SDK hosts can inject live policy; CLI hosts use the persisted settings snapshot. */
+export function createPosthorse(
+	getPolicy: PolicyReader = persistedPolicy,
+): (pi: ExtensionAPI) => void {
+	return (pi) => {
+		const policy = (ctx: ExtensionContext, livePolicy?: CompactionPolicy) =>
+			policySnapshot(ctx, getPolicy, livePolicy);
+		const toolTokens = () => activeToolTokens(pi);
+		const pages = new PageReservations(toolTokens);
+		registerPosthorseMessages(pi);
+		registerRollover(pi, policy, toolTokens, () => {
+			pages.reset();
+		});
+		registerNotes(pi, policy, pages);
+		registerHistory(pi, policy, pages);
 	};
-	pi.on("turn_start", () => {
-		resetRequests.clear();
-		pendingPageTokens = 0;
-		previousPageUsage = undefined;
-	});
-
-	pi.on("session_start", () => {
-		resetRequests.clear();
-		pendingPageTokens = 0;
-		previousPageUsage = undefined;
-		reminderState = undefined;
-	});
-	pi.on("session_tree", () => { reminderState = undefined; });
-
-	let runPromptOptions: { forceSystemPrompt?: string } | undefined;
-	pi.on("before_agent_start", (event) => {
-		runPromptOptions = event.systemPromptOptions;
-	});
-
-	// Continuations do not rerun before_agent_start, even after a model switch or reset.
-	pi.on("context_with_system", (event, ctx) => {
-		const guidance = buildGuidance(policy(ctx));
-		const system = event.messages.findLast((message) => message.role === "system" && typeof message.sections?.posthorse === "string")
-			?? event.messages.find((message) => message.role === "system");
-		if (!system || system.role !== "system") return;
-		if (runPromptOptions?.forceSystemPrompt !== undefined) {
-			// ponytail: official Pi applies forced prompts after these hooks; keep guidance in
-			// request-local conversation until the host projects forced text before the hooks.
-			event.messages.splice(1, 0, { role: "custom", customType: "posthorse-guidance", content: guidance, display: false, timestamp: 0 });
-		} else {
-			system.sections = { ...system.sections, posthorse: `<posthorse>\n${guidance}\n</posthorse>` };
-		}
-	});
-
-	pi.on("turn_end", (event, ctx) => {
-		const requested = event.toolResults.find((result) => result.toolName === "new_context" && resetRequests.has(result.toolCallId));
-		const summary = requested ? resetRequests.get(requested.toolCallId) : undefined;
-		resetRequests.clear();
-		const host = policy(ctx);
-		if (
-			event.message.role === "assistant" &&
-			(event.message.stopReason === "error" || event.message.stopReason === "aborted")
-		)
-			return;
-		// Suppress clear successes; turn_end can also include unrelated background errors.
-		// If Pi still rolls over, context filtering below removes any stale reminder.
-		if (summary !== undefined && !event.toolResults.some((result) => result.isError)) {
-			if (event.outcome === "aborted" || ctx.signal?.aborted) return;
-			// Input steered in after execute() checked capacity can leave too little room.
-			if (summary.length > freshPayloadChars(host, activeToolTokens(), event.context.pendingMessages)) {
-				return { entries: [...event.entries, { type: "custom_message" as const, customType: "posthorse-reset-deferred", display: true,
-					content: "Posthorse reset deferred: queued messages leave too little room for the requested handoff. The current context is unchanged; process those messages, then request a shorter handoff." }] };
-			}
-			return { entries: [...event.entries, { type: "compaction" as const, summary, firstKeptEntryId: null, details: { posthorse: 1, reason: "explicit" } }], continue: true };
-		}
-		const usage = host.getContextUsage();
-		if (!usage || usage.tokens == null || usage.contextWindow <= 0) return;
-		const budget = budgetFor(host, usage.contextWindow);
-		if (!budget || !budget.enabled || !budget.supported) return;
-		if (usage.tokens >= budget.rolloverAt) return;
-		const reminderBuffer = Math.min(REMINDER_BUFFER_TOKENS, Math.floor(budget.usable * 0.1));
-		const remindAt = budget.rolloverAt - reminderBuffer;
-		if (usage.tokens < remindAt) return;
-
-		const state = remindersFor(ctx);
-		const fingerprint: ReminderFingerprint = {
-			windowId: state.windowId,
-			contextWindow: budget.contextWindow,
-			reserveTokens: budget.reserveTokens,
-		};
-		// A reminder a compaction summarized away no longer reaches the model.
-		if (hasReminder(state.reminders, fingerprint)) return;
-		pi.sendMessage(
-			{
-				customType: REMINDER_TYPE,
-				content: `[posthorse] Checkpoint now: ${(budget.rolloverAt - usage.tokens).toLocaleString("en-US")} tokens remain before Pi's automatic rollover line. Stop normal work, ${CHECKPOINT_STEPS}.`,
-				display: true,
-				details: fingerprint,
-			},
-			{ deliverAs: "steer" },
-		);
-	});
-
-	// Filter active input only; raw reminders remain in history for deduplication and recovery.
-	pi.on("context", (event, ctx) => {
-		if (!event.messages.some((message) => message.role === "custom" && isReminderType(message.customType))) return;
-		// The fork's window marker saves a branch walk, but a compaction inside the window drops it.
-		const marker = event.messages.find((message) => message.role === "custom" && message.customType === "context-window");
-		const windowId = marker?.role === "custom"
-			? (marker.details as { windowId?: unknown } | undefined)?.windowId
-			: remindersFor(ctx).windowId;
-		if (typeof windowId !== "string") return;
-		const host = policy(ctx);
-		const budget = budgetFor(host);
-		const fingerprint: ReminderFingerprint = {
-			windowId,
-			contextWindow: budget?.contextWindow,
-			reserveTokens: budget?.reserveTokens,
-		};
-		const enabled = host.getCompactionSettings().enabled;
-		const stale = (message: (typeof event.messages)[number]) =>
-			message.role === "custom" &&
-			isReminderType(message.customType) &&
-			(!enabled || !reminderMatches(message.details, fingerprint));
-		if (event.messages.some(stale)) return { messages: event.messages.filter((message) => !stale(message)) };
-	});
-
-	// Pi owns thresholds, recovery retries, and whether another request follows.
-	pi.on("session_before_compact", (event, ctx) => {
-		if (event.reason === "manual") return;
-		const cancelled = () => event.signal.aborted || ctx.signal?.aborted;
-		if (cancelled()) return { cancel: true };
-		try {
-			// The event carries Pi's live settings; prefer them over the persisted snapshot.
-			const host = policy(ctx, event.preparation.settings);
-			// Small/unknown context windows deliberately keep Pi's own compaction.
-			if (!budgetFor(host)?.supported) return;
-			const limit = freshPayloadChars(host, activeToolTokens());
-			const ownerQuestionRegistered = pi.getAllTools().some((tool) => tool.name === "ask_question" && tool.namespace === undefined);
-			const handoff = buildAutoHandoff(event.branchEntries, ctx.sessionManager.buildSessionProjection().entries, limit, ownerQuestionRegistered);
-			if (limit < MIN_PAGE_CHARS || handoff.length > limit) throw new Error("Too little fresh context capacity for an automatic recovery record.");
-			if (cancelled()) return { cancel: true };
-			// firstKeptEntryId must name an entry; an invisible sentinel retains no prior conversation.
-			pi.appendEntry("posthorse-boundary", {});
-			const firstKeptEntryId = ctx.sessionManager.getLeafId();
-			if (!firstKeptEntryId) throw new Error("Pi did not persist the context boundary.");
-			return { compaction: { summary: handoff, firstKeptEntryId, tokensBefore: event.preparation.tokensBefore, details: { posthorse: 1, reason: event.reason } } };
-		} catch (error) {
-			// Pi swallows handler errors and would then run its summarizer; cancel instead.
-			if (!cancelled()) {
-				const message = `Posthorse automatic rollover cancelled: ${error instanceof Error ? error.message : String(error)}`;
-				if (ctx.hasUI) ctx.ui.notify(message, "error");
-				else console.error(message);
-			}
-			return { cancel: true };
-		}
-	});
-
-	pi.registerTool({
-		name: "new_context",
-		label: "New Context",
-		...toolCards("new_context"),
-		description:
-			"Start a fresh context window once the current foreground tools succeed; background work continues across the reset. Earlier conversation stays recoverable through history. Put continuation state in handoff, or save fuller state in notes first.",
-		promptSnippet: "request a fresh context window with an optional handoff",
-		parameters: Type.Object({
-			handoff: Type.Optional(
-				Type.String({
-					description: "What the fresh window needs to continue, as readable prose",
-					maxLength: MAX_HANDOFF_CHARS,
-				}),
-			),
-		}),
-		async execute(_id, { handoff }, _signal, _onUpdate, ctx) {
-			const trimmed = handoff?.trim() || undefined;
-			const limit = freshPayloadChars(policy(ctx), activeToolTokens());
-			if (trimmed && trimmed.length > limit) {
-				throw new Error(
-					`Handoff is too large for the active model (${trimmed.length.toLocaleString("en-US")} characters; limit ${limit.toLocaleString("en-US")}). Save fuller state in notes, then retry with a shorter handoff or no handoff.`,
-				);
-			}
-			const result = textResult(
-				"Requested a fresh Pi context after the current foreground tools succeed. Background work continues across the reset. Earlier conversation stays in session history.",
-				[],
-				{ kind: "new-context" },
-			);
-			resetRequests.set(_id, trimmed || EMPTY_HANDOFF);
-			return result;
-		},
-	});
-
-	pi.registerTool({
-		name: "get_context_remaining",
-		label: "Context Remaining",
-		...toolCards("get_context_remaining"),
-		description:
-			"Estimate tokens left before Pi's automatic rollover and the configured context limit. Check before reporting remaining space or changing your work plan because of context limits. A checkpoint reminder already arrives before rollover; no routine checks are needed.",
-		promptSnippet: "verify remaining context before reporting a token count or changing plans because of context limits",
-		parameters: Type.Object({}),
-		async execute(_id, _params, _signal, _onUpdate, ctx) {
-			const host = policy(ctx);
-			const usage = host.getContextUsage();
-			if (!usage || usage.tokens == null) return textResult("Context usage is not known until the next model response.", [], { kind: "context" });
-			const n = (value: number) => value.toLocaleString("en-US");
-			const budget = budgetFor(host, usage.contextWindow);
-			const display: PosthorseDisplay = {
-				kind: "context", usage,
-				rollover: !budget?.enabled ? "disabled" : budget.supported ? "enabled" : "unsupported",
-				rolloverAt: budget?.rolloverAt,
-			};
-			const configured = `≈${n(Math.max(0, usage.contextWindow - usage.tokens))} tokens until the configured context limit (${n(usage.tokens)}/${n(usage.contextWindow)} used, ${Math.round(usage.percent ?? 0)}%). Best available native estimate. ${SNAPSHOT_NOTE}`;
-			if (!budget?.enabled) return textResult(`Automatic rollover is disabled in the available settings (Pi compaction.enabled=false). ${configured}`, [], display);
-			if (!budget.supported) return textResult(`${unsupportedMessage(budget)} ${configured}`, [], display);
-			return textResult(
-				`≈${n(Math.max(0, budget.rolloverAt - usage.tokens))} tokens until automatic rollover (line at ${n(budget.rolloverAt)}); ${configured}`,
-				[], display,
-			);
-		},
-	});
-
-	pi.registerTool({
-		name: "notes",
-		label: "Notes",
-		...toolCards("notes"),
-		description:
-			"Durable notes shared across Git worktrees and context resets. Ops: list (newest first, size/date; optional folder), read, search (case-insensitive text), write (replace; empty clears), append (one newline-terminated record). list/read/search are paged; continue with the returned offset. list shows the absolute notes directory; read shows the absolute file path. Prefer available file-editing tools for changed sections of one concise current-state note; write for creation or substantial restructuring. Link fuller evidence instead of copying it.",
-		promptSnippet: "save and recall durable state that survives context resets",
-		parameters: Type.Object({
-			op: Type.Union(
-				[Type.Literal("list"), Type.Literal("read"), Type.Literal("write"), Type.Literal("append"), Type.Literal("search")],
-				{ description: "Operation to perform" },
-			),
-			path: Type.Optional(Type.String({ description: "Note or folder path relative to .pi/notes/" })),
-			content: Type.Optional(Type.String({ description: "Full file content (write) or text to add (append)" })),
-			query: Type.Optional(Type.String({ description: "Substring to find in notes (search)" })),
-			offset: Type.Optional(Type.Integer({ description: "Character offset for list/read/search (default 0)", minimum: 0 })),
-		}),
-		async execute(_id, params, signal, _onUpdate, ctx) {
-			const dir = join(notesRoot(ctx.cwd), ".pi", "notes");
-			const safeJoin = (path: string) => {
-				const relative = normalize(path.replace(/^[/\\]+/, ""));
-				if (relative === ".." || relative.startsWith(`..${sep}`) || isAbsolute(relative)) {
-					throw new Error(`Invalid path "${path}": must stay inside .pi/notes/.`);
-				}
-				return join(dir, relative);
-			};
-			const walk = (directory: string, output: NoteFile[], ancestors = new Set<string>()) => {
-				const root = realpathSync(directory);
-				if (ancestors.has(root)) return;
-				ancestors.add(root);
-				for (const file of readdirSync(directory)) {
-					const path = join(directory, file);
-					const info = statSync(path, { throwIfNoEntry: false });
-					if (!info) continue;
-					if (info.isDirectory()) walk(path, output, ancestors);
-					else output.push({ path, size: info.size, mtimeMs: info.mtimeMs });
-				}
-				ancestors.delete(root);
-			};
-			const notesUnder = (target: string): NoteFile[] => {
-				const info = statSync(target, { throwIfNoEntry: false });
-				if (!info) return [];
-				const files: NoteFile[] = [];
-				if (info.isDirectory()) walk(target, files);
-				else files.push({ path: target, size: info.size, mtimeMs: info.mtimeMs });
-				return files.sort((a, b) => b.mtimeMs - a.mtimeMs);
-			};
-			const list = (folder?: string) => notesPage(
-				policy(ctx),
-				notesUnder(folder ? safeJoin(folder) : dir).map((file) =>
-					`${file.path.slice(dir.length + 1)}  ${formatSize(file.size)}  ${new Date(file.mtimeMs).toISOString().slice(0, 16)}Z`),
-				params.offset ?? 0,
-				"notes-list",
-				folder ? `(no notes in ${folder})` : "(no notes yet)",
-				`Notes directory: ${dir}\n`,
-			);
-
-			switch (params.op) {
-				case "list":
-					return list(params.path);
-				case "read": {
-					const relative = requireValue(params.path, "path", params.op);
-					const path = safeJoin(relative);
-					const info = statSync(path, { throwIfNoEntry: false });
-					if (!info) throw new Error(`No note at ${relative}. Use op "list" to see available notes.`);
-					if (info.isDirectory()) return list(relative);
-					if (await isBinaryFile(path)) throw new Error(`${relative} is a binary file (${formatSize(info.size)}); notes read returns text only.`);
-					const text = readFileSync(path, "utf8");
-					const offset = params.offset ?? 0;
-					if (offset && offset >= text.length) {
-						throw new Error(`Offset ${offset} is past the end of ${relative} (${text.length} chars).`);
-					}
-					const header = `File: ${path}\n`;
-					const host = policy(ctx);
-					const chars = pageSize(host, offset, 0) - header.length;
-					if (chars <= 0) pageError(host, `Too little context remains to include the note path. Call new_context first, then retry with offset ${offset}.`);
-					const end = Math.min(text.length, offset + chars);
-					const more =
-						end < text.length ? `\n[chars ${offset}-${end} of ${text.length}; continue with offset ${end}]` : "";
-					return pageResult(`${header}${text.slice(offset, end)}${more}`, [], { kind: "note-read", headerLength: header.length, offset, end, total: text.length });
-				}
-				case "write": {
-					const relative = requireValue(params.path, "path", params.op);
-					if (params.content === undefined) throw new Error(`"content" is required for op "write" (use "" to clear a note).`);
-					const path = safeJoin(relative);
-					mkdirSync(dirname(path), { recursive: true });
-					await withFileMutationQueue(path, () => publishFile(path, params.content!, signal));
-					return textResult(`Wrote ${path}`, [], { kind: "note-write" });
-				}
-				case "append": {
-					const relative = requireValue(params.path, "path", params.op);
-					const content = requireValue(params.content, "content", params.op);
-					const path = safeJoin(relative);
-					mkdirSync(dirname(path), { recursive: true });
-					// One O_APPEND write per newline-terminated record, so concurrent Pi processes appending to a
-					// shared note never merge records. The separator only matters after a write that left no trailing
-					// newline; a torn read of another process's in-flight append costs at most one blank line.
-					await withFileMutationQueue(path, async () => {
-						signal?.throwIfAborted();
-						const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
-						const separator = existing && !existing.endsWith("\n") ? "\n" : "";
-						appendFileSync(path, `${separator}${content.replace(/\n?$/, "\n")}`);
-					});
-					return textResult(`Appended to ${path}`, [], { kind: "note-append" });
-				}
-				case "search": {
-					const query = requireValue(params.query, "query", params.op).toLowerCase();
-					const hits: string[] = [];
-					for (const { path: file } of notesUnder(dir)) {
-						if (await isBinaryFile(file)) continue;
-						let number = 0;
-						for await (const line of lfLines(file, signal)) {
-							number++;
-							const trimmed = line.trim();
-							const match = trimmed.toLowerCase().indexOf(query);
-							if (match !== -1) {
-								hits.push(`${file.slice(dir.length + 1)}:${number}: ${excerptAround(trimmed, match, 50, 200)}`);
-							}
-						}
-					}
-					return notesPage(policy(ctx), hits, params.offset ?? 0, "notes-search", `No notes match "${excerpt(params.query!, 200)}".`);
-				}
-			}
-		},
-	});
-
-	pi.registerTool({
-		name: "history",
-		label: "History",
-		...toolCards("history"),
-		description:
-			"Search or read earlier session entries, including previous context windows. search skips entries still in your active context and lists original content before recovery echoes, newest first; all=true also searches this project's other sessions and subagent runs. read takes an entry id exactly as search printed it and pages text and images.",
-		promptSnippet: "recover earlier conversation that left the active context window",
-		promptGuidelines: ["Use history search first, then history read with the entry id exactly as printed"],
-		parameters: Type.Object({
-			op: Type.Union([Type.Literal("search"), Type.Literal("read")], { description: "Operation to perform" }),
-			query: Type.Optional(Type.String({ description: "Case-insensitive text to find (search)" })),
-			id: Type.Optional(Type.String({ description: "Entry id exactly as search printed it (read)" })),
-			all: Type.Optional(Type.Boolean({ description: "Also search this project's other sessions and subagent runs" })),
-			limit: Type.Optional(Type.Integer({ description: "Maximum search results per page (default 10, max 50)", minimum: 1, maximum: 50 })),
-			cursor: Type.Optional(Type.String({ description: "Continuation from the previous search page; keep query and all unchanged", maxLength: 512 })),
-			offset: Type.Optional(Type.Integer({ description: "Character offset for read (default 0)", minimum: 0 })),
-			imageOffset: Type.Optional(Type.Integer({ description: "First image to return (read); use the value from the continuation", minimum: 0 })),
-		}),
-		async execute(_id, params, signal, _onUpdate, ctx) {
-			const manager = ctx.sessionManager;
-			const cwd = resolve(ctx.cwd);
-			const currentFile = manager.getSessionFile?.();
-			const dir = manager.getSessionDir();
-
-			if (params.op === "search") {
-				const query = requireValue(params.query, "query", params.op).toLowerCase();
-				const limit = params.limit ?? 10;
-				const searchKey = shortKey(JSON.stringify([query, params.all === true]));
-				// Projections show replacements and stripped async calls under the original id, so an entry is in
-				// context only when all of its own text is visible there. Posthorse strips stale reminders from input.
-				const seen = (message: MessageLike) => [
-					textOf(message), assistantFailure(message), imageSummary(imagesOf(message.content)), message.summary, message.command, message.output,
-				].filter(Boolean).join("\n").toLowerCase();
-				const visible = new Map((manager.buildSessionProjection().entries as readonly ProjectedEntry[]).flatMap(({ sourceEntry, messages }) =>
-					sourceEntry.id && messages.length ? [[sourceEntry.id, messages.map(seen).join("\n")] as const] : []));
-				const inContext = (entry: EntryLike) => {
-					if (entry.type === "custom_message" && isReminderType(entry.customType)) return false;
-					const own = entry.type === "message" ? entry.message ?? {}
-						: entry.type === "context_edit" ? { content: entry.replacement?.content }
-						: entry.type === "context_window" ? { content: entry.handoff }
-						: { content: entry.content, summary: entry.summary };
-					return visible.get((entry.type === "context_edit" ? entry.targetId : entry.id) ?? "")?.includes(seen(own)) === true;
-				};
-				let skipped = 0;
-				let cursor: [string, 0 | 1, number, string] | undefined;
-				if (params.cursor) {
-					try {
-						const value = JSON.parse(Buffer.from(params.cursor, "base64url").toString());
-						if (!Array.isArray(value) || value.length !== 4 || typeof value[0] !== "string" || !value[0] || ![0, 1].includes(value[1]) || !Number.isSafeInteger(value[2]) || value[2] < 0 || value[3] !== searchKey) throw new Error();
-						cursor = value as typeof cursor;
-					} catch { pageError(policy(ctx), "Invalid history cursor or changed query/scope; restart the search without it.", params.cursor); }
-				}
-				const hits: HistoryHit[][] = [[], []];
-				let found = !cursor;
-				const addHit = (hit: HistoryHit | undefined) => {
-					if (!hit) return;
-					if (cursor && hit.priority < cursor[1]) return;
-					if (cursor && hit.priority === cursor[1] && !found) {
-						if (hit.id !== cursor[0]) return;
-						found = true;
-						if (cursor[2] > hit.text.length) pageError(policy(ctx), "History cursor is past the entry; restart the search without it.", params.cursor);
-						if (cursor[2] === hit.text.length) return;
-					}
-					if (hits[hit.priority].length <= limit) hits[hit.priority].push(hit);
-				};
-
-				if (params.all) {
-					const needles = prefilterNeedles(query);
-					const candidates = needles && await filesContaining(dir, needles, signal);
-					const current = currentFile && resolve(currentFile);
-					for await (const file of scopedSessionFiles(dir, cwd, currentFile, signal, { candidates })) {
-						const recent: HistoryHit[][] = [[], []];
-						let anchorHere = false;
-						const source = relative(dir, file);
-						const inCurrent = resolve(file) === current;
-						for await (const item of sessionWindowEntries(file, signal)) {
-							const hit = historyHit(item, query, source);
-							if (!hit) continue;
-							if (inCurrent && inContext(item.entry)) {
-								skipped++;
-								continue;
-							}
-							const seeking = cursor && !found && hit.priority === cursor[1];
-							if (seeking && anchorHere) continue;
-							if (seeking && hit.id === cursor?.[0]) anchorHere = true;
-							const group = recent[hit.priority];
-							group.push(hit);
-							// Keep one page plus its anchor and lookahead, not every matching excerpt.
-							if (group.length > limit + 2) group.shift();
-						}
-						if (cursor && !found && !anchorHere) recent[cursor[1]] = [];
-						for (const group of recent) for (const hit of group.reverse()) addHit(hit);
-						if (hits[0].length > limit) break;
-					}
-				} else {
-					const current = [...windowEntries(manager.getBranch() as EntryLike[])];
-					for (const item of current.reverse()) {
-						const hit = historyHit(item, query);
-						if (!hit) continue;
-						if (inContext(item.entry)) {
-							skipped++;
-							continue;
-						}
-						addHit(hit);
-						if (hits[0].length > limit) break;
-					}
-				}
-				const host = policy(ctx);
-				const chars = pageSize(host, 0, 0, params.cursor);
-				if (!found) pageError(host, "History cursor entry no longer matches; restart the search without it.", params.cursor);
-				const results = hits.flat();
-				const cursorFor = (hit: HistoryHit, offset: number) => Buffer.from(JSON.stringify([hit.id, hit.priority, offset, searchKey])).toString("base64url");
-				const footer = (next: string) => `\n[More results; continue with cursor "${next}" and the same query/scope.]`;
-				const reserve = Math.max(0, ...results.map((hit) => footer(cursorFor(hit, hit.text.length)).length));
-				if (reserve >= chars) pageError(host, "History entry id is too large for pagination.", params.cursor);
-				const skippedNote = skipped && !params.cursor
-					? `\n[Skipped ${skipped} match${skipped === 1 ? "" : "es"} already in your active context.]`
-					: "";
-				const parts: string[] = [];
-				const spans: Array<{ headerLength: number; length: number }> = [];
-				let available = chars - reserve - skippedNote.length;
-				let next: string | undefined;
-				for (const hit of results) {
-					const offset = cursor?.[0] === hit.id ? cursor[2] : 0;
-					if (parts.length && hit.text.length - offset > available) break;
-					// A split header or excerpt must still identify the native entry on every page.
-					const prefix = offset || hit.text.length > available ? `[entry ${hit.id}; from char ${offset}] ` : "";
-					if (prefix.length >= available) break;
-					const end = Math.min(hit.text.length, offset + available - prefix.length);
-					const part = prefix + hit.text.slice(offset, end);
-					parts.push(part);
-					spans.push({ headerLength: prefix.length + Math.max(0, Math.min(hit.headerLength - offset, end - offset)), length: part.length });
-					available -= part.length + 1;
-					next = end < hit.text.length || parts.length < results.length ? cursorFor(hit, end) : undefined;
-					if (available <= 0 || parts.length >= limit) break;
-				}
-				const body = parts.length ? parts.join("\n") : `No history matches "${excerpt(params.query!, 200)}".`;
-				const tail = `${skippedNote}${next ? footer(next) : ""}`;
-				return pageResult(body + tail, [], { kind: "history-search", entries: spans, footerLength: tail.length, more: next !== undefined, skipped });
-			}
-
-			const id = requireValue(params.id, "id", params.op);
-			const separator = id.indexOf("@");
-			const entryId = separator < 0 ? id : id.slice(0, separator);
-			const fileKey = separator < 0 ? undefined : id.slice(separator + 1);
-			const formatEntry = (item: WindowedEntry, source = "") => {
-				// Session-file reads print the qualified id, so continuations reopen the same file.
-				const shownId = source ? `${item.entry.id}@${shortKey(source)}` : id;
-				const offset = params.offset ?? 0;
-				const imageOffset = params.imageOffset ?? (offset === 0 ? 0 : item.images.length);
-				if (imageOffset > item.images.length) {
-					throw new Error(`Image offset ${imageOffset} is past the end of history entry "${id}" (${item.images.length} images).`);
-				}
-				if (offset > item.text.length || (offset === item.text.length && imageOffset === item.images.length)) {
-					throw new Error(`Offset ${offset} is past the end of history entry "${id}" (${item.text.length} chars).`);
-				}
-				// Reserve one image first so an image-only continuation either advances or asks for fresh context.
-				const firstImage = imageOffset < item.images.length ? 1 : 0;
-				const chars = pageSize(policy(ctx), offset, firstImage, undefined, item.images.length ? imageOffset : undefined);
-				const imageEnd = Math.min(item.images.length, imageOffset + firstImage + Math.floor((chars - MIN_PAGE_CHARS) / ESTIMATED_IMAGE_CHARS));
-				const images = item.images.slice(imageOffset, imageEnd);
-				const end = Math.min(
-					item.text.length,
-					offset + chars - (images.length - firstImage) * ESTIMATED_IMAGE_CHARS,
-				);
-				const more = end < item.text.length || imageEnd < item.images.length
-					? `\nMore remains; call history read with id "${shownId}" and offset ${end}${item.images.length ? ` and imageOffset ${imageEnd}` : ""}.` : "";
-				const header = `${item.entry.timestamp ?? ""}${sourceTag(source)} [window ${item.windowId}] [${shownId}] [chars ${offset}-${end} of ${item.text.length}] `;
-				return pageResult(
-					`${header}${item.text.slice(offset, end)}${more}`,
-					images,
-					{ kind: "history-read", headerLength: header.length, offset, end, total: item.text.length, imageOffset, imageEnd, imageTotal: item.images.length },
-				);
-			};
-
-			if (fileKey === undefined) {
-				for (const item of windowEntries(manager.getBranch() as EntryLike[])) {
-					if (item.entry.id === entryId) return formatEntry(item);
-				}
-			}
-			// Bare ids from other sessions reach here through older notes and handoffs.
-			const candidates = fileKey === undefined && /^[\w-]+$/.test(entryId)
-				? await filesContaining(dir, [`"id":"${entryId}"`], signal)
-				: undefined;
-			for await (const file of scopedSessionFiles(dir, cwd, currentFile, signal, { fileKey, candidates })) {
-				const fileSource = relative(dir, file);
-				for await (const item of sessionWindowEntries(file, signal)) {
-					if (item.entry.id === entryId) return formatEntry(item, fileSource);
-				}
-			}
-			throw new Error(`No history entry "${id}" in this session or this project's other sessions. Pass an id exactly as history search prints it, such as 1a2f07de, or 1a2f07de@Ab3dE5fG7h from another session; search first when you only have text or a timestamp.`);
-		},
-	});
-};
-
+}
 export default createPosthorse();