pi-posthorse 0.10.24 → 0.10.26

package/index.ts

@@ -14,6 +14,7 @@ import { policySnapshot } from "./src/budget.ts";
 import type { CompactionPolicy, PolicyReader } from "./src/contracts.ts";
 import { createWindowGuidance } from "./src/guidance.ts";
 import { registerHistory } from "./src/history.ts";
+import { toolFacts } from "./src/host.ts";
 import { safeJsonStringify } from "./src/message-text.ts";
 import { registerNotes } from "./src/notes.ts";
 import { createNotesStore } from "./src/note-store.ts";
@@ -22,9 +23,8 @@ 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()
+	const { active, tools } = toolFacts(pi);
+	return tools
 		.filter((tool) => active.has(tool.name))
 		.reduce(
 			(total, tool) =>

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-posthorse",
-	"version": "0.10.24",
+	"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

@@ -0,0 +1,101 @@
+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. */
+export type Boundary = {
+	readonly kind: BoundaryKind;
+	/** Counts as a Posthorse window: labels, reminder windows, and note provenance. */
+	readonly window: boolean;
+	/** An automatic recovery record that walks through earlier windows continue past. */
+	readonly chainsAncestry: boolean;
+	/** Starts a new guidance epoch; a provider summary block keeps the previous one. */
+	readonly freshGuidance: boolean;
+};
+
+export function windowHandoff(entry: EntryLike | undefined): string | undefined {
+	return entry?.type === "compaction" ? entry.summary : entry?.handoff;
+}
+/** An automatic recovery record opens with this prefix; an earlier window's walk may continue past it. */
+function automaticHandoff(entry: EntryLike): boolean {
+	return windowHandoff(entry)?.trim().startsWith(AUTO_HANDOFF_PREFIX) === true;
+}
+/**
+ * A compaction with a provider summary block carries forward the previous window's leading system
+ * message unchanged, so its guidance section must stay locked to that earlier epoch too.
+ */
+function providerSummaryBlock(entry: EntryLike): boolean {
+	return (
+		entry.type === "compaction" &&
+		isRecord(entry.providerSummary) &&
+		isRecord(entry.providerSummary.block)
+	);
+}
+function compactionKind(details: Readonly<Record<string, unknown>>): BoundaryKind {
+	if (details.reason === "threshold" || details.reason === "overflow") {
+		return "automatic";
+	}
+	return details.reason === "explicit" ? "explicit" : "posthorse";
+}
+export function classifyBoundary(entry?: EntryLike): Boundary | undefined {
+	if (entry?.type === "context_window") {
+		return {
+			kind: "fork",
+			window: true,
+			chainsAncestry: automaticHandoff(entry),
+			freshGuidance: true,
+		};
+	}
+	if (entry?.type !== "compaction") {
+		return undefined;
+	}
+	const details = isRecord(entry.details) ? entry.details : undefined;
+	const freshGuidance = !providerSummaryBlock(entry);
+	if (details?.posthorse !== POSTHORSE_COMPACTION) {
+		return { kind: "native", window: false, chainsAncestry: false, freshGuidance };
+	}
+	const kind = compactionKind(details);
+	return {
+		kind,
+		window: true,
+		chainsAncestry: kind === "automatic" && automaticHandoff(entry),
+		freshGuidance,
+	};
+}
+export function isWindow(entry: EntryLike): boolean {
+	return classifyBoundary(entry)?.window === true;
+}
+export function startsFreshGuidanceEpoch(entry: EntryLike): boolean {
+	return classifyBoundary(entry)?.freshGuidance === true;
+}
+export function chainsAncestry(entry?: EntryLike): boolean {
+	return classifyBoundary(entry)?.chainsAncestry === true;
+}
+/** The boundary already applied to a projection: a compaction with a visible tail. -1 when none. */
+export function activeBoundaryIndex(projected: readonly ProjectedEntry[]): number {
+	return projected.findIndex(
+		(entry) => entry.sourceEntry.type === "compaction" && entry.messages.length > 0,
+	);
+}
+/** First active branch entry, including tails retained by Pi's own /compact. */
+export 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 };
+}

package/src/budget.ts

@@ -24,11 +24,18 @@ export const ALL_GUIDANCE_TOOLS: GuidanceTools = {
 export type Budget = {
 	readonly contextWindow: number;
 	readonly reserveTokens: number;
-	readonly enabled: boolean;
+	/** One classification of how Posthorse may use this capacity. */
+	readonly state: BudgetState;
 	readonly usable: number;
 	readonly rolloverAt: number;
-	readonly supported: boolean;
 };
+export type BudgetState = "disabled" | "unsupported" | "enabled";
+function budgetState(enabled: boolean, usable: number): BudgetState {
+	if (!enabled) {
+		return "disabled";
+	}
+	return usable >= MIN_USABLE_TOKENS ? "enabled" : "unsupported";
+}
 /** A synchronous evaluation owns one snapshot; never carry it across an await. */
 export function policySnapshot(
 	ctx: ExtensionContext,
@@ -73,10 +80,9 @@ export function budgetFor(
 	return {
 		contextWindow,
 		reserveTokens,
-		enabled,
+		state: budgetState(enabled, usable),
 		usable,
 		rolloverAt: usable + 1,
-		supported: !enabled || usable >= MIN_USABLE_TOKENS,
 	};
 }
 export function budgetGuidanceKey(ctx: PolicyContext): string {
@@ -84,9 +90,9 @@ export function budgetGuidanceKey(ctx: PolicyContext): string {
 	if (budget === undefined) {
 		return ctx.getCompactionSettings().enabled ? "1:unknown" : "0:unknown";
 	}
-	return budget.enabled
-		? `1:${budget.contextWindow}:${budget.reserveTokens}`
-		: `0:${budget.contextWindow}`;
+	return budget.state === "disabled"
+		? `0:${budget.contextWindow}`
+		: `1:${budget.contextWindow}:${budget.reserveTokens}`;
 }
 export function unsupportedMessage(budget: Budget, newContextAvailable = true): string {
 	const n = (value: number) => value.toLocaleString("en-US");
@@ -104,7 +110,7 @@ function automaticGuidance(
 		const reset = tools.newContext ? " new_context remains available." : "";
 		return `Pi compaction is disabled in the available settings, so Posthorse sends no checkpoint reminder.${reset}`;
 	}
-	if (budget !== undefined && !budget.supported) {
+	if (budget?.state === "unsupported") {
 		return unsupportedMessage(budget, tools.newContext);
 	}
 	const line =
@@ -120,7 +126,8 @@ export function buildGuidance(
 	tools: GuidanceTools = ALL_GUIDANCE_TOOLS,
 ): string {
 	const budget = budgetFor(ctx);
-	const enabled = budget?.enabled ?? ctx.getCompactionSettings().enabled;
+	const enabled =
+		budget === undefined ? ctx.getCompactionSettings().enabled : budget.state !== "disabled";
 	const capacity =
 		budget === undefined
 			? "Configured context capacity is unknown."
@@ -148,20 +155,29 @@ function guidanceTokenCount(guidance: string): number {
 export function guidanceTokens(ctx: PolicyContext): number {
 	return guidanceTokenCount(guidanceFor(ctx));
 }
+/**
+ * Which guidance the reservation subtracts: the text rebuilt for the next request, or the host's
+ * effective text that is already in the prompt.
+ */
+export type GuidanceReservation = "rebuild" | "effective";
 /** Half the fresh capacity after prompt/tool/input overhead remains for continued work. */
 export function freshPayloadChars(
 	ctx: PolicyContext,
 	toolTokens: number,
-	pendingMessages: readonly MessageLike[] = [],
-	cap = MAX_HANDOFF_CHARS,
+	options: {
+		readonly pendingMessages?: readonly MessageLike[] | undefined;
+		readonly cap?: number | undefined;
+		readonly guidance?: GuidanceReservation | undefined;
+	} = {},
 ): number {
+	const { pendingMessages = [], cap = MAX_HANDOFF_CHARS, guidance = "rebuild" } = options;
 	const budget = budgetFor(ctx);
 	if (budget === undefined) {
 		return cap;
 	}
-	const line = budget.enabled && budget.supported ? budget.rolloverAt : budget.contextWindow;
+	const line = budget.state === "enabled" ? budget.rolloverAt : budget.contextWindow;
 	const reservedGuidance =
-		cap === MAX_HANDOFF_CHARS ? guidanceTokenCount(buildGuidance(ctx)) : guidanceTokens(ctx);
+		guidance === "rebuild" ? guidanceTokenCount(buildGuidance(ctx)) : guidanceTokens(ctx);
 	const promptTokens = Math.ceil(ctx.getSystemPrompt().length / 4) + reservedGuidance;
 	const pendingTokens = pendingMessages.reduce(
 		(total, message) =>
@@ -181,10 +197,13 @@ export function freshPayloadChars(
 export function pageCapacity(ctx: PolicyContext, toolTokens: () => number): number {
 	const usage = ctx.getContextUsage();
 	if (usage === undefined || usage.tokens === null) {
-		return freshPayloadChars(ctx, toolTokens(), [], MAX_PAGE_CHARS) / 4 + PAGE_MARGIN_TOKENS;
+		return (
+			freshPayloadChars(ctx, toolTokens(), { cap: MAX_PAGE_CHARS, guidance: "effective" }) /
+				4 +
+			PAGE_MARGIN_TOKENS
+		);
 	}
 	const budget = budgetFor(ctx, usage.contextWindow);
-	const line =
-		budget?.enabled === true && budget.supported ? budget.rolloverAt : usage.contextWindow;
+	const line = budget?.state === "enabled" ? budget.rolloverAt : usage.contextWindow;
 	return line - usage.tokens - guidanceTokens(ctx);
 }

package/src/context-tools.ts

@@ -12,10 +12,7 @@ import {
 } from "./contracts.ts";
 
 function rolloverStatus(budget: Budget | undefined): "disabled" | "enabled" | "unsupported" {
-	if (budget?.enabled !== true) {
-		return "disabled";
-	}
-	return budget.supported ? "enabled" : "unsupported";
+	return budget?.state ?? "disabled";
 }
 function contextReport(host: PolicyContext, newContextAvailable: boolean): TextResult {
 	const usage = host.getContextUsage();
@@ -34,14 +31,14 @@ function contextReport(host: PolicyContext, newContextAvailable: boolean): TextR
 		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.`;
-	if (budget?.enabled !== true) {
+	if (budget === undefined || budget.state === "disabled") {
 		return textResult(
 			`Automatic rollover is disabled in the available settings (Pi compaction.enabled=false). ${configured}`,
 			[],
 			display,
 		);
 	}
-	if (!budget.supported) {
+	if (budget.state === "unsupported") {
 		return textResult(
 			`${unsupportedMessage(budget, newContextAvailable)} ${configured}`,
 			[],

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,12 +114,58 @@ 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;
 }
 export function optionalString(value: unknown): string | undefined {
 	return typeof value === "string" ? value : undefined;
 }
+/** Some models send every optional argument; an empty string means the argument was omitted. */
+export function presentText(value: unknown): string | undefined {
+	return typeof value === "string" && value !== "" ? value : undefined;
+}
 export function requireValue(value: string | undefined, name: string, op: string): string {
 	if (value === undefined || value === "") {
 		throw new Error(`"${name}" is required for op "${op}".`);

package/src/epoch-cache.ts

@@ -0,0 +1,50 @@
+import { sessionIdentity, type SessionHost, type SessionIdentity } from "./host.ts";
+
+/** A cached value with the session state it was computed from. */
+export type EpochValue<Value> = {
+	readonly identity: SessionIdentity;
+	readonly value: Value;
+};
+export type EpochCache<Value> = {
+	readonly read: (ctx: SessionContext) => Value;
+	readonly reset: () => void;
+};
+export type SessionContext = { readonly sessionManager: SessionHost };
+
+function sameSession(left: SessionIdentity, right: SessionIdentity): boolean {
+	return left.sessionId === right.sessionId && left.file === right.file;
+}
+/**
+ * Caches one session fact for the current leaf. A new leaf recomputes unless its walk reaches the
+ * cached leaf entry itself: entry identity, not a reusable id, certifies an append-only extension.
+ */
+export function createEpochCache<Value>(
+	compute: (
+		ctx: SessionContext,
+		identity: SessionIdentity,
+		previous: EpochValue<Value> | undefined,
+	) => Value,
+): EpochCache<Value> {
+	let cached: (EpochValue<Value> & { readonly manager: object }) | undefined;
+	return {
+		reset: () => {
+			cached = undefined;
+		},
+		read: (ctx) => {
+			const manager: object = ctx.sessionManager;
+			const identity = sessionIdentity(ctx.sessionManager);
+			const previous =
+				cached !== undefined &&
+				cached.manager === manager &&
+				sameSession(cached.identity, identity)
+					? cached
+					: undefined;
+			if (previous !== undefined && previous.identity.leaf === identity.leaf) {
+				return previous.value;
+			}
+			const value = compute(ctx, identity, previous);
+			cached = { manager, identity, value };
+			return value;
+		},
+	};
+}

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 {
@@ -7,7 +7,16 @@ import {
 	buildGuidance,
 	type GuidanceTools,
 } from "./budget.ts";
-import { isRecord, type EntryLike, type PolicyContext, type SnapshotReader } from "./contracts.ts";
+import type { EntryLike, PolicyContext, SnapshotReader } from "./contracts.ts";
+import { startsFreshGuidanceEpoch } from "./boundary.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({
@@ -24,74 +33,25 @@ type MemoryEpoch = {
 	readonly byBudget: Map<string, string>;
 	tools: GuidanceTools | undefined;
 };
-type EpochState = {
-	readonly manager: ExtensionContext["sessionManager"];
-	readonly sessionId: string;
-	readonly file: string | undefined;
-	readonly leaf: EntryLike | undefined;
+type GuidanceEpoch = {
 	readonly anchorKey: string;
 	readonly byBudget: ReadonlyMap<string, string>;
 	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 {
-	const active = new Set(pi.getActiveTools());
-	const unnamespaced = new Set(
-		pi
-			.getAllTools()
-			.filter((tool) => tool.namespace === undefined)
-			.map((tool) => tool.name),
-	);
+export function activeGuidanceTools(pi: ToolRegistry): GuidanceTools {
+	const { activeUnnamespaced } = toolFacts(pi);
 	return {
-		newContext: active.has("new_context") && unnamespaced.has("new_context"),
-		getContextRemaining:
-			active.has("get_context_remaining") && unnamespaced.has("get_context_remaining"),
+		newContext: activeUnnamespaced.has("new_context"),
+		getContextRemaining: activeUnnamespaced.has("get_context_remaining"),
 	};
 }
-/**
- * A compaction with a provider summary block carries forward the previous window's leading system
- * message unchanged, so its guidance section must stay locked to that earlier epoch too.
- */
-function startsFreshGuidanceEpoch(entry: EntryLike): boolean {
-	if (entry.type === "context_window") {
-		return true;
-	}
-	return (
-		entry.type === "compaction" &&
-		!(isRecord(entry.providerSummary) && isRecord(entry.providerSummary.block))
-	);
-}
-function parentEntry(
-	manager: ExtensionContext["sessionManager"],
-	id: string | null | undefined,
-): EntryLike | undefined {
-	const raw: unknown = manager;
-	if (id === undefined || id === null || id === "" || !isRecord(raw)) {
-		return undefined;
-	}
-	return typeof raw.getEntry === "function" ? manager.getEntry(id) : undefined;
-}
-function sessionIdentityOf(manager: ExtensionContext["sessionManager"]): {
-	readonly sessionId: string;
-	readonly file: string | undefined;
-	readonly leaf: EntryLike | undefined;
-} {
-	const raw: unknown = manager;
-	const sessionId =
-		isRecord(raw) && typeof raw.getSessionId === "function" ? manager.getSessionId() : "";
-	const file =
-		isRecord(raw) && typeof raw.getSessionFile === "function"
-			? manager.getSessionFile()
-			: undefined;
-	const leafId =
-		isRecord(raw) && typeof raw.getLeafId === "function" ? manager.getLeafId() : null;
-	return { sessionId, file, leaf: parentEntry(manager, leafId) };
-}
 function collectGuidanceEntries(
 	entries: readonly EntryLike[],
 	baseByBudget?: ReadonlyMap<string, string>,
@@ -130,27 +90,27 @@ function withMemoryEpoch(
 	return { byBudget: merged, tools: collected.tools ?? memory.tools };
 }
 function scanGuidanceEpoch(
-	manager: ExtensionContext["sessionManager"],
-	identity: { readonly sessionId: string; readonly leaf: EntryLike | undefined },
-	previous: EpochState | undefined,
+	manager: SessionHost,
+	identity: SessionIdentity,
+	previous: EpochValue<GuidanceEpoch> | undefined,
 	memoryByEpoch: ReadonlyMap<string, MemoryEpoch> | undefined,
-): Pick<EpochState, "anchorKey" | "byBudget" | "tools"> {
+): GuidanceEpoch {
 	const reversed: EntryLike[] = [];
 	let anchor: EntryLike | undefined;
 	for (
 		let entry = identity.leaf;
 		entry !== undefined;
-		entry = parentEntry(manager, entry.parentId)
+		entry = sessionEntry(manager, entry.parentId)
 	) {
-		if (previous !== undefined && previous.leaf === entry) {
+		if (previous !== undefined && previous.identity.leaf === entry) {
 			const collected = collectGuidanceEntries(
 				reversed.reverse(),
-				previous.byBudget,
-				previous.tools,
+				previous.value.byBudget,
+				previous.value.tools,
 			);
 			return {
-				anchorKey: previous.anchorKey,
-				...withMemoryEpoch(collected, memoryByEpoch?.get(previous.anchorKey)),
+				anchorKey: previous.value.anchorKey,
+				...withMemoryEpoch(collected, memoryByEpoch?.get(previous.value.anchorKey)),
 			};
 		}
 		if (startsFreshGuidanceEpoch(entry)) {
@@ -169,43 +129,55 @@ function scanGuidanceEpoch(
 		...withMemoryEpoch(collected, memoryByEpoch?.get(anchorKey)),
 	};
 }
-export function createWindowGuidance(pi: ExtensionAPI): WindowGuidance {
-	let state: EpochState | undefined;
+/** 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 readEpoch = (ctx: ExtensionContext): EpochState => {
-		const manager = ctx.sessionManager;
-		const { sessionId, file, leaf } = sessionIdentityOf(manager);
-		const previous =
-			state?.manager === manager && state.sessionId === sessionId && state.file === file
-				? state
-				: undefined;
-		if (previous !== undefined && previous.leaf === leaf) {
-			return previous;
+	const epochs = createEpochCache<GuidanceEpoch>((ctx, identity, previous) =>
+		scanGuidanceEpoch(
+			ctx.sessionManager,
+			identity,
+			previous,
+			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);
+			}
 		}
-		state = {
-			manager,
-			sessionId,
-			file,
-			leaf,
-			...scanGuidanceEpoch(
-				manager,
-				{ sessionId, leaf },
-				previous,
-				memoryByManager.get(manager),
-			),
-		};
-		return state;
 	};
 	return {
 		resolve(ctx, host) {
-			const epoch = readEpoch(ctx);
+			const epoch = epochs.read(ctx);
 			const key = budgetGuidanceKey(host);
 			return (
 				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 = readEpoch(ctx);
+			const epoch = epochs.read(ctx);
+			pruneRetiredEpochs(ctx.sessionManager, epoch.anchorKey);
 			const key = budgetGuidanceKey(host);
 			const existing = epoch.byBudget.get(key);
 			if (existing !== undefined) {
@@ -225,7 +197,7 @@ export function createWindowGuidance(pi: ExtensionAPI): WindowGuidance {
 			}
 			memory.byBudget.set(key, text);
 			memory.tools ??= tools;
-			state = undefined;
+			epochs.reset();
 			pi.appendEntry(WINDOW_GUIDANCE_TYPE, {
 				version: 1,
 				budgetKey: key,
@@ -235,13 +207,13 @@ export function createWindowGuidance(pi: ExtensionAPI): WindowGuidance {
 			return text;
 		},
 		reset() {
-			state = undefined;
+			epochs.reset();
 			memoryByManager = new WeakMap();
 		},
 	};
 }
 export function registerGuidance(
-	pi: ExtensionAPI,
+	pi: Pick<ExtensionAPI, "on">,
 	policy: SnapshotReader,
 	windowGuidance: WindowGuidance,
 ): void {
@@ -249,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;