pi-posthorse 0.9.3 → 0.10.1

package/src/notes.ts

@@ -1,13 +1,7 @@
-import {
-	appendFileSync,
-	existsSync,
-	mkdirSync,
-	readdirSync,
-	readFileSync,
-	realpathSync,
-	statSync,
-} from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { readdir, realpath, stat } from "node:fs/promises";
 import { dirname, isAbsolute, join, normalize, sep } from "node:path";
+import { setImmediate } from "node:timers/promises";
 import {
 	formatSize,
 	withFileMutationQueue,
@@ -18,6 +12,7 @@ import { Type } from "typebox";
 import { toolCards } from "../ui.ts";
 import {
 	MAX_PAGE_CHARS,
+	isRecord,
 	requireValue,
 	textResult,
 	type PolicyContext,
@@ -36,10 +31,25 @@ export type NotesParams = {
 };
 type NoteFile = { readonly path: string; readonly size: number; readonly mtimeMs: number };
 type NoteHits = { readonly rows: string[]; readonly more: boolean; readonly skipped: number };
+/** Paged operations take a fresh policy snapshot after their filesystem awaits. */
+type NotesAccess = {
+	readonly host: () => PolicyContext;
+	readonly pages: PageAccess;
+	readonly signal: AbortSignal | undefined;
+};
 /** Larger files are logs or evidence rather than notes; reading them would dominate a search. */
 const SEARCH_FILE_BYTES = 1024 * 1024;
 /** Overlapping reads cut a full search of a 212,000-file notes tree from 39 s to 14 s. */
 const SEARCH_BATCH = 16;
+/**
+ * Maximum explicit `stat` calls overlapped per batch. On a 212,751-note tree, 16, 64 and 256 took
+ * equal time within host noise. The walk enters one folder at a time, so this bounds our pending
+ * `stat` calls at any depth. On filesystems that report unknown entry types, Node 24's
+ * `readdir({ withFileTypes: true })` also issues its own `lstat` for every entry at once.
+ */
+const WALK_BATCH = 64;
+/** Formatting all 212,751 rows of one listing at once stalled Pi for 156-163 ms. */
+const FORMAT_BATCH = 10_000;
 /** Search rescans up to the requested offset, so this also caps the matches one call keeps. */
 const SEARCH_OFFSET_LIMIT = 1_000_000;
 function safeJoin(dir: string, path: string): string {
@@ -49,46 +59,105 @@ function safeJoin(dir: string, path: string): string {
 	}
 	return join(dir, relative);
 }
-function walk(directory: string, ancestors: readonly string[] = []): NoteFile[] {
-	const root = realpathSync(directory);
+/** Like `statSync(path, { throwIfNoEntry: false })`: an entry deleted mid-walk is skipped. */
+async function statIfPresent(path: string) {
+	try {
+		return await stat(path);
+	} catch (error) {
+		if (isRecord(error) && (error.code === "ENOENT" || error.code === "ENOTDIR")) {
+			return;
+		}
+		throw error;
+	}
+}
+/** A folder's present entries in listing order. */
+async function* folderEntries(directory: string, signal: AbortSignal | undefined) {
+	const entries = await readdir(directory, { withFileTypes: true });
+	let start = 0;
+	while (start < entries.length) {
+		signal?.throwIfAborted();
+		const batch = entries.slice(start, start + WALK_BATCH);
+		const firstFolder = batch.findIndex(
+			(entry) => entry.isDirectory() || entry.isSymbolicLink(),
+		);
+		const paths = batch
+			.slice(0, firstFolder === -1 ? batch.length : firstFolder + 1)
+			.map((entry) => join(directory, entry.name));
+		// Stats overlap only up to the next entry that may be a folder.
+		// oxlint-disable-next-line no-await-in-loop
+		const infos = await Promise.all(paths.map(statIfPresent));
+		for (const [index, path] of paths.entries()) {
+			start += 1;
+			const info = infos[index];
+			if (info !== undefined) {
+				yield { path, info };
+			}
+			if (info?.isDirectory() === true) {
+				// Stat later entries only after this folder's subtree is walked, discarding any
+				// already taken, so entries removed meanwhile are skipped.
+				break;
+			}
+		}
+	}
+}
+/** Files depth-first in directory-listing order, yielding between filesystem calls. */
+async function walk(
+	directory: string,
+	signal: AbortSignal | undefined,
+	ancestors: readonly string[] = [],
+): Promise<NoteFile[]> {
+	signal?.throwIfAborted();
+	const root = await realpath(directory);
 	if (ancestors.includes(root)) {
 		return [];
 	}
 	const next = [...ancestors, root];
-	return readdirSync(directory).flatMap((file) => {
-		const path = join(directory, file);
-		const info = statSync(path, { throwIfNoEntry: false });
-		if (info === undefined) {
-			return [];
+	const files: NoteFile[] = [];
+	for await (const { path, info } of folderEntries(directory, signal)) {
+		if (info.isDirectory()) {
+			for (const file of await walk(path, signal, next)) {
+				files.push(file);
+			}
+		} else {
+			files.push({ path, size: info.size, mtimeMs: info.mtimeMs });
 		}
-		return info.isDirectory()
-			? walk(path, next)
-			: [{ path, size: info.size, mtimeMs: info.mtimeMs }];
-	});
+	}
+	return files;
 }
-function notesUnder(target: string): NoteFile[] {
-	const info = statSync(target, { throwIfNoEntry: false });
+async function notesUnder(target: string, signal: AbortSignal | undefined): Promise<NoteFile[]> {
+	const info = await statIfPresent(target);
+	signal?.throwIfAborted();
 	if (info === undefined) {
 		return [];
 	}
 	const files = info.isDirectory()
-		? walk(target)
+		? await walk(target, signal)
 		: [{ path: target, size: info.size, mtimeMs: info.mtimeMs }];
+	signal?.throwIfAborted();
 	return files.sort((a, b) => b.mtimeMs - a.mtimeMs);
 }
-function listNotes(
+async function listNotes(
 	dir: string,
 	params: NotesParams,
-	host: PolicyContext,
-	pages: PageAccess,
-): TextResult {
+	access: NotesAccess,
+): Promise<TextResult> {
+	const { host, pages, signal } = access;
 	const folder = params.path;
 	const target = folder === undefined || folder === "" ? dir : safeJoin(dir, folder);
-	const rows = notesUnder(target).map(
-		(file) =>
-			`${file.path.slice(dir.length + 1)}  ${formatSize(file.size)}  ${new Date(file.mtimeMs).toISOString().slice(0, 16)}Z`,
-	);
-	return pages.notes(host, {
+	const files = await notesUnder(target, signal);
+	const rows: string[] = [];
+	for (let start = 0; start < files.length; start += FORMAT_BATCH) {
+		// Pi gets an event-loop turn before each batch of rows.
+		// oxlint-disable-next-line no-await-in-loop
+		await setImmediate();
+		signal?.throwIfAborted();
+		for (const file of files.slice(start, start + FORMAT_BATCH)) {
+			rows.push(
+				`${file.path.slice(dir.length + 1)}  ${formatSize(file.size)}  ${new Date(file.mtimeMs).toISOString().slice(0, 16)}Z`,
+			);
+		}
+	}
+	return pages.notes(host(), {
 		rows,
 		offset: params.offset ?? 0,
 		kind: "notes-list",
@@ -99,9 +168,9 @@ function listNotes(
 async function readNote(
 	dir: string,
 	params: NotesParams,
-	getHost: () => PolicyContext,
-	pages: PageAccess,
+	access: NotesAccess,
 ): Promise<TextResult> {
+	const { pages } = access;
 	const relative = requireValue(params.path, "path", params.op);
 	const path = safeJoin(dir, relative);
 	const info = statSync(path, { throwIfNoEntry: false });
@@ -109,7 +178,7 @@ async function readNote(
 		throw new Error(`No note at ${relative}. Use op "list" to see available notes.`);
 	}
 	if (info.isDirectory()) {
-		return listNotes(dir, params, getHost(), pages);
+		return listNotes(dir, params, access);
 	}
 	if (await isBinaryFile(path)) {
 		throw new Error(
@@ -122,7 +191,7 @@ async function readNote(
 		throw new Error(`Offset ${offset} is past the end of ${relative} (${text.length} chars).`);
 	}
 	const header = `File: ${path}\n`;
-	const host = getHost();
+	const host = access.host();
 	const chars = pages.size(host, { offset }) - header.length;
 	if (chars <= 0) {
 		pages.error(
@@ -197,11 +266,13 @@ async function noteHits(
 	limit: number,
 	signal?: AbortSignal,
 ): Promise<NoteHits> {
-	const notes = notesUnder(dir);
+	const notes = await notesUnder(dir, signal);
 	const rows: string[] = [];
 	let length = -1;
 	let skipped = 0;
 	for (let start = 0; start < notes.length; start += SEARCH_BATCH) {
+		// A batch of notes over 1 MiB reads nothing that would notice cancellation.
+		signal?.throwIfAborted();
 		// Batches keep note order, so a search stops within one batch of the page limit.
 		// oxlint-disable-next-line no-await-in-loop
 		const batch = await Promise.all(
@@ -231,21 +302,20 @@ async function noteHits(
 async function searchNotes(
 	dir: string,
 	params: NotesParams,
-	access: { readonly host: PolicyContext; readonly pages: PageAccess },
-	signal?: AbortSignal,
+	access: NotesAccess,
 ): Promise<TextResult> {
 	const { host, pages } = access;
 	const query = requireValue(params.query, "query", params.op);
 	const offset = params.offset ?? 0;
 	if (offset >= SEARCH_OFFSET_LIMIT) {
 		pages.error(
-			host,
+			host(),
 			`Notes search pages end before offset ${SEARCH_OFFSET_LIMIT}; search for something more specific.`,
 		);
 	}
-	const hits = await noteHits(dir, query.toLowerCase(), offset + MAX_PAGE_CHARS, signal);
+	const hits = await noteHits(dir, query.toLowerCase(), offset + MAX_PAGE_CHARS, access.signal);
 	const skipped = hits.skipped === 1 ? "1 note" : `${hits.skipped} notes`;
-	return pages.notes(host, {
+	return pages.notes(host(), {
 		rows: hits.rows,
 		more: hits.more,
 		offset,
@@ -297,17 +367,18 @@ export function registerNotes(
 		// oxlint-disable-next-line max-params
 		async execute(_id, params, signal, _onUpdate, ctx) {
 			const dir = notesDir(ctx.cwd);
+			const access: NotesAccess = { host: () => policy(ctx), pages, signal };
 			switch (params.op) {
 				case "list":
-					return listNotes(dir, params, policy(ctx), pages);
+					return listNotes(dir, params, access);
 				case "read":
-					return readNote(dir, params, () => policy(ctx), pages);
+					return readNote(dir, params, access);
 				case "write":
 					return writeNote(dir, params, signal);
 				case "append":
 					return appendNote(dir, params, signal);
 				case "search":
-					return searchNotes(dir, params, { host: policy(ctx), pages }, signal);
+					return searchNotes(dir, params, access);
 			}
 		},
 	});

package/src/paging.ts

@@ -63,7 +63,7 @@ export class PageReservations {
 			);
 		}
 		this.previousUsage = usage;
-		const remaining = pageCapacity(ctx, this.toolTokens()) - this.pendingTokens;
+		const remaining = pageCapacity(ctx, this.toolTokens) - this.pendingTokens;
 		const chars = Math.min(
 			MAX_PAGE_CHARS,
 			Math.max(0, remaining - PAGE_MARGIN_TOKENS) * 4 -

package/src/recovery-results.ts

@@ -9,6 +9,7 @@ import {
 	toolIdentity,
 } from "./message-text.ts";
 
+export type RecoveryEntry = EntryLike & { readonly retained: boolean };
 type LinkedCall = { readonly entry: EntryLike; readonly block: ToolCallLike };
 export type RecoveryBlock = { readonly header: string; readonly text: string };
 export type RecoveryBatch = { readonly callId?: string; readonly blocks: readonly RecoveryBlock[] };
@@ -82,12 +83,14 @@ function resultBlock(
 	};
 }
 /** Async receipts may arrive after a response; completion does not establish receipt delivery. */
-export function recoverableToolResults(entries: readonly EntryLike[]): RecoveryBatch | undefined {
+export function recoverableToolResults(
+	entries: readonly RecoveryEntry[],
+): RecoveryBatch | undefined {
 	const calls = callsById(entries);
 	const start = trailingStart(entries);
 	const results = entries.filter((entry, index) => {
 		const message = entry.message;
-		if (message?.role !== "toolResult" || message.toolCallId === undefined) {
+		if (message?.role !== "toolResult" || message.toolCallId === undefined || entry.retained) {
 			return false;
 		}
 		const call = calls.get(message.toolCallId);

package/src/recovery.ts

@@ -18,6 +18,7 @@ import {
 	recoverableToolResults,
 	type RecoveryBatch,
 	type RecoveryBlock,
+	type RecoveryEntry,
 } from "./recovery-results.ts";
 
 const MAX_RECOVERY_RECORD_CHARS = 4_000;
@@ -121,6 +122,7 @@ function projectedCurrent(
 	entries: readonly EntryLike[],
 	projected: readonly ProjectedEntry[],
 	current: readonly EntryLike[] = entries.slice(contextStart(entries).start),
+	retained: ReadonlySet<string> = new Set(),
 ): EntryLike[] {
 	const edits = contextEdits(entries);
 	const omittedIds = new Set(
@@ -130,7 +132,7 @@ function projectedCurrent(
 	);
 	return current.flatMap((entry) => {
 		const id = entry.id ?? "";
-		if (id !== "" && omittedIds.has(id)) {
+		if (retained.has(id) || omittedIds.has(id)) {
 			return [];
 		}
 		const edit = edits.get(id);
@@ -211,6 +213,7 @@ function recoveryAncestry(
 	entries: readonly EntryLike[],
 	projected: readonly ProjectedEntry[],
 	ownerQuestionRegistered: boolean,
+	retained: ReadonlySet<string>,
 ): {
 	readonly checkpoint?: EntryLike;
 	readonly carried: readonly RecoveryRecord[];
@@ -234,7 +237,7 @@ function recoveryAncestry(
 		if (owners.length > 0) {
 			return {
 				checkpoint: automaticBoundary(window.boundary) ? undefined : window.boundary,
-				carried: anchors(owners).fixed,
+				carried: anchors(owners.filter((record) => !retained.has(record.id))).fixed,
 				skipped,
 			};
 		}
@@ -262,13 +265,16 @@ function skippedRecords(ids: readonly string[], limit: number): string | undefin
 function projectedToolEntries(
 	entries: readonly EntryLike[],
 	projected: readonly ProjectedEntry[],
-): EntryLike[] {
+	retained: ReadonlySet<string>,
+): RecoveryEntry[] {
 	const edits = contextEdits(entries);
 	return projected.flatMap(({ sourceEntry, messages }) =>
 		messages
 			.filter((message) => message.role === "assistant" || message.role === "toolResult")
 			.map((message) => ({
 				type: "message",
+				// Resolve retention before replacing identity with the history-read reference.
+				retained: retained.has(sourceEntry.id ?? ""),
 				id: edits.get(sourceEntry.id ?? "")?.id ?? sourceEntry.id,
 				message,
 			})),
@@ -378,37 +384,69 @@ function renderIndex(records: readonly RecoveryRecord[], available: number): str
 		...listed,
 	].join("\n");
 }
-/** Raw owner anchors and projected tool evidence have distinct provenance and share one bounded payload. */
-export function buildAutoHandoff(
+function selectedInputs(
 	entries: readonly EntryLike[],
 	projected: readonly ProjectedEntry[],
-	maxChars: number,
-	ownerQuestionRegistered: boolean,
-): string {
-	const history = recoveryAncestry(entries, projected, ownerQuestionRegistered);
-	const priorWindow = history.checkpoint;
+	options: {
+		readonly ownerQuestionRegistered: boolean;
+		readonly retained: ReadonlySet<string>;
+		readonly carried: readonly RecoveryRecord[];
+	},
+): { readonly fixed: readonly RecoveryRecord[]; readonly others: readonly RecoveryRecord[] } {
+	const { ownerQuestionRegistered, retained, carried } = options;
+	const current = projectedCurrent(entries, projected);
+	const allRecords = ownerRecords(current, projected, ownerQuestionRegistered);
 	const records = ownerRecords(
-		projectedCurrent(entries, projected),
+		projectedCurrent(entries, projected, undefined, retained),
 		projected,
 		ownerQuestionRegistered,
 	);
 	const { fixed, others } = anchors(records);
-	if (!records.some((record) => record.kind === "owner")) {
+	if (!allRecords.some((record) => record.kind === "owner")) {
 		fixed.unshift(
-			...history.carried.map((record) => ({
-				...record,
-				label: `${record.label}; carried from an earlier window, possibly already handled; not current progress`,
-			})),
+			...carried.map((record) =>
+				Object.assign({}, record, {
+					label: `${record.label}; carried from an earlier window, possibly already handled; not current progress`,
+				}),
+			),
 		);
 	}
+	return { fixed, others };
+}
+/** Raw owner anchors and projected tool evidence have distinct provenance and share one bounded payload. */
+export function buildAutoHandoff(
+	entries: readonly EntryLike[],
+	projected: readonly ProjectedEntry[],
+	maxChars: number,
+	options: {
+		readonly ownerQuestionRegistered: boolean;
+		readonly retainedEntryIds?: ReadonlySet<string>;
+	},
+): string {
+	const { ownerQuestionRegistered, retainedEntryIds: retained = new Set<string>() } = options;
+	const preamble =
+		retained.size === 0
+			? PREAMBLE
+			: `${PREAMBLE}\nRecent messages follow separately; their inputs and tool evidence are not repeated in this record.`;
+	const history = recoveryAncestry(entries, projected, ownerQuestionRegistered, retained);
+	const priorWindow = history.checkpoint;
+	const { fixed, others } = selectedInputs(entries, projected, {
+		ownerQuestionRegistered,
+		retained,
+		carried: history.carried,
+	});
+	const emptyInputHeader =
+		retained.size > 0
+			? "No discarded owner or visible coordination inputs were selected for this recovery record."
+			: "No selected current-window owner or visible coordination inputs were found.";
 	const inputHeader =
 		fixed.length > 0
 			? "Selected owner and coordination inputs (chronological):"
-			: "No selected current-window owner or visible coordination inputs were found.";
-	const batch = recoverableToolResults(projectedToolEntries(entries, projected));
+			: emptyInputHeader;
+	const batch = recoverableToolResults(projectedToolEntries(entries, projected, retained));
 	const header = batchHeader(batch);
 	const minimum = [
-		PREAMBLE,
+		preamble,
 		inputHeader,
 		...fixed.map((record) => formatRecord(record, 0)),
 		header,
@@ -427,7 +465,7 @@ export function buildAutoHandoff(
 		(history.skipped.length > 0 ? 1 : 0);
 	const fixedBudget = Math.max(
 		0,
-		maxChars - joined([PREAMBLE, inputHeader, plan.bare]).length - HANDOFF_OVERHEAD_RESERVE,
+		maxChars - joined([preamble, inputHeader, plan.bare]).length - HANDOFF_OVERHEAD_RESERVE,
 	);
 	const fixedLimit =
 		count > 0
@@ -438,7 +476,7 @@ export function buildAutoHandoff(
 		skippedRecords(history.skipped, fixedLimit),
 	]);
 	const fixedParts = [
-		PREAMBLE,
+		preamble,
 		inputHeader,
 		...fixed.map((record) => formatRecord(record, fixedLimit)),
 	];

package/src/retention.ts

@@ -0,0 +1,203 @@
+import {
+	DEFAULT_COMPACTION_SETTINGS,
+	estimateTokens,
+	findCutPoint,
+	type ProjectedSessionEntry,
+	type SessionEntry,
+	type SessionMessageEntry,
+} from "@earendil-works/pi-coding-agent";
+import { freshPayloadChars } from "./budget.ts";
+import {
+	MAX_HANDOFF_CHARS,
+	MIN_PAGE_CHARS,
+	type EntryLike,
+	type MessageLike,
+	type PolicyContext,
+} from "./contracts.ts";
+import { buildAutoHandoff } from "./recovery.ts";
+
+type RecoveryCapacity = {
+	readonly host: PolicyContext;
+	readonly toolTokens: number;
+	readonly pendingMessages?: readonly MessageLike[];
+	readonly firstKeptEntryId?: string;
+};
+type RetainedTail = {
+	readonly firstKeptEntryId?: string;
+	readonly ids: ReadonlySet<string>;
+};
+type Immutable<T> = T extends string | number | boolean | null | undefined
+	? T
+	: T extends readonly (infer Item)[]
+		? readonly Immutable<Item>[]
+		: T extends object
+			? { readonly [Key in keyof T]: Immutable<T[Key]> }
+			: T;
+type ProjectionEntry = Immutable<ProjectedSessionEntry>;
+const CUT_ROLES = new Set([
+	"user",
+	"assistant",
+	"bashExecution",
+	"custom",
+	"branchSummary",
+	"compactionSummary",
+]);
+function visibleMessages(entry: ProjectionEntry) {
+	return entry.messages.filter((message) => message.role !== "system");
+}
+function safeStart(entry: ProjectionEntry): boolean {
+	return (
+		entry.sourceEntry.type !== "compaction" &&
+		visibleMessages(entry).some((message) => CUT_ROLES.has(message.role))
+	);
+}
+function nativeMessage(
+	message: ProjectionEntry["messages"][number],
+): SessionMessageEntry["message"] {
+	switch (message.role) {
+		case "assistant":
+			return {
+				role: "assistant",
+				api: message.api,
+				provider: message.provider,
+				model: message.model,
+				stopReason: message.stopReason,
+				usage: message.usage,
+				timestamp: message.timestamp,
+				content: [...message.content],
+			};
+		case "toolResult":
+			return {
+				role: "toolResult",
+				toolCallId: message.toolCallId,
+				toolName: message.toolName,
+				isError: message.isError,
+				timestamp: message.timestamp,
+				content: [...message.content],
+			};
+		case "user":
+		case "custom":
+			return {
+				...message,
+				content:
+					typeof message.content === "string" ? message.content : [...message.content],
+			};
+		case "system":
+			// Compaction checkpoints replace earlier system declarations.
+			return { role: "user", content: "", timestamp: message.timestamp };
+		case "bashExecution":
+		case "branchSummary":
+		case "compactionSummary":
+			return { ...message };
+	}
+}
+/** The exported native cut finder reads raw entries; materialize only projected contributions. */
+function projectedCut(entries: readonly ProjectionEntry[], keep: number): number {
+	const materialized = entries.flatMap<SessionEntry>(({ sourceEntry, messages }) =>
+		messages.length === 0 || sourceEntry.type === "compaction"
+			? [{ ...sourceEntry, type: "custom", customType: "posthorse-projection", data: {} }]
+			: messages.map((message) => ({
+					id: sourceEntry.id,
+					parentId: sourceEntry.parentId,
+					timestamp: sourceEntry.timestamp,
+					type: "message",
+					message: nativeMessage(message),
+				})),
+	);
+	const cut = findCutPoint(materialized, 0, materialized.length, keep);
+	const id = materialized[cut.firstKeptEntryIndex]?.id;
+	return entries.findIndex((entry) => entry.sourceEntry.id === id);
+}
+function pairedTail(entries: readonly ProjectionEntry[]): boolean {
+	const calls = new Set<string>();
+	for (const message of entries.flatMap(visibleMessages)) {
+		if (message.role === "assistant") {
+			for (const part of message.content.filter((block) => block.type === "toolCall")) {
+				calls.add(part.id);
+			}
+		} else if (message.role === "toolResult") {
+			if (!calls.delete(message.toolCallId)) {
+				return false;
+			}
+		}
+	}
+	return calls.size === 0;
+}
+function boundedTail(
+	entries: readonly ProjectionEntry[],
+	start: number,
+	maxTokens: number,
+): RetainedTail {
+	const costs = entries.map((entry) =>
+		entry.sourceEntry.type === "compaction"
+			? 0
+			: visibleMessages(entry).reduce(
+					(sum, message) => sum + estimateTokens(nativeMessage(message)),
+					0,
+				),
+	);
+	let tokens = costs.slice(start).reduce((sum, cost) => sum + cost, 0);
+	for (let index = start; index < entries.length; index++) {
+		if (tokens > 0 && tokens <= maxTokens && safeStart(entries[index])) {
+			const tail = entries.slice(index);
+			if (pairedTail(tail)) {
+				return {
+					firstKeptEntryId: entries[index].sourceEntry.id,
+					ids: new Set(tail.map((entry) => entry.sourceEntry.id)),
+				};
+			}
+		}
+		tokens -= costs[index];
+	}
+	return { ids: new Set() };
+}
+function retainedTail(
+	projected: readonly ProjectionEntry[],
+	capacity: RecoveryCapacity,
+	maxTokens: number,
+): RetainedTail {
+	const keep =
+		capacity.host.getCompactionSettings().keepRecentTokens ??
+		DEFAULT_COMPACTION_SETTINGS.keepRecentTokens;
+	if (!Number.isFinite(keep) || keep <= 0 || maxTokens <= 0) {
+		return { ids: new Set() };
+	}
+	const boundary = projected.findIndex(
+		(entry) => entry.sourceEntry.type === "compaction" && entry.messages.length > 0,
+	);
+	const entries = projected.slice(boundary + 1);
+	if (entries.length === 0) {
+		return { ids: new Set() };
+	}
+	const prepared = entries.findIndex(
+		(entry) => entry.sourceEntry.id === capacity.firstKeptEntryId,
+	);
+	const start = prepared >= 0 ? prepared : projectedCut(entries, keep);
+	return start < 0 ? { ids: new Set() } : boundedTail(entries, start, maxTokens);
+}
+/** Recent messages and recovery share half the fresh operational budget, leaving work headroom. */
+export function automaticRecovery(
+	entries: readonly EntryLike[],
+	projected: readonly ProjectionEntry[],
+	capacity: RecoveryCapacity,
+	ownerQuestionRegistered: boolean,
+): { readonly handoff: string; readonly firstKeptEntryId?: string } | undefined {
+	const payload = freshPayloadChars(
+		capacity.host,
+		capacity.toolTokens,
+		capacity.pendingMessages,
+		Number.MAX_SAFE_INTEGER,
+	);
+	const limit = Math.min(MAX_HANDOFF_CHARS, payload);
+	if (limit < MIN_PAGE_CHARS) {
+		return undefined;
+	}
+	const retained = retainedTail(projected, capacity, Math.floor((payload - limit) / 4));
+	const handoff = buildAutoHandoff(entries, projected, limit, {
+		ownerQuestionRegistered,
+		retainedEntryIds: retained.ids,
+	});
+	return handoff.length > limit
+		? undefined
+		: { handoff, firstKeptEntryId: retained.firstKeptEntryId };
+}