pi-posthorse 0.7.0 → 0.8.1

package/index.ts

@@ -1,1597 +1,52 @@
 /**
  * Posthorse — fresh context, same journey.
  *
- * No-summary context rollover for Pi. On the fitchmultz/pi fork, Pi persists native context
- * windows; on official Pi, rollover is a retain-none compaction whose summary is the handoff.
- * 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 };
-
-/** The fork exposes live settings on the context; official Pi gets them from the injected policy. */
-type PolicyContext = {
-	model?: { contextWindow: number };
-	getCompactionSettings(): CompactionPolicy;
-	getContextUsage(): ContextUsage | undefined;
-	getSystemPrompt(): string;
-};
-
-/** Fork-only extension API; the published Pi types do not declare it. */
-type NativeExtensionAPI = {
-	registerContextWindowHook(
-		handler: (
-			event: { contextEntries: ProjectedEntry[]; pendingMessages: MessageLike[] },
-			ctx: ExtensionContext,
-		) => ReceiptEdit[] | undefined,
-	): void;
-	on(
-		event: "session_before_auto_compact",
-		handler: (
-			event: { reason: "overflow" | "threshold"; branchEntries: EntryLike[]; pendingMessages?: MessageLike[]; retainedToolResultIds: string[] },
-			ctx: unknown,
-		) => { newContext: { handoff?: string } } | undefined,
-	): void;
-};
-
-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 ReceiptEdit = { type: "context_edit"; targetId: string; replacement: { content: string } };
-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 fork context window, or the retain-none compaction Posthorse commits on official Pi. */
-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 currentWindowId(entries: readonly EntryLike[]): string {
-	for (let i = entries.length - 1; i >= 0; i--) {
-		const entry = entries[i];
-		if (isWindow(entry) && entry.id) return entry.id;
-	}
-	return "initial";
-}
-
-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): 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 &&
-		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): 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 records = edited
-		.map((entry) => recoveryRecord(entry))
-		.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.model?.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 contextWindow = ctx.model?.contextWindow;
-	if (!contextWindow || contextWindow <= 0) return cap;
-	const budget = budgetFor(ctx, contextWindow);
-	const line = budget?.enabled && budget.supported ? budget.rolloverAt : contextWindow;
-	const promptTokens = Math.ceil(ctx.getSystemPrompt().length / 4);
-	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,
-	);
-}
-
-/** Bound only the carried receipts; edits preserve the journal and native call/result identity. */
-function boundWindowReceipts(
-	ctx: ExtensionContext & PolicyContext,
-	projected: readonly ProjectedEntry[],
-	pending: readonly MessageLike[],
-	toolTokens: number,
-): ReceiptEdit[] | undefined {
-	if (!ctx.model) return undefined;
-	const estimate = estimateTokens as unknown as (message: MessageLike) => number;
-	const messages = projected.flatMap((entry) => entry.messages);
-	const budget = budgetFor(ctx);
-	const reserve = budget?.enabled && budget.supported ? budget.reserveTokens : 0;
-	const overhead =
-		reserve +
-		PAGE_MARGIN_TOKENS +
-		Math.max(
-			Math.ceil(ctx.getSystemPrompt().length / 4) + toolTokens,
-			messages.filter((message) => message.role === "system").reduce((sum, message) => sum + estimate(message), 0),
-		) +
-		pending.reduce((sum, message) => sum + estimate(message), 0);
-	const fixed = messages.filter((message) => message.role !== "system" && message.role !== "toolResult");
-	const available = ctx.model.contextWindow - overhead - fixed.reduce((sum, message) => sum + estimate(message), 0);
-	const edits = contextEdits(ctx.sessionManager.getBranch() as EntryLike[]);
-	const receipts = projected.flatMap(({ sourceEntry, messages }) =>
-		messages.filter((message) => message.role === "toolResult").map((message) => {
-			if (!sourceEntry.id) throw new Error("Posthorse: retained receipt has no history entry");
-			const recoveryId = edits.get(sourceEntry.id)?.id ?? sourceEntry.id;
-			const images = imageSummary(imagesOf(message.content));
-			const header = `Retained ${message.isError ? "error" : "result"} excerpt. Full content: history read id ${recoveryId}.${images ? `\n${images}` : ""}\n`;
-			const cost = estimate(message);
-			const minimum = Math.min(cost, Math.ceil(header.length / 4));
-			return { id: sourceEntry.id, message, header, cost, minimum };
-		}),
-	);
-	if (receipts.reduce((sum, receipt) => sum + receipt.cost, 0) <= available) return undefined;
-	let extra = available - receipts.reduce((sum, receipt) => sum + receipt.minimum, 0);
-	if (extra < 0) throw new Error("Posthorse: fresh context cannot fit fixed input and receipt recovery references");
-	// Like handoffs, oversized receipt excerpts leave half the remaining capacity for continued work.
-	extra = Math.floor(extra / 2);
-	const drafts: ReceiptEdit[] = [];
-	receipts.sort((a, b) => a.cost - a.minimum - (b.cost - b.minimum));
-	for (const [index, receipt] of receipts.entries()) {
-		const allowance = receipt.minimum + Math.min(receipt.cost - receipt.minimum, Math.floor(extra / (receipts.length - index)));
-		extra -= allowance - receipt.minimum;
-		if (receipt.cost <= allowance) continue;
-		const content = receipt.header + excerpt(textOf(receipt.message), allowance * 4 - receipt.header.length);
-		drafts.push({ type: "context_edit", targetId: receipt.id, replacement: { content } });
-	}
-	const replacements = new Map(drafts.map((draft) => [draft.targetId, draft.replacement.content]));
-	const total = projected.reduce(
-		(sum, entry) =>
-			sum + entry.messages.reduce(
-				(tokens, message) => tokens + (message.role === "system" ? 0 : estimate(
-					replacements.has(entry.sourceEntry.id ?? "")
-						? { ...message, content: replacements.get(entry.sourceEntry.id!) }
-						: message,
-				)),
-				0,
-			),
-		overhead,
-	);
-	if (total > ctx.model.contextWindow) throw new Error("Posthorse: retained receipts exceed fresh context capacity");
-	return drafts;
-}
-
-/** 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 = "rewrite the task's current-state note in place with notes write (goal, progress, decisions, next steps), 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;
-}
-
-function buildGuidance(ctx: PolicyContext, official: boolean): string {
-	const budget = budgetFor(ctx);
-	const enabled = budget?.enabled ?? ctx.getCompactionSettings().enabled;
-	let automatic: string;
-	if (!enabled) {
-		automatic = official
-			? "Pi compaction is disabled in the available settings, so Posthorse sends no checkpoint reminder. new_context remains available."
-			: "Pi compaction is disabled, so Posthorse sends no checkpoint reminder and performs no automatic rollover. 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";
-		automatic = `Automatic rollover follows Pi's compaction setting. 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)
-${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.
-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);
-}
-
-/** SDK hosts on official Pi can inject their live settings instead of the persisted snapshot; the fork always uses its own. */
-export const createPosthorse = (getPolicy: (ctx: ExtensionContext) => CompactionPolicy = persistedPolicy) => (pi: ExtensionAPI) => {
-	const nativePi = pi as unknown as NativeExtensionAPI;
-	const native = typeof nativePi.registerContextWindowHook === "function";
-	const policy = (ctx: ExtensionContext): PolicyContext =>
-		native ? (ctx as ExtensionContext & PolicyContext) : {
-			model: ctx.model,
-			getCompactionSettings: () => getPolicy(ctx),
-			getContextUsage: () => ctx.getContextUsage(),
-			getSystemPrompt: () => ctx.getSystemPrompt(),
-		};
-	registerPosthorseMessages(pi);
-	const activeToolTokens = () => {
-		const active = new Set(pi.getActiveTools());
-		return pi
-			.getAllTools()
-			// The fork identifies namespaced tools by id; official Pi only has names.
-			.filter((tool) => active.has((tool as typeof tool & { id?: string }).id ?? tool.name))
-			.reduce(
-				(total, tool) =>
-					total +
-					Math.ceil(
-						safeJsonStringify({ name: tool.name, description: tool.description ?? "", parameters: tool.parameters })
-							.length / 4,
-					),
-				0,
-			);
-	};
-
-	if (native) {
-		nativePi.registerContextWindowHook((event, ctx) =>
-			boundWindowReceipts(ctx as ExtensionContext & PolicyContext, event.contextEntries, event.pendingMessages, activeToolTokens()),
-		);
-	}
-
-	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) => {
-		const text = rows.length ? rows.join("\n") : empty;
-		const chars = pageSize(ctx, offset, 0);
-		if (offset && offset >= text.length) pageError(ctx, "Offset is past the end; restart with offset 0.");
-		// 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}]`;
-		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(text.slice(offset, end) + (end < text.length ? footer(end) : ""), [], { kind, count: starts.filter((start) => start < end).length, page: { offset, end, total: text.length } });
-	};
-	pi.on("turn_start", () => {
-		pendingPageTokens = 0;
-		previousPageUsage = undefined;
-	});
-
-	pi.on("session_start", () => {
-		pendingPageTokens = 0;
-		previousPageUsage = undefined;
-	});
-
-	pi.on("before_agent_start", (event, ctx) => {
-		const guidance = buildGuidance(policy(ctx), !native);
-		// An earlier full-prompt override makes section edits invisible to Pi.
-		if (event.systemPromptOptions.forceSystemPrompt !== undefined) {
-			return { systemPrompt: `${event.systemPrompt}\n\n${guidance}` };
-		}
-		event.systemPromptOptions.sections.posthorse = guidance;
-	});
-
-	pi.on("turn_end", (event, ctx) => {
-		const host = policy(ctx);
-		if (
-			event.message.role === "assistant" &&
-			(event.message.stopReason === "error" || event.message.stopReason === "aborted")
-		)
-			return;
-		const requested = event.toolResults.find((result) => result.toolName === "new_context");
-		// Suppress clear successes; turn_end can also include unrelated background errors.
-		// If Pi still rolls over, context filtering below removes any stale reminder.
-		if (requested && !event.toolResults.some((result) => result.isError)) {
-			// The fork commits new_context from the tool result; official Pi needs a retain-none compaction draft.
-			if (native || event.outcome === "aborted" || ctx.signal?.aborted) return;
-			const content = (event.message as MessageLike).content;
-			const call = (Array.isArray(content) ? content as ToolCallLike[] : []).find((block) => block?.type === "toolCall" && block.id === requested.toolCallId);
-			const handoff = (call?.arguments as { handoff?: unknown } | undefined)?.handoff;
-			const summary = (typeof handoff === "string" && handoff.trim()) || EMPTY_HANDOFF;
-			// 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 branch = ctx.sessionManager.getBranch() as EntryLike[];
-		const fingerprint: ReminderFingerprint = {
-			windowId: currentWindowId(branch),
-			contextWindow: budget.contextWindow,
-			reserveTokens: budget.reserveTokens,
-		};
-		// A reminder a compaction summarized away no longer reaches the model.
-		if (hasReminder(branch.slice(contextStart(branch).start), 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
-			: currentWindowId(ctx.sessionManager.getBranch() as EntryLike[]);
-		if (typeof windowId !== "string") return;
-		const host = policy(ctx);
-		const budget = budgetFor(host);
-		const fingerprint: ReminderFingerprint = {
-			windowId,
-			contextWindow: budget?.contextWindow,
-			reserveTokens: budget?.reserveTokens,
-		};
-		const stale = (message: (typeof event.messages)[number]) =>
-			message.role === "custom" &&
-			isReminderType(message.customType) &&
-			(!host.getCompactionSettings().enabled || !reminderMatches(message.details, fingerprint));
-		if (event.messages.some(stale)) return { messages: event.messages.filter((message) => !stale(message)) };
-	});
-
-	if (native) {
-		// Claim Pi's automatic threshold/overflow trigger with a fresh window: no summary, no summarization auth.
-		nativePi.on("session_before_auto_compact", (event, ctx) => {
-			const host = policy(ctx as ExtensionContext);
-			const budget = budgetFor(host);
-			// An unsupported budget would roll over every turn; leave Pi's own behavior in place instead.
-			if (budget && !budget.supported) return undefined;
-			const limit = freshPayloadChars(host, activeToolTokens(), event.pendingMessages);
-			const projected = (ctx as ExtensionContext).sessionManager.buildSessionProjection().entries;
-			const handoff = limit >= MIN_PAGE_CHARS ? buildAutoHandoff(event.branchEntries, projected, limit) : "";
-			if (!handoff || handoff.length > limit) {
-				// Only receipts Pi will retain require shaping; consumed results must not force an empty cut.
-				return event.retainedToolResultIds.length ? { newContext: {} } : undefined;
-			}
-			return { newContext: { handoff } };
+/** 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();
 		});
-	} else {
-		// Official 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: PolicyContext = { ...policy(ctx), getCompactionSettings: () => event.preparation.settings };
-				// Small/unknown context windows deliberately keep Pi's own compaction.
-				if (!budgetFor(host)?.supported) return;
-				const limit = freshPayloadChars(host, activeToolTokens());
-				const handoff = buildAutoHandoff(ctx.sessionManager.getBranch() as EntryLike[], ctx.sessionManager.buildSessionProjection().entries, limit);
-				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" },
-			);
-			// Official Pi ignores this field; its reset is committed at turn_end from the call arguments.
-			return native ? { ...result, newContext: { handoff: trimmed } } : 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. A checkpoint reminder already arrives before rollover; use this only before a large step late in a window.",
-		promptSnippet: "check the context budget before a large step late in a window",
-		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.${native ? "" : ` ${SNAPSHOT_NOTE}`}`;
-			if (!budget?.enabled) return textResult(`Automatic rollover is disabled${native ? "" : " 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 in .pi/notes/, shared across Git worktrees and kept across context resets. Ops: list (newest first, with size and date; optional folder path), read, search (case-insensitive substring over text notes), write (replace; empty content clears), append (adds one line-terminated record). list/read/search are paged; continue with the returned offset. Keep one current-state note per task and rewrite it in place.",
-		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)",
-			);
-
-			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 end = Math.min(text.length, offset + pageSize(policy(ctx), offset, 0));
-					const more =
-						end < text.length ? `\n[chars ${offset}-${end} of ${text.length}; continue with offset ${end}]` : "";
-					return pageResult(`${text.slice(offset, end)}${more}`, [], { kind: "note-read", 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 chars = pageSize(policy(ctx), 0, 0, params.cursor);
-				if (!found) pageError(policy(ctx), "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(policy(ctx), "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.`);
-		},
-	});
-};
-
+		registerNotes(pi, policy, pages);
+		registerHistory(pi, policy, pages);
+	};
+}
 export default createPosthorse();