pi-posthorse 0.10.25 → 0.10.26

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-posthorse",
-	"version": "0.10.25",
+	"version": "0.10.26",
 	"type": "module",
 	"description": "Posthorse: fresh context, same journey. No-summary context rollover for Pi, with sparse budget reminders, handoffs, notes, and history.",
 	"keywords": [

package/src/boundary.ts

@@ -1,4 +1,10 @@
-import { AUTO_HANDOFF_PREFIX, isRecord, type EntryLike, type ProjectedEntry } from "./contracts.ts";
+import {
+	AUTO_HANDOFF_PREFIX,
+	POSTHORSE_COMPACTION,
+	isRecord,
+	type EntryLike,
+	type ProjectedEntry,
+} from "./contracts.ts";
 
 export type BoundaryKind = "fork" | "native" | "automatic" | "explicit" | "posthorse";
 /** Everything the app derives from one persisted context boundary, decided in one place. */
@@ -50,7 +56,7 @@ export function classifyBoundary(entry?: EntryLike): Boundary | undefined {
 	}
 	const details = isRecord(entry.details) ? entry.details : undefined;
 	const freshGuidance = !providerSummaryBlock(entry);
-	if (details?.posthorse !== 1) {
+	if (details?.posthorse !== POSTHORSE_COMPACTION) {
 		return { kind: "native", window: false, chainsAncestry: false, freshGuidance };
 	}
 	const kind = compactionKind(details);

package/src/contracts.ts

@@ -1,5 +1,5 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { PosthorseDisplay } from "../ui.ts";
+import type { PosthorseDisplay } from "./ui/display.ts";
 
 export { isRecord } from "./records.ts";
 
@@ -40,6 +40,8 @@ export type ToolCallLike = {
 };
 export type MessageLike = {
 	readonly role?: string | undefined;
+	readonly timestamp?: number | undefined;
+	readonly sections?: unknown;
 	readonly stopReason?: string | undefined;
 	readonly errorMessage?: string | undefined;
 	readonly content?: unknown;
@@ -112,6 +114,48 @@ 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.";
 
+/**
+ * Journal wording is a storage format: recovery reads sessions back, across releases, by
+ * matching this exact text. Producers and parsers share one vocabulary, so a wording change
+ * is a migration and must keep reading the previous release's journals.
+ */
+export const BOUNDARY_TYPE = "posthorse-boundary";
+export const RESET_DEFERRED_TYPE = "posthorse-reset-deferred";
+export const RETAINED_TAIL_TYPE = "posthorse-retained-tail";
+export const RETAINED_MARKER_PREFIX = "Context rolled over after entry ";
+/** Display marker the legacy fork's context-window extension projects into messages. */
+export const LEGACY_WINDOW_TYPE = "context-window";
+/** The details marker every compaction Posthorse drafts carries; readers reject other values. */
+export const POSTHORSE_COMPACTION = 1;
+
+export function posthorseDetails(reason: string): {
+	readonly posthorse: typeof POSTHORSE_COMPACTION;
+	readonly reason: string;
+} {
+	return { posthorse: POSTHORSE_COMPACTION, reason };
+}
+
+/** Receipt lines the notes tool returns; recovery matches them to record note touches. */
+export const NOTE_RECEIPT = {
+	wrote: "Wrote ",
+	appended: "Appended to ",
+	file: "File: ",
+	directory: "Notes directory: ",
+} as const;
+
+export function noteWriteReceipt(path: string): string {
+	return `${NOTE_RECEIPT.wrote}${path}`;
+}
+export function noteAppendReceipt(path: string): string {
+	return `${NOTE_RECEIPT.appended}${path}`;
+}
+export function noteReadHeader(path: string): string {
+	return `${NOTE_RECEIPT.file}${path}\n`;
+}
+export function notesDirectoryHeader(directory: string): string {
+	return `${NOTE_RECEIPT.directory}${directory}\n`;
+}
+
 export function unknownArray(value: unknown): readonly unknown[] | undefined {
 	return Array.isArray(value) ? value : undefined;
 }

package/src/files.ts

@@ -86,6 +86,12 @@ async function existingNote(target: string) {
 	}
 	return previous;
 }
+/** Reserved by publishFile; inventories hide these names without deleting their contents. */
+export function isPublicationTemporaryName(name: string): boolean {
+	return /^\.posthorse-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\.tmp$/.test(
+		name,
+	);
+}
 /** Same-directory replacement; pre-rename failures preserve the old note and its metadata. */
 export async function publishFile(
 	path: string,

package/src/guidance.ts

@@ -1,4 +1,4 @@
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "typebox";
 import { Check } from "typebox/value";
 import {
@@ -9,8 +9,14 @@ import {
 } from "./budget.ts";
 import type { EntryLike, PolicyContext, SnapshotReader } from "./contracts.ts";
 import { startsFreshGuidanceEpoch } from "./boundary.ts";
-import { createEpochCache, type EpochValue } from "./epoch-cache.ts";
-import { sessionEntry, toolFacts, type SessionHost, type SessionIdentity } from "./host.ts";
+import { createEpochCache, type EpochValue, type SessionContext } from "./epoch-cache.ts";
+import {
+	sessionEntry,
+	toolFacts,
+	type SessionHost,
+	type SessionIdentity,
+	type ToolRegistry,
+} from "./host.ts";
 
 export const WINDOW_GUIDANCE_TYPE = "posthorse-window-guidance";
 const guidanceRecordSchema = Type.Object({
@@ -33,12 +39,13 @@ type GuidanceEpoch = {
 	readonly tools: GuidanceTools | undefined;
 };
 export type WindowGuidance = {
-	readonly resolve: (ctx: ExtensionContext, host: PolicyContext) => string;
-	readonly deliver: (ctx: ExtensionContext, host: PolicyContext) => string;
+	/** Only the session manager is read; the same context the epoch cache accepts. */
+	readonly resolve: (ctx: SessionContext, host: PolicyContext) => string;
+	readonly deliver: (ctx: SessionContext, host: PolicyContext) => string;
 	readonly reset: () => void;
 };
 
-export function activeGuidanceTools(pi: ExtensionAPI): GuidanceTools {
+export function activeGuidanceTools(pi: ToolRegistry): GuidanceTools {
 	const { activeUnnamespaced } = toolFacts(pi);
 	return {
 		newContext: activeUnnamespaced.has("new_context"),
@@ -122,7 +129,10 @@ function scanGuidanceEpoch(
 		...withMemoryEpoch(collected, memoryByEpoch?.get(anchorKey)),
 	};
 }
-export function createWindowGuidance(pi: ExtensionAPI): WindowGuidance {
+/** The journal and tool-registry members guidance borrows; the host's full API satisfies these. */
+export type GuidanceRegistry = ToolRegistry & Pick<ExtensionAPI, "appendEntry">;
+
+export function createWindowGuidance(pi: GuidanceRegistry): WindowGuidance {
 	let memoryByManager = new WeakMap<object, Map<string, MemoryEpoch>>();
 	const epochs = createEpochCache<GuidanceEpoch>((ctx, identity, previous) =>
 		scanGuidanceEpoch(
@@ -132,6 +142,21 @@ export function createWindowGuidance(pi: ExtensionAPI): WindowGuidance {
 			memoryByManager.get(ctx.sessionManager),
 		),
 	);
+	/**
+	 * A fresh anchor retires every earlier one on this branch: nothing reads an old epoch again
+	 * without /tree, which resets all memory. Keep only the current anchor's delivered text.
+	 */
+	const pruneRetiredEpochs = (manager: object, anchorKey: string): void => {
+		const byEpoch = memoryByManager.get(manager);
+		if (byEpoch === undefined) {
+			return;
+		}
+		for (const key of byEpoch.keys()) {
+			if (key !== anchorKey) {
+				byEpoch.delete(key);
+			}
+		}
+	};
 	return {
 		resolve(ctx, host) {
 			const epoch = epochs.read(ctx);
@@ -140,8 +165,19 @@ export function createWindowGuidance(pi: ExtensionAPI): WindowGuidance {
 				epoch.byBudget.get(key) ?? buildGuidance(host, epoch.tools ?? ALL_GUIDANCE_TOOLS)
 			);
 		},
+		/**
+		 * Delivering guidance from inside the request hook must persist before the request: a
+		 * restart after a rollover with a provider summary block has to reuse these exact bytes —
+		 * the leading system message is sent unchanged, and in-memory delivery state does not
+		 * survive. On the fork, the provider-summary request runs this hook mid-compaction. That
+		 * is safe twice over: the request that reached the rollover threshold already delivered
+		 * this budget's text, so the summary request reuses it and writes nothing; and a
+		 * compaction with a summary block keeps the previous guidance anchor, so even a budget
+		 * change mid-compaction appends inside the epoch the next window still reads.
+		 */
 		deliver(ctx, host) {
 			const epoch = epochs.read(ctx);
+			pruneRetiredEpochs(ctx.sessionManager, epoch.anchorKey);
 			const key = budgetGuidanceKey(host);
 			const existing = epoch.byBudget.get(key);
 			if (existing !== undefined) {
@@ -177,7 +213,7 @@ export function createWindowGuidance(pi: ExtensionAPI): WindowGuidance {
 	};
 }
 export function registerGuidance(
-	pi: ExtensionAPI,
+	pi: Pick<ExtensionAPI, "on">,
 	policy: SnapshotReader,
 	windowGuidance: WindowGuidance,
 ): void {
@@ -185,6 +221,7 @@ export function registerGuidance(
 	pi.on("before_agent_start", (event) => {
 		promptOptions = event.systemPromptOptions;
 	});
+
 	pi.on("agent_settled", () => {
 		// Prompt options belong to one run, never to later idle context evaluation.
 		promptOptions = undefined;

package/src/note-discovery.ts

@@ -1,6 +1,7 @@
 import { readdir, stat } from "node:fs/promises";
-import { join, relative } from "node:path";
+import { basename, join, relative } from "node:path";
 import { isRecord } from "./contracts.ts";
+import { isPublicationTemporaryName } from "./files.ts";
 import { sessionNoteTouches } from "./note-evidence.ts";
 import { notesUnder, type NoteFile } from "./note-inventory.ts";
 import {
@@ -118,6 +119,9 @@ async function readReference(
 	path: string,
 	signal: AbortSignal | undefined,
 ): Promise<DiscoveredNote | undefined> {
+	if (isPublicationTemporaryName(basename(path))) {
+		return;
+	}
 	const target = await session.access(path, { signal });
 	if (target.kind === "own") {
 		return;

package/src/note-inventory.ts

@@ -1,6 +1,7 @@
 import { readdir, realpath, stat } from "node:fs/promises";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 import { isRecord, presentText } from "./contracts.ts";
+import { isPublicationTemporaryName } from "./files.ts";
 import {
 	canonicalPath,
 	inside,
@@ -26,7 +27,9 @@ async function statIfPresent(path: string) {
 }
 /** Preserve depth-first listing order and recheck later entries after visiting each folder. */
 async function* folderEntries(directory: string, signal: AbortSignal | undefined) {
-	const entries = await readdir(directory, { withFileTypes: true });
+	const entries = (await readdir(directory, { withFileTypes: true })).filter(
+		(entry) => !isPublicationTemporaryName(entry.name),
+	);
 	let start = 0;
 	while (start < entries.length) {
 		signal?.throwIfAborted();
@@ -99,6 +102,9 @@ export async function notesUnder(
 		requested === undefined || requested === "."
 			? scopeDirectory(scope)
 			: notePath(scope, requested);
+	if (isPublicationTemporaryName(basename(target))) {
+		return [];
+	}
 	const info = await statIfPresent(target);
 	options.signal?.throwIfAborted();
 	if (info === undefined) {

package/src/note-store.ts

@@ -32,6 +32,8 @@ import {
 import type { NotesRecovery } from "./note-evidence.ts";
 
 type NotesManager = ExtensionContext["sessionManager"];
+/** The journal member the notes store borrows; the host's full API satisfies this. */
+type NotesApi = Pick<ExtensionAPI, "appendEntry">;
 export type NoteCall = { readonly id: string; readonly rootId: string };
 type Adoption = "owned" | "adopted";
 /**
@@ -42,7 +44,7 @@ export type NoteAccess =
 	| { readonly kind: "own"; readonly address: NoteAddress; readonly path: string }
 	| { readonly kind: "inherited"; readonly address: NoteAddress; readonly path: string };
 export class SessionNotes {
-	readonly #pi: ExtensionAPI;
+	readonly #pi: NotesApi;
 	readonly binding: NoteBinding;
 	readonly #manager: NotesManager;
 	readonly #source: NoteSource;
@@ -50,7 +52,7 @@ export class SessionNotes {
 	readonly scopes: readonly NoteScope[];
 	readonly #calls = new Map<string, string>();
 	readonly #revisions = new Map<string, number>();
-	constructor(pi: ExtensionAPI, binding: NoteBinding, manager: NotesManager, source: NoteSource) {
+	constructor(pi: NotesApi, binding: NoteBinding, manager: NotesManager, source: NoteSource) {
 		this.#pi = pi;
 		this.binding = binding;
 		this.#manager = manager;
@@ -251,8 +253,9 @@ export type NotesStore = {
 type SessionState =
 	| { readonly kind: "initializing"; readonly value: Promise<SessionNotes> }
 	| { readonly kind: "ready"; readonly value: SessionNotes };
-export function createNotesStore(pi: ExtensionAPI): NotesStore {
+export function createNotesStore(pi: NotesApi): NotesStore {
 	const sessions = new Map<string, SessionState>();
+
 	const get = (ctx: ExtensionContext): Promise<SessionNotes> => {
 		const key = sessionKey(ctx);
 		const existing = sessions.get(key);

package/src/notes.ts

@@ -11,6 +11,10 @@ import { Type } from "typebox";
 import { toolCards } from "../ui.ts";
 import {
 	MAX_PAGE_CHARS,
+	noteAppendReceipt,
+	noteReadHeader,
+	noteWriteReceipt,
+	notesDirectoryHeader,
 	presentText,
 	requireValue,
 	textResult,
@@ -84,7 +88,7 @@ async function listNotes(
 		offset: params.offset ?? 0,
 		kind: "notes-list",
 		empty: folder === undefined ? "(no notes yet)" : `(no notes in ${folder})`,
-		header: `Notes directory: ${dir}\n`,
+		header: notesDirectoryHeader(dir),
 	});
 }
 async function readNote(
@@ -124,7 +128,7 @@ async function readNote(
 	}
 	const header =
 		target.kind === "own"
-			? `File: ${path}\n`
+			? noteReadHeader(path)
 			: `Read-only live reference: notes read ${JSON.stringify({ scope: scopeDirectory(target.address), path: target.address.path })}\n`;
 	const end = Math.min(
 		text.length,
@@ -170,7 +174,7 @@ async function writeNote(
 			access.call,
 		);
 	});
-	return textResult(`Wrote ${path}`, [], { kind: "note-write" });
+	return textResult(noteWriteReceipt(path), [], { kind: "note-write" });
 }
 async function appendNote(
 	session: SessionNotes,
@@ -203,7 +207,7 @@ async function appendNote(
 			access.call,
 		);
 	});
-	return textResult(`Appended to ${path}`, [], { kind: "note-append" });
+	return textResult(noteAppendReceipt(path), [], { kind: "note-append" });
 }
 /** One note's matching lines as `path:line: excerpt` rows. */
 function matchingLines(name: string, text: string, query: string): string[] {

package/src/recovery-note-touches.ts

@@ -1,4 +1,5 @@
 import {
+	NOTE_RECEIPT,
 	isRecord,
 	optionalString,
 	presentText,
@@ -15,7 +16,7 @@ export type ScannedNoteEntry = {
 	readonly entryId: string;
 	readonly inRetained: boolean;
 };
-type ContentTouchKind = "full-write" | "partial-write" | "read" | "clear";
+export type ContentTouchKind = "full-write" | "partial-write" | "read" | "clear";
 export type NoteTarget = {
 	readonly notePath: string;
 	readonly absPath?: string | undefined;
@@ -81,6 +82,21 @@ function matchMarkerPath(slash: string): string | undefined {
 function absoluteSlashPath(slash: string): boolean {
 	return slash.startsWith("/") || /^[A-Za-z]:\//u.test(slash);
 }
+
+/** Receipt lines are a storage format: parse exactly what the notes tool emits. */
+function receiptPattern(prefix: string): RegExp {
+	return new RegExp(`^${prefix.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&")}([^\\r\\n]+)$`, "mu");
+}
+const receiptPatterns: readonly (readonly [RegExp, ContentTouchKind])[] = [
+	[receiptPattern(NOTE_RECEIPT.wrote), "full-write"],
+	[receiptPattern(NOTE_RECEIPT.appended), "partial-write"],
+	[receiptPattern(NOTE_RECEIPT.file), "read"],
+];
+
+export function notesDirectoryOf(text: string): string | undefined {
+	return receiptPattern(NOTE_RECEIPT.directory).exec(text)?.[1];
+}
+
 function unscopedNoteTarget(trimmed: string, slash: string): NoteTarget | undefined {
 	if (absoluteSlashPath(slash)) {
 		const base = normalizeRelPath(slash.slice(slash.lastIndexOf("/") + 1));
@@ -114,15 +130,10 @@ function resolveNoteTarget(
 	return fromNotesTool ? unscopedNoteTarget(trimmed, slash) : undefined;
 }
 
-function extractNotesResultTarget(
+export function extractNotesResultTarget(
 	text: string,
 ): { readonly kind: ContentTouchKind; readonly rawPath: string } | undefined {
-	const patterns: readonly (readonly [RegExp, ContentTouchKind])[] = [
-		[/^Wrote ([^\r\n]+)$/mu, "full-write"],
-		[/^Appended to ([^\r\n]+)$/mu, "partial-write"],
-		[/^File: ([^\r\n]+)$/mu, "read"],
-	];
-	for (const [pattern, kind] of patterns) {
+	for (const [pattern, kind] of receiptPatterns) {
 		const rawPath = pattern.exec(text)?.[1];
 		if (rawPath !== undefined) {
 			return { kind, rawPath };
@@ -193,9 +204,7 @@ function learnNotesDirs(
 	const dirs = new Set<string>();
 	for (const info of results.values()) {
 		const match =
-			!info.isError && info.toolName === "notes"
-				? /^Notes directory: ([^\r\n]+)$/mu.exec(info.text)?.[1]
-				: undefined;
+			!info.isError && info.toolName === "notes" ? notesDirectoryOf(info.text) : undefined;
 		if (match !== undefined) {
 			dirs.add(match.trim().replaceAll("\\", "/").replace(/\/+$/u, ""));
 		}

package/src/recovery.ts

@@ -1,4 +1,9 @@
-import { AUTO_HANDOFF_PREFIX, type EntryLike, type ProjectedEntry } from "./contracts.ts";
+import {
+	AUTO_HANDOFF_PREFIX,
+	RETAINED_MARKER_PREFIX,
+	type EntryLike,
+	type ProjectedEntry,
+} from "./contracts.ts";
 import { contextStart, windowHandoff } from "./boundary.ts";
 import { contextEdits } from "./history-entries.ts";
 import { boundedBlock, excerpt } from "./message-text.ts";
@@ -23,8 +28,6 @@ const MAX_RECOVERY_RESULT_CHARS = 1_500;
 const HANDOFF_OVERHEAD_RESERVE = 1_000;
 const MAX_NOTES_SECTION_CHARS = 1_200;
 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 RETAINED_MARKER_PREFIX = "Context rolled over after entry ";
-
 export function hasRetainedRolloverMarker(summary: string): boolean {
 	return (
 		summary.startsWith(AUTO_HANDOFF_PREFIX) && summary.includes(`\n${RETAINED_MARKER_PREFIX}`)

package/src/reminders.ts

@@ -1,8 +1,10 @@
 import type { ExtensionContext, TurnEndEvent } from "@earendil-works/pi-coding-agent";
 import { budgetFor, type Budget } from "./budget.ts";
 import {
+	LEGACY_WINDOW_TYPE,
 	isRecord,
 	isReminderType,
+	type MessageLike,
 	type EntryLike,
 	type PolicyContext,
 	type ProjectedEntry,
@@ -58,7 +60,7 @@ function contextMarker(messages: readonly ContextMessage[]): {
 	readonly present: boolean;
 	readonly windowId: unknown;
 } {
-	const marker = messages.find((message) => message.customType === "context-window");
+	const marker = messages.find((message) => message.customType === LEGACY_WINDOW_TYPE);
 	if (marker === undefined) {
 		return { present: false, windowId: undefined };
 	}
@@ -235,12 +237,12 @@ export function createReminderLookup(): ReminderLookup {
 	return { reset: cache.reset, read: cache.read };
 }
 
-function countRetainedFromProjected(
+function retainedProjectedMessages(
 	projected: readonly ProjectedEntry[],
 	retainedIds: ReadonlySet<string>,
 	stale: StaleReminderPredicate,
-): number {
-	let count = 0;
+): MessageLike[] {
+	const retained: MessageLike[] = [];
 	for (const item of projected) {
 		if (!retainedIds.has(item.sourceEntry.id ?? "")) {
 			continue;
@@ -249,11 +251,11 @@ function countRetainedFromProjected(
 			if (
 				!stale({ role: msg.role ?? "", customType: msg.customType, details: msg.details })
 			) {
-				count += 1;
+				retained.push(msg);
 			}
 		}
 	}
-	return count;
+	return retained;
 }
 
 function entryProducesRetainedMessage(
@@ -284,7 +286,7 @@ export function countRetainedMessages(
 	}
 	const projection = sessionProjection(ctx.sessionManager);
 	if (projection !== undefined) {
-		return countRetainedFromProjected(projection, retainedIds, stale);
+		return retainedProjectedMessages(projection, retainedIds, stale).length;
 	}
 	const edits = contextEdits(branch);
 	return branch.filter(
@@ -292,3 +294,24 @@ export function countRetainedMessages(
 			retainedIds.has(entry.id ?? "") && entryProducesRetainedMessage(entry, edits, stale),
 	).length;
 }
+
+/**
+ * The retained tail's messages, in journal order, as the session projection carries them.
+ * Stale reminders leave the list exactly as the provider filter removes them. Undefined when
+ * the journal names no tail or the host has no session projection, so callers cannot certify
+ * the tail by identity and must count positions instead.
+ */
+export function retainedTailMessages(
+	ctx: ExtensionContext,
+	stale: StaleReminderPredicate,
+): readonly MessageLike[] | undefined {
+	const branch = sessionBranch(ctx.sessionManager) ?? [];
+	const retainedIds = journalRetainedIds(branch);
+	if (retainedIds === undefined) {
+		return undefined;
+	}
+	const projection = sessionProjection(ctx.sessionManager);
+	return projection === undefined
+		? undefined
+		: retainedProjectedMessages(projection, retainedIds, stale);
+}

package/src/retained-tail.ts

@@ -1,4 +1,4 @@
-import type { EntryLike } from "./contracts.ts";
+import type { EntryLike, MessageLike } from "./contracts.ts";
 
 /**
  * What a rollover retains: where Pi keeps the tail, which entries it holds, and how it must start.
@@ -54,3 +54,87 @@ export function retainedSpan(
 	const lastId = list.at(-1)?.id?.slice(0, 120);
 	return firstId === undefined || lastId === undefined ? undefined : { firstId, lastId };
 }
+
+/**
+ * Where the retained tail ends in a provider message list: the position after the last message
+ * that matches the journal's next retained message, in order. Opaque system presentations of
+ * custom messages must preserve their journal timestamp and order. Other interleaved messages
+ * are skipped. Returns undefined when the whole tail cannot be matched.
+ */
+export function retainedTailEnd(
+	messages: readonly MessageLike[],
+	summaryIndex: number,
+	retained: readonly MessageLike[],
+): number | undefined {
+	if (retained.length === 0) {
+		return summaryIndex + 1;
+	}
+	let expected = 0;
+	let end: number | undefined;
+	for (
+		let index = summaryIndex + 1;
+		index < messages.length && expected < retained.length;
+		index++
+	) {
+		const message = messages.at(index);
+		const journal = retained.at(expected);
+		if (message === undefined || journal === undefined) {
+			break;
+		}
+		if (sameRetainedMessage(journal, message) || isOpaquePresentation(journal, message)) {
+			expected += 1;
+			end = index + 1;
+		}
+	}
+	return expected === retained.length ? end : undefined;
+}
+
+/**
+ * Presenters such as pi-change-working-dir replace a custom message's content and details with
+ * system sections but preserve its timestamp. Timestamp/order correlation is their integration
+ * contract, not a globally unique message ID. A system message without that timestamp is not
+ * evidence that the expected custom message survived.
+ */
+function isOpaquePresentation(journal: MessageLike, event: MessageLike): boolean {
+	return (
+		event.role === "system" &&
+		event.content === "" &&
+		event.sections !== undefined &&
+		journal.role === "custom" &&
+		journal.timestamp !== undefined &&
+		event.timestamp === journal.timestamp
+	);
+}
+
+/**
+ * Identity of a retained message as the provider context carries it: same payload and receipt
+ * linkage, and a role an earlier handler may only present as `system`. Journal and
+ * provider messages are clones of each other, so identity is structural, never object equality.
+ */
+export function sameRetainedMessage(journal: MessageLike, event: MessageLike): boolean {
+	return (
+		(event.role === "system" || journal.role === event.role) &&
+		messageIdentity(journal) === messageIdentity(event)
+	);
+}
+
+function messageIdentity(message: MessageLike): string {
+	// Array serialization normalizes absent optional fields to null on both clones.
+	return JSON.stringify([
+		message.timestamp,
+		message.customType,
+		message.content,
+		message.details,
+		message.toolCallId,
+		message.toolName,
+		message.namespace,
+		message.isError,
+		message.summary,
+		message.command,
+		message.output,
+		message.stopReason,
+		message.errorMessage,
+		message.nestedCalls,
+		message.excludeFromContext,
+	]);
+}

package/src/rollover.ts

@@ -9,7 +9,11 @@ import type {
 import { activeBoundaryIndex } from "./boundary.ts";
 import { budgetFor, freshPayloadChars } from "./budget.ts";
 import {
+	BOUNDARY_TYPE,
 	REMINDER_TYPE,
+	RESET_DEFERRED_TYPE,
+	RETAINED_TAIL_TYPE,
+	posthorseDetails,
 	type PolicyContext,
 	type ProjectedEntry,
 	type SnapshotReader,
@@ -36,10 +40,12 @@ import {
 	countRetainedMessages,
 	createReminderLookup,
 	reminderDecision,
+	retainedTailMessages,
 	staleReminderPredicate,
 	type ReminderLookup,
 	type StaleReminderPredicate,
 } from "./reminders.ts";
+import { retainedTailEnd } from "./retained-tail.ts";
 
 function explicitReset(
 	event: TurnEndEvent,
@@ -53,7 +59,7 @@ function explicitReset(
 				...event.entries,
 				{
 					type: "custom_message",
-					customType: "posthorse-reset-deferred",
+					customType: RESET_DEFERRED_TYPE,
 					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.",
@@ -68,7 +74,7 @@ function explicitReset(
 				type: "compaction",
 				summary,
 				firstKeptEntryId: null,
-				details: { posthorse: 1, reason: "explicit" },
+				details: posthorseDetails("explicit"),
 			},
 		],
 		continue: true,
@@ -83,11 +89,11 @@ function chronologicalRetainedTail(
 	const first = messages[summaryIndex];
 	if (first?.role === "compactionSummary" && hasRetainedRolloverMarker(first.summary)) {
 		// Pi projects no system messages into the retained tail, but an earlier handler can
-		// present a retained message as one (pi-change-working-dir's directory snapshots).
-		// Count positions, not roles, so the record never lands inside the next tool batch.
-		const count = countRetainedMessages(ctx, stale);
-		const end = summaryIndex + 1 + count;
-		if (count > 0 && end <= messages.length) {
+		// present a retained message as one (pi-change-working-dir's directory snapshots) or
+		// interleave a new message. Match the projected journal tail before reordering it;
+		// count positions only on a host without a projection.
+		const { count, end } = retainedTailSliceEnd(messages, summaryIndex, ctx, stale);
+		if (count > 0 && end !== undefined) {
 			const prefix = messages.slice(0, summaryIndex);
 			const retainedSlice = messages.slice(summaryIndex + 1, end);
 			const afterSlice = messages.slice(end);
@@ -98,7 +104,7 @@ function chronologicalRetainedTail(
 				...prefix,
 				{
 					role: "custom",
-					customType: "posthorse-retained-tail",
+					customType: RETAINED_TAIL_TYPE,
 					content: "[Retained pre-rollover tail]",
 					display: false,
 					timestamp: first.timestamp,
@@ -111,6 +117,27 @@ function chronologicalRetainedTail(
 	}
 	return messages;
 }
+
+/** An unmatched projection must not silently become a positional match. */
+function retainedTailSliceEnd(
+	messages: ContextWithSystemEvent["messages"],
+	summaryIndex: number,
+	ctx: ExtensionContext,
+	stale: StaleReminderPredicate,
+): { readonly count: number; readonly end: number | undefined } {
+	const retained = retainedTailMessages(ctx, stale);
+	const count = retained?.length ?? countRetainedMessages(ctx, stale);
+	if (count === 0) {
+		return { count, end: undefined };
+	}
+	let end: number | undefined;
+	if (retained !== undefined) {
+		end = retainedTailEnd(messages, summaryIndex, retained);
+	} else if (summaryIndex + 1 + count <= messages.length) {
+		end = summaryIndex + 1 + count;
+	}
+	return { count, end };
+}
 function registerReminderFilter(
 	pi: ExtensionAPI,
 	policy: SnapshotReader,
@@ -149,7 +176,9 @@ function automaticDraft(
 	let firstKeptEntryId = recovery.firstKeptEntryId;
 	if (firstKeptEntryId === undefined) {
 		// Public compaction requires an entry id even when no prior conversation safely fits.
-		pi.appendEntry("posthorse-boundary", {});
+		// A compaction cancelled after this append leaves an inert marker: no reader matches
+		// BOUNDARY_TYPE; the compaction entry itself is the boundary recovery classifies.
+		pi.appendEntry(BOUNDARY_TYPE, {});
 		firstKeptEntryId = ctx.sessionManager.getLeafId() ?? undefined;
 	}
 	if (firstKeptEntryId === undefined || firstKeptEntryId === "") {
@@ -160,7 +189,7 @@ function automaticDraft(
 			summary: recovery.handoff,
 			firstKeptEntryId,
 			tokensBefore: recovery.tokensBefore,
-			details: { posthorse: 1, reason: recovery.reason },
+			details: posthorseDetails(recovery.reason),
 			...providerSummaryField(recovery.providerSummary),
 		},
 	};
@@ -263,7 +292,7 @@ function thresholdFallback(
 					type: "compaction",
 					summary: recovery.handoff,
 					firstKeptEntryId: recovery.firstKeptEntryId ?? null,
-					details: { posthorse: 1, reason: "threshold" },
+					details: posthorseDetails("threshold"),
 					...providerSummaryField(recovery.providerSummary),
 				},
 			],

package/src/session-lines.ts

@@ -11,6 +11,7 @@ export type LineMatcher = {
 export type SessionLine = {
 	readonly head: string;
 	readonly matches: boolean;
+	/** Read while the owning iterator is open; advancing alone does not close its handle. */
 	readonly text: () => Promise<string>;
 };
 type LineRange = {

package/ui.ts

@@ -7,6 +7,7 @@ import {
 	type Text,
 } from "@earendil-works/pi-tui";
 import { clean, hint, leadingRows, textBlock, textOf } from "./src/ui/text.ts";
+import { LEGACY_WINDOW_TYPE, REMINDER_TYPE } from "./src/contracts.ts";
 
 export type { PosthorseDisplay } from "./src/ui/display.ts";
 export { toolCards } from "./src/ui/cards.ts";
@@ -26,7 +27,7 @@ export function registerPosthorseMessages(pi: ExtensionAPI): void {
 			states.set(message, state);
 		}
 		const view = state;
-		const window = message.customType === "context-window";
+		const window = message.customType === LEGACY_WINDOW_TYPE;
 		const raw = textOf(message.content);
 		const handoffLabel = "\n\nHandoff from the previous window:\n";
 		const handoffAt = raw.indexOf(handoffLabel);
@@ -79,7 +80,7 @@ export function registerPosthorseMessages(pi: ExtensionAPI): void {
 			return { handled: true };
 		});
 	};
-	for (const type of ["context-window", "posthorse-reminder"]) {
+	for (const type of [LEGACY_WINDOW_TYPE, REMINDER_TYPE]) {
 		pi.registerMessageRenderer(type, renderer);
 	}
 }