pi-posthorse 0.10.9 → 0.10.11

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-posthorse",
-	"version": "0.10.9",
+	"version": "0.10.11",
 	"type": "module",
 	"description": "Posthorse: fresh context, same journey. No-summary context rollover for Pi, with sparse budget reminders, handoffs, notes, and history.",
 	"keywords": [
@@ -71,9 +71,9 @@
 		"@earendil-works/pi-coding-agent": "1.5.0",
 		"@earendil-works/pi-tui": "1.5.0",
 		"@types/node": "24.19.1",
-		"oxc-parser": "0.156.0",
-		"oxfmt": "0.75.0",
-		"oxlint": "1.90.0",
+		"oxc-parser": "0.157.0",
+		"oxfmt": "0.76.0",
+		"oxlint": "1.91.0",
 		"oxlint-tsgolint": "7.0.2005",
 		"typebox": "1.3.27",
 		"typescript": "7.0.2",

package/src/context-tools.ts

@@ -70,9 +70,7 @@ export function registerContextTools(
 				}),
 			),
 		}),
-		// Pi's fixed tool contract supplies id, params, signal, updates, and context.
-		// oxlint-disable-next-line max-params -- QX-002: Pi supplies five fixed positional tool arguments.
-		async execute(id, { handoff }, _signal, _onUpdate, ctx) {
+		async execute(...[id, { handoff }, , , ctx]) {
 			const trimmed = handoff?.trim();
 			const limit = freshPayloadChars(policy(ctx), activeToolTokens());
 			if (trimmed !== undefined && trimmed !== "" && trimmed.length > limit) {
@@ -98,9 +96,7 @@ export function registerContextTools(
 		promptSnippet:
 			"verify remaining context before reporting a token count or changing plans because of context limits",
 		parameters: Type.Object({}),
-		// Pi's fixed tool contract supplies id, params, signal, updates, and context.
-		// oxlint-disable-next-line max-params -- QX-002: Pi supplies five fixed positional tool arguments.
-		async execute(_id, _params, _signal, _onUpdate, ctx) {
+		async execute(...[, , , , ctx]) {
 			return contextReport(policy(ctx));
 		},
 	});

package/src/contracts.ts

@@ -1,6 +1,8 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { PosthorseDisplay } from "../ui.ts";
 
+export { isRecord } from "./records.ts";
+
 export type CompactionPolicy = {
 	readonly enabled: boolean;
 	readonly reserveTokens: number;
@@ -108,9 +110,6 @@ export const REMINDER_TYPE = "posthorse-reminder";
 export const AUTO_HANDOFF_PREFIX = "Automatic context rollover recovery record.";
 export const EMPTY_HANDOFF = "Fresh context. Restore relevant notes and history before continuing.";
 
-export function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 export function unknownArray(value: unknown): readonly unknown[] | undefined {
 	return Array.isArray(value) ? value : undefined;
 }

package/src/files.ts

@@ -286,13 +286,20 @@ export function notesDir(cwd: string): string {
 		const target = migrationTarget(moved);
 		try {
 			renameSync(local, target);
+		} catch (error) {
+			if (lstatSync(local, { throwIfNoEntry: false })?.isDirectory() === true) {
+				throw error;
+			}
+			return moved;
+		}
+		try {
 			// Sessions still running an older Posthorse keep reaching the notes until they reload.
 			symlinkSync(moved, local, "junction");
 		} catch (error) {
 			if (lstatSync(local, { throwIfNoEntry: false })?.isDirectory() === true) {
 				throw error;
 			}
-			// Another session moved them first, or only the compatibility link failed.
+			// Notes are already outside the checkout; the compatibility link is optional.
 		}
 	}
 	return moved;

package/src/history-pages.ts

@@ -10,10 +10,13 @@ import { excerpt, shortKey, sourceTag } from "./message-text.ts";
 import type { HistoryMatches, HistoryParams } from "./history-search.ts";
 import type { PageAccess } from "./paging.ts";
 
+type Continuation<Position> =
+	| { readonly kind: "complete" }
+	| { readonly kind: "more"; readonly next: Position };
 type SearchPage = {
 	readonly parts: readonly string[];
 	readonly spans: readonly { readonly headerLength: number; readonly length: number }[];
-	readonly next?: string | undefined;
+	readonly continuation: Continuation<string>;
 };
 function cursorFor(matches: HistoryMatches, hit: HistoryHit, offset: number): string {
 	return Buffer.from(JSON.stringify([hit.id, hit.priority, offset, matches.key])).toString(
@@ -56,7 +59,7 @@ function searchParts(matches: HistoryMatches, chars: number): SearchPage {
 	const parts: string[] = [];
 	const spans: Array<{ headerLength: number; length: number }> = [];
 	let available = chars;
-	let next: string | undefined;
+	let continuation: Continuation<string> = { kind: "complete" };
 	for (const hit of matches.hits) {
 		const fragment = hitFragment(hit, matches.cursor, available, parts.length === 0);
 		if (fragment === undefined) {
@@ -65,15 +68,15 @@ function searchParts(matches: HistoryMatches, chars: number): SearchPage {
 		parts.push(fragment.part);
 		spans.push({ headerLength: fragment.headerLength, length: fragment.part.length });
 		available -= fragment.part.length + 1;
-		next =
+		continuation =
 			fragment.end < hit.text.length || parts.length < matches.hits.length
-				? cursorFor(matches, hit, fragment.end)
-				: undefined;
+				? { kind: "more", next: cursorFor(matches, hit, fragment.end) }
+				: { kind: "complete" };
 		if (available <= 0 || parts.length >= matches.limit) {
 			break;
 		}
 	}
-	return { parts, spans, next };
+	return { parts, spans, continuation };
 }
 export function searchPage(
 	matches: HistoryMatches,
@@ -98,12 +101,14 @@ export function searchPage(
 		page.parts.length > 0
 			? page.parts.join("\n")
 			: `No history matches "${excerpt(params.query ?? "", 200)}".`;
-	const tail = skippedNote + (page.next === undefined ? "" : searchFooter(page.next));
+	const tail =
+		skippedNote +
+		(page.continuation.kind === "more" ? searchFooter(page.continuation.next) : "");
 	return pages.result(body + tail, [], {
 		kind: "history-search",
 		entries: [...page.spans],
 		footerLength: tail.length,
-		more: page.next !== undefined,
+		more: page.continuation.kind === "more",
 		skipped: matches.skipped,
 	});
 }
@@ -155,9 +160,13 @@ export function historyReadPage(
 		item.text.length,
 		offset + chars - (images.length - firstImage) * ESTIMATED_IMAGE_CHARS,
 	);
-	const more =
+	const continuation: Continuation<{ readonly offset: number; readonly imageOffset: number }> =
 		end < item.text.length || imageEnd < item.images.length
-			? `\nMore remains; call history read with id "${shownId}" and offset ${end}${item.images.length > 0 ? ` and imageOffset ${imageEnd}` : ""}.`
+			? { kind: "more", next: { offset: end, imageOffset: imageEnd } }
+			: { kind: "complete" };
+	const more =
+		continuation.kind === "more"
+			? `\nMore remains; call history read with id "${shownId}" and offset ${continuation.next.offset}${item.images.length > 0 ? ` and imageOffset ${continuation.next.imageOffset}` : ""}.`
 			: "";
 	const header = `${item.entry.timestamp ?? ""}${sourceTag(source)} [window ${item.windowId}] [${shownId}] [chars ${offset}-${end} of ${item.text.length}] `;
 	return access.pages.result(`${header}${item.text.slice(offset, end)}${more}`, images, {

package/src/history-search.ts

@@ -115,12 +115,14 @@ type SearchProgress = {
 	readonly seeking: (priority: 0 | 1) => boolean;
 	readonly enough: () => boolean;
 };
+type CursorProgress =
+	| { readonly kind: "seeking"; readonly cursor: HistoryCursor }
+	| { readonly kind: "collecting"; readonly cursor?: HistoryCursor };
 /** Owns ranking, lookahead and one cursor's progress; never holds the whole archive. */
 class SearchAccumulator {
 	readonly groups: [HistoryHit[], HistoryHit[]] = [[], []];
-	readonly cursor: HistoryCursor | undefined;
 	readonly limit: number;
-	private found: boolean;
+	private progress: CursorProgress;
 	private readonly fail: (message: string) => never;
 	constructor(
 		limit: number,
@@ -128,24 +130,27 @@ class SearchAccumulator {
 		fail: (message: string) => never,
 	) {
 		this.limit = limit;
-		this.cursor = cursor;
-		this.found = cursor === undefined;
+		this.progress = cursor === undefined ? { kind: "collecting" } : { kind: "seeking", cursor };
 		this.fail = fail;
 	}
+	get cursor(): HistoryCursor | undefined {
+		return this.progress.cursor;
+	}
 	add(hit: HistoryHit): void {
-		const cursor = this.cursor;
+		const progress = this.progress;
+		const cursor = progress.cursor;
 		if (cursor !== undefined && hit.priority < cursor[1]) {
 			return;
 		}
-		if (cursor !== undefined && hit.priority === cursor[1] && !this.found) {
-			if (hit.id !== cursor[0]) {
+		if (progress.kind === "seeking" && hit.priority === progress.cursor[1]) {
+			if (hit.id !== progress.cursor[0]) {
 				return;
 			}
-			this.found = true;
-			if (cursor[2] > hit.text.length) {
+			if (progress.cursor[2] > hit.text.length) {
 				this.fail("History cursor is past the entry; restart the search without it.");
 			}
-			if (cursor[2] === hit.text.length) {
+			this.progress = { kind: "collecting", cursor: progress.cursor };
+			if (progress.cursor[2] === hit.text.length) {
 				return;
 			}
 		}
@@ -154,13 +159,13 @@ class SearchAccumulator {
 		}
 	}
 	seeking(priority: 0 | 1): boolean {
-		return this.cursor !== undefined && !this.found && priority === this.cursor[1];
+		return this.progress.kind === "seeking" && priority === this.progress.cursor[1];
 	}
 	enough(): boolean {
 		return this.groups[0].length > this.limit;
 	}
 	results(): HistoryHit[] {
-		if (!this.found) {
+		if (this.progress.kind === "seeking") {
 			this.fail("History cursor entry no longer matches; restart the search without it.");
 		}
 		return this.groups.flat();

package/src/history.ts

@@ -127,9 +127,7 @@ export function registerHistory(
 				}),
 			),
 		}),
-		// Pi's fixed tool contract supplies id, params, signal, updates, and context.
-		// oxlint-disable-next-line max-params -- QX-002: Pi supplies five fixed positional tool arguments.
-		async execute(_id, params, signal, _onUpdate, ctx) {
+		async execute(...[, params, signal, , ctx]) {
 			const source = historySource(ctx);
 			if (params.op === "search") {
 				const fail = (message: string): never =>

package/src/note-guards.ts

@@ -102,7 +102,7 @@ async function guardOperation(
 	}
 	if (existingEdit(tool, operation) && !session.owns(address.path)) {
 		const copied = await withFileMutationQueue(path, () => session.adopt(address.path, call));
-		if (copied) {
+		if (copied === "adopted") {
 			return `Private copy created at ${path}; no requested edit ran. Read this copy, then retry the edit.`;
 		}
 	}

package/src/note-snapshots.ts

@@ -108,30 +108,45 @@ export async function mapBatch<Input, Output>(
 	}
 	return results;
 }
-async function copyNote(note: SnapshotNote, destination: string): Promise<NoteSeed> {
+type CopyResult =
+	| { readonly kind: "verified"; readonly seed: NoteSeed }
+	| { readonly kind: "unverified"; readonly error: Error };
+async function copyNote(note: SnapshotNote, destination: string): Promise<CopyResult> {
 	const source = notePath(note.source, note.source.path);
 	const [before] = await Promise.all([
 		stat(source),
 		mkdir(dirname(destination), { recursive: true }),
 	]);
 	await copyFile(source, destination, constants.COPYFILE_EXCL);
-	const after = await stat(source);
-	if (!sameIdentity(before, after)) {
-		throw new Error(`Source note changed during snapshot: ${source}. Retry initialization.`);
+	try {
+		const after = await stat(source);
+		if (!sameIdentity(before, after)) {
+			throw new Error(
+				`Source note changed during snapshot: ${source}. Retry initialization.`,
+			);
+		}
+		await utimes(destination, before.atimeMs / 1000, before.mtimeMs / 1000);
+		const [digest, destInfo] = await Promise.all([fileDigest(destination), stat(destination)]);
+		return { kind: "verified", seed: { ...note, digest, identity: fileIdentity(destInfo) } };
+	} catch (error) {
+		return {
+			kind: "unverified",
+			error: error instanceof Error ? error : new Error(String(error)),
+		};
 	}
-	await utimes(destination, before.atimeMs / 1000, before.mtimeMs / 1000);
-	const [digest, destInfo] = await Promise.all([fileDigest(destination), stat(destination)]);
-	return { ...note, digest, identity: fileIdentity(destInfo) };
 }
-/** Publication is the ownership boundary. An existing unrelated directory is never overwritten. */
-export async function snapshot(
+type SnapshotPreparation =
+	| { readonly kind: "existing"; readonly binding: ForkBinding }
+	| { readonly kind: "empty" }
+	| { readonly kind: "staging"; readonly stage: string; readonly container: string };
+async function prepareSnapshot(
 	binding: ForkBinding,
 	notes: readonly SnapshotNote[],
-): Promise<ForkBinding> {
+): Promise<SnapshotPreparation> {
 	const directory = scopeDirectory(binding);
 	const existing = await readManifest(directory);
 	if (existing !== undefined && sameOwner(existing.owner, binding.owner)) {
-		return existing;
+		return { kind: "existing", binding: existing };
 	}
 	const container = dirname(directory);
 	if (
@@ -145,22 +160,41 @@ export async function snapshot(
 		throw new Error(`Incomplete notes snapshot: preserving unexpected data at ${container}.`);
 	}
 	if (notes.length === 0) {
-		return binding;
+		return { kind: "empty" };
 	}
 	await mkdir(dirname(container), { recursive: true });
 	const stage = await mkdtemp(join(dirname(container), ".staging-"));
+	return { kind: "staging", stage, container };
+}
+/** Publication is the ownership boundary. An existing unrelated directory is never overwritten. */
+export async function snapshot(
+	binding: ForkBinding,
+	notes: readonly SnapshotNote[],
+): Promise<ForkBinding> {
+	const preparation = await prepareSnapshot(binding, notes);
+	if (preparation.kind !== "staging") {
+		return preparation.kind === "existing" ? preparation.binding : binding;
+	}
+	const { stage, container } = preparation;
 	try {
 		// Keep each file's identity and digest paired with the bytes actually copied.
-		const seeds = await mapBatch(notes, (note) =>
-			copyNote(note, notePath({ root: stage, scope: "notes" }, note.path)),
-		);
+		const seeds = await mapBatch(notes, async (note) => {
+			const result = await copyNote(
+				note,
+				notePath({ root: stage, scope: "notes" }, note.path),
+			);
+			if (result.kind === "unverified") {
+				throw result.error;
+			}
+			return result.seed;
+		});
 		const complete: ForkBinding = { ...binding, seeds };
 		await writeFile(join(stage, "manifest.json"), JSON.stringify(complete), { flag: "wx" });
 		await rename(stage, container);
 		return complete;
 	} catch (error) {
 		throw new Error(
-			`Incomplete notes snapshot for ${directory}: ${error instanceof Error ? error.message : String(error)}`,
+			`Incomplete notes snapshot for ${scopeDirectory(binding)}: ${error instanceof Error ? error.message : String(error)}`,
 			{ cause: error },
 		);
 	} finally {
@@ -168,7 +202,7 @@ export async function snapshot(
 	}
 }
 /** Called inside the destination's native mutation queue, never queues that path recursively. */
-export async function adoptNote(binding: NoteBinding, note: SnapshotNote): Promise<NoteSeed> {
+export async function adoptNote(binding: NoteBinding, note: SnapshotNote): Promise<CopyResult> {
 	return copyNote(note, notePath(binding, note.path));
 }
 /** Empty initialized scopes publish their manifest when the first note is created. */

package/src/note-store.ts

@@ -35,6 +35,7 @@ import type { NotesRecovery } from "./note-evidence.ts";
 
 type NotesManager = ExtensionContext["sessionManager"];
 export type NoteCall = { readonly id: string; readonly rootId: string };
+type Adoption = "owned" | "unavailable" | "adopted";
 export type NoteRead = {
 	readonly address: NoteAddress;
 	readonly path: string;
@@ -172,16 +173,16 @@ export class SessionNotes {
 		};
 		return { address, path: notePath(address, relative), writable: reference === undefined };
 	}
-	async adopt(path: string, call: NoteCall): Promise<boolean> {
+	async adopt(path: string, call: NoteCall): Promise<Adoption> {
 		const relative = noteRelative(path);
 		if (this.owns(relative)) {
-			return false;
+			return "owned";
 		}
 		const source = await this.#reference(relative);
 		if (source === undefined) {
-			return false;
+			return "unavailable";
 		}
-		const seed = await adoptNote(this.binding, {
+		const result = await adoptNote(this.binding, {
 			path: relative,
 			source,
 			lineage: source,
@@ -194,20 +195,26 @@ export class SessionNotes {
 					scope: this.binding.scope,
 					path: relative,
 					kind: "adopt",
-					seed,
+					...(result.kind === "verified" ? { seed: result.seed } : {}),
 				},
 			],
 			call,
 		);
+		if (result.kind === "unverified") {
+			throw new Error(
+				`Private copy created at ${notePath(this.binding, relative)}; source not edited, but copy verification failed. Read the private copy before retrying.`,
+				{ cause: result.error },
+			);
+		}
 		try {
-			await saveAdoption(this.binding, seed);
+			await saveAdoption(this.binding, result.seed);
 		} catch (error) {
 			throw new Error(
 				`Private copy created at ${notePath(this.binding, relative)}; source not edited, but its adoption manifest could not be saved. Read the private copy before retrying.`,
 				{ cause: error },
 			);
 		}
-		return true;
+		return "adopted";
 	}
 	async prepareWrite(): Promise<void> {
 		await ensureManifest(this.binding);
@@ -215,7 +222,7 @@ export class SessionNotes {
 	async guardReference(path: string, call: NoteCall): Promise<string> {
 		const destination = notePath(this.binding, path);
 		const copied = await withFileMutationQueue(destination, () => this.adopt(path, call));
-		return copied
+		return copied === "adopted"
 			? `Private copy created at ${destination}; the source was not edited. Read the private copy, then retry the edit on that path.`
 			: `This session writes only ${this.directory}. Read ${destination}, then retry there; the foreign path was not edited.`;
 	}
@@ -232,15 +239,19 @@ export type NotesStore = {
 	readonly roots: () => readonly string[];
 	readonly recovery: (ctx: ExtensionContext) => NotesRecovery | undefined;
 };
+type SessionState =
+	| { readonly kind: "initializing"; readonly value: Promise<SessionNotes> }
+	| { readonly kind: "ready"; readonly value: SessionNotes };
 export function createNotesStore(pi: ExtensionAPI): NotesStore {
-	const sessions = new Map<string, Promise<SessionNotes>>();
-	const ready = new Map<string, SessionNotes>();
+	const sessions = new Map<string, SessionState>();
 	const roots = new Set<string>();
 	const get = (ctx: ExtensionContext): Promise<SessionNotes> => {
 		const key = sessionKey(ctx);
 		const existing = sessions.get(key);
 		if (existing !== undefined) {
-			return existing;
+			return existing.kind === "initializing"
+				? existing.value
+				: Promise.resolve(existing.value);
 		}
 		const bindings = bindingsOf(ctx.sessionManager.getEntries());
 		const header = ctx.sessionManager.getHeader();
@@ -260,19 +271,22 @@ export function createNotesStore(pi: ExtensionAPI): NotesStore {
 				for (const scope of session.scopes) {
 					roots.add(scope.root);
 				}
-				ready.set(key, session);
+				sessions.set(key, { kind: "ready", value: session });
 				return session;
 			})
 			.catch((error: unknown) => {
 				sessions.delete(key);
 				throw error;
 			});
-		sessions.set(key, initialized);
+		sessions.set(key, { kind: "initializing", value: initialized });
 		return initialized;
 	};
 	return {
 		get,
 		roots: () => [...roots],
-		recovery: (ctx: ExtensionContext) => ready.get(sessionKey(ctx))?.recovery,
+		recovery: (ctx: ExtensionContext) => {
+			const state = sessions.get(sessionKey(ctx));
+			return state?.kind === "ready" ? state.value.recovery : undefined;
+		},
 	};
 }

package/src/note-tool-effects.ts

@@ -23,6 +23,7 @@ function patchOperations(input: unknown): NoteOperation[] {
 		return [];
 	}
 	const operations: NoteOperation[] = [];
+	let update: { readonly path: string; readonly end: number } | undefined;
 	for (const match of input.matchAll(
 		/^\*\*\* (Update File|Add File|Delete File|Move to): ([^\r\n]+)$/gmu,
 	)) {
@@ -31,10 +32,15 @@ function patchOperations(input: unknown): NoteOperation[] {
 			continue;
 		}
 		if (match[1] === "Move to") {
-			const previous = operations.pop();
-			if (previous !== undefined) {
-				operations.push({ ...previous, action: "delete" });
+			if (
+				update !== undefined &&
+				/^(?:\r\n|\r|\n)$/u.test(input.slice(update.end, match.index))
+			) {
+				operations[operations.length - 1] = { path: update.path, action: "delete" };
+				operations.push({ path, action: "create" });
 			}
+			update = undefined;
+			continue;
 		}
 		let action: NoteAction = "create";
 		if (match[1] === "Update File") {
@@ -43,6 +49,7 @@ function patchOperations(input: unknown): NoteOperation[] {
 			action = "delete";
 		}
 		operations.push({ path, action });
+		update = action === "edit" ? { path, end: match.index + match[0].length } : undefined;
 	}
 	return operations;
 }

package/src/notes.ts

@@ -330,9 +330,7 @@ export function registerNotes(
 				}),
 			),
 		}),
-		// Pi's fixed tool contract supplies id, params, signal, updates, and context.
-		// oxlint-disable-next-line max-params -- QX-002: Pi supplies five fixed positional tool arguments.
-		async execute(_id, params, signal, _onUpdate, ctx) {
+		async execute(...[_id, params, signal, , ctx]) {
 			// Migrate newly returned legacy package notes without changing this session’s binding.
 			notesDir(ctx.cwd);
 			const session = await store.get(ctx);

package/src/paging.ts

@@ -36,34 +36,31 @@ export type PageAccess = {
 	readonly error: (ctx: PolicyContext, message: string, cursor?: string) => never;
 	readonly notes: (ctx: PolicyContext, page: NotesPage) => TextResult;
 };
+type PageAccounting = {
+	readonly pendingTokens: number;
+	readonly usage: number | null | undefined;
+};
+function reconcile(accounting: PageAccounting, usage: PageAccounting["usage"]): PageAccounting {
+	// Native usage may already include serial results, but not parallel siblings.
+	const counted =
+		typeof usage === "number" && typeof accounting.usage === "number"
+			? Math.max(0, usage - accounting.usage)
+			: 0;
+	return { pendingTokens: Math.max(0, accounting.pendingTokens - counted), usage };
+}
 /** Shared by note and history tools. Reservations precede delivery and reset at a turn boundary. */
 export class PageReservations {
-	private pendingTokens = 0;
-	private previousUsage: number | null | undefined;
+	private accounting: PageAccounting = { pendingTokens: 0, usage: undefined };
 	private readonly toolTokens: () => number;
 	constructor(toolTokens: () => number) {
 		this.toolTokens = toolTokens;
 	}
 	reset(): void {
-		this.pendingTokens = 0;
-		this.previousUsage = undefined;
+		this.accounting = { pendingTokens: 0, usage: undefined };
 	}
 	size(ctx: PolicyContext, request: PageRequest): number {
-		const usage = ctx.getContextUsage()?.tokens;
-		// Native usage may already include serial results, but not parallel siblings.
-		if (
-			usage !== undefined &&
-			usage !== null &&
-			this.previousUsage !== undefined &&
-			this.previousUsage !== null
-		) {
-			this.pendingTokens = Math.max(
-				0,
-				this.pendingTokens - Math.max(0, usage - this.previousUsage),
-			);
-		}
-		this.previousUsage = usage;
-		const remaining = pageCapacity(ctx, this.toolTokens) - this.pendingTokens;
+		this.accounting = reconcile(this.accounting, ctx.getContextUsage()?.tokens);
+		const remaining = pageCapacity(ctx, this.toolTokens) - this.accounting.pendingTokens;
 		const chars = Math.min(
 			MAX_PAGE_CHARS,
 			Math.max(0, remaining - PAGE_MARGIN_TOKENS) * 4 -
@@ -74,6 +71,15 @@ export class PageReservations {
 		}
 		return chars;
 	}
+	private reserve(text: string, imageCount = 0): void {
+		this.accounting = {
+			...this.accounting,
+			pendingTokens:
+				this.accounting.pendingTokens +
+				Math.ceil(text.length / 4) +
+				imageCount * (ESTIMATED_IMAGE_CHARS / 4),
+		};
+	}
 	private refuse(remaining: number, request: PageRequest): never {
 		const position =
 			request.cursor !== undefined && request.cursor !== ""
@@ -82,17 +88,16 @@ export class PageReservations {
 		const message = `Too little context remains to read a page safely. Call new_context first, then retry ${position}.`;
 		// Even refusals consume context; omit repeated guidance when it no longer fits.
 		const text = Math.ceil(message.length / 4) <= remaining ? message : "";
-		this.pendingTokens += Math.ceil(text.length / 4);
+		this.reserve(text);
 		throw new Error(text);
 	}
 	result(text: string, images: readonly ImageLike[], display: PosthorseDisplay): TextResult {
-		this.pendingTokens +=
-			Math.ceil(text.length / 4) + images.length * (ESTIMATED_IMAGE_CHARS / 4);
+		this.reserve(text, images.length);
 		return textResult(text, images, display);
 	}
 	error(ctx: PolicyContext, message: string, cursor?: string): never {
 		this.size(ctx, { offset: 0, cursor });
-		this.pendingTokens += Math.ceil(message.length / 4);
+		this.reserve(message);
 		throw new Error(message);
 	}
 	notes(ctx: PolicyContext, page: NotesPage): TextResult {

package/src/records.ts

@@ -0,0 +1,3 @@
+export function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}