pi-posthorse 0.5.0 → 0.7.0

package/index.ts

@@ -1,16 +1,16 @@
 /**
  * Posthorse — fresh context, same journey.
  *
- * Native no-summary context windows for the fitchmultz/pi fork. Pi owns the persisted
- * boundary. Posthorse owns the policy: sparse budget reminders, rollover tools, durable
- * notes, and history recovery.
+ * No-summary context rollover for Pi. On the fitchmultz/pi fork, Pi persists native context
+ * windows; on official Pi, rollover is a retain-none compaction whose summary is the handoff.
+ * Pi owns the persisted boundary. Posthorse owns the policy: sparse budget reminders, rollover
+ * tools, durable notes, and history recovery.
  */
 
-import { createHash } from "node:crypto";
+import { execFile } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
 import {
 	appendFileSync,
-	constants,
-	copyFileSync,
 	createReadStream,
 	existsSync,
 	mkdirSync,
@@ -19,16 +19,20 @@ import {
 	realpathSync,
 	statSync,
 } from "node:fs";
+import { access, constants, lstat, open, readlink, realpath, rename, stat, unlink } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
-import * as codingAgent from "@earendil-works/pi-coding-agent";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { promisify } from "node:util";
+import { estimateTokens, formatSize, getAgentDir, SettingsManager, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { registerPosthorseMessages, toolCards, type PosthorseDisplay } from "./ui.ts";
 
 const REMINDER_BUFFER_TOKENS = 32_000;
-/** Absolute ceiling for handoffs and recovery pages; pages shrink to the live remaining budget. */
+/** Absolute ceilings; handoffs and pages shrink to the live remaining budget. */
 const MAX_HANDOFF_CHARS = 20_000;
+const MAX_PAGE_CHARS = 40_000;
 const MAX_RECOVERY_RECORD_CHARS = 4_000;
+const MAX_RECOVERY_RESULT_CHARS = 1_500;
 const HANDOFF_OVERHEAD_RESERVE = 1_000;
 const PAGE_MARGIN_TOKENS = 1_000;
 const MIN_PAGE_CHARS = 1_000;
@@ -36,45 +40,55 @@ const ESTIMATED_IMAGE_CHARS = 4_800;
 /** A window must hold the largest handoff (~5,000 tokens) plus equal working room below Pi's line. */
 const MIN_USABLE_TOKENS = Math.ceil(MAX_HANDOFF_CHARS / 4) * 2;
 const REMINDER_TYPE = "posthorse-reminder";
-/** Persisted by pi-headroom transcripts before the rename; still recognized everywhere. */
-const LEGACY_REMINDER_TYPE = "headroom-reminder";
 const AUTO_HANDOFF_PREFIX = "Automatic context rollover recovery record.";
-const LEGACY_AUTO_HANDOFF_PREFIX =
-	"Automatic context rollover. Continue the current task without asking the user to repeat it.";
+const EMPTY_HANDOFF = "Fresh context. Restore relevant notes and history before continuing.";
 
 type CompactionPolicy = { enabled: boolean; reserveTokens: number };
 type ContextUsage = { tokens: number | null; contextWindow: number; percent: number | null };
-/** Fork-only SDK export; the public npm declarations do not include it. */
-const { publishLocalFile } = codingAgent as typeof codingAgent & {
-	publishLocalFile(absolutePath: string, content: string | Uint8Array, signal?: AbortSignal): Promise<void>;
-};
 
-/** Fork-only ExtensionContext members; the published Pi types do not declare them. */
-type NativeContext = {
+/** The fork exposes live settings on the context; official Pi gets them from the injected policy. */
+type PolicyContext = {
 	model?: { contextWindow: number };
-	newContext(options?: { handoff?: string }): void;
 	getCompactionSettings(): CompactionPolicy;
 	getContextUsage(): ContextUsage | undefined;
 	getSystemPrompt(): string;
 };
 
+/** Fork-only extension API; the published Pi types do not declare it. */
 type NativeExtensionAPI = {
+	registerContextWindowHook(
+		handler: (
+			event: { contextEntries: ProjectedEntry[]; pendingMessages: MessageLike[] },
+			ctx: ExtensionContext,
+		) => ReceiptEdit[] | undefined,
+	): void;
 	on(
 		event: "session_before_auto_compact",
 		handler: (
-			event: { reason: "overflow" | "threshold"; branchEntries: EntryLike[]; pendingMessages?: MessageLike[] },
+			event: { reason: "overflow" | "threshold"; branchEntries: EntryLike[]; pendingMessages?: MessageLike[]; retainedToolResultIds: string[] },
 			ctx: unknown,
 		) => { newContext: { handoff?: string } } | undefined,
 	): void;
 };
 
 type ImageLike = { type: "image"; data: string; mimeType: string };
+type ToolCallLike = {
+	type?: string;
+	id?: string;
+	name?: string;
+	namespace?: string;
+	arguments?: unknown;
+	executionArguments?: unknown;
+	async?: boolean;
+};
 type MessageLike = {
 	role?: string;
 	stopReason?: string;
 	errorMessage?: string;
 	content?: unknown;
+	summary?: string;
 	toolName?: string;
+	namespace?: string;
 	toolCallId?: string;
 	isError?: boolean;
 	command?: string;
@@ -93,9 +107,14 @@ type EntryLike = {
 	details?: unknown;
 	display?: boolean;
 	handoff?: string;
+	firstKeptEntryId?: string;
+	targetId?: string;
+	replacement?: { content: unknown } | null;
 };
 
 type WindowedEntry = { entry: EntryLike; windowId: string; text: string; images: ImageLike[] };
+type ProjectedEntry = { sourceEntry: EntryLike; messages: MessageLike[] };
+type ReceiptEdit = { type: "context_edit"; targetId: string; replacement: { content: string } };
 type HistoryHit = { id: string; text: string; headerLength: number; priority: 0 | 1 };
 type RecoveryRecord = {
 	id: string;
@@ -105,6 +124,7 @@ type RecoveryRecord = {
 	text: string;
 };
 type ReminderFingerprint = { windowId: string; contextWindow?: number; reserveTokens?: number };
+type NoteFile = { path: string; size: number; mtimeMs: number };
 type Budget = {
 	contextWindow: number;
 	reserveTokens: number;
@@ -114,21 +134,92 @@ type Budget = {
 	supported: boolean;
 };
 
-function nativeContext<T>(ctx: T): T & NativeContext {
-	const candidate = ctx as T & Partial<NativeContext>;
-	if (
-		typeof candidate.newContext !== "function" ||
-		typeof candidate.getCompactionSettings !== "function" ||
-		typeof candidate.getSystemPrompt !== "function" ||
-		typeof publishLocalFile !== "function"
-	) {
-		throw new Error("Posthorse requires the fitchmultz/pi fork with native context windows and publishLocalFile (see README).");
+/** A fork context window, or the retain-none compaction Posthorse commits on official Pi. */
+function isWindow(entry: EntryLike): boolean {
+	return entry.type === "context_window" || (entry.type === "compaction" && (entry.details as { posthorse?: unknown } | undefined)?.posthorse === 1);
+}
+
+function windowHandoff(entry: EntryLike | undefined): string | undefined {
+	return entry?.type === "compaction" ? entry.summary : entry?.handoff;
+}
+
+/** First branch entry still in model context: after a fork window, or a compaction's kept tail (including Pi's own `/compact`). */
+function contextStart(entries: readonly EntryLike[]): { start: number; boundary?: EntryLike } {
+	for (let i = entries.length - 1; i >= 0; i--) {
+		const entry = entries[i];
+		if (entry.type === "context_window") return { start: i + 1, boundary: entry };
+		if (entry.type === "compaction") {
+			const kept = entries.findIndex((candidate) => candidate.id === entry.firstKeptEntryId);
+			return { start: kept >= 0 ? kept : i + 1, boundary: entry };
+		}
 	}
-	return candidate as T & NativeContext;
+	return { start: 0 };
 }
 
 function isReminderType(customType: unknown): boolean {
-	return customType === REMINDER_TYPE || customType === LEGACY_REMINDER_TYPE;
+	return customType === REMINDER_TYPE;
+}
+
+/** Resolve each link like the fork's publisher: never normalize away a path constraint. */
+async function resolveFileTarget(absolutePath: string): Promise<string> {
+	let target = absolutePath;
+	const links = new Set<string>();
+	for (;;) {
+		// A trailing separator requires an existing directory, never a new regular file.
+		if (target.endsWith(sep) || target.endsWith("/")) {
+			await stat(target);
+			return realpath(target);
+		}
+		const parentInput = dirname(target);
+		// realpath alone can accept regular-file/.. on macOS; stat checks traversal.
+		if (!(await stat(parentInput)).isDirectory()) {
+			throw Object.assign(new Error(`Not a directory: ${parentInput}`), { code: "ENOTDIR" });
+		}
+		const parent = await realpath(parentInput);
+		target = join(parent, basename(target));
+		const info = await lstat(target).catch((error: NodeJS.ErrnoException) => {
+			if (error.code !== "ENOENT") throw error;
+			return undefined;
+		});
+		if (!info) return target;
+		if (!info.isSymbolicLink()) return realpath(target);
+		if (links.has(target)) throw Object.assign(new Error(`Symlink cycle: ${absolutePath}`), { code: "ELOOP" });
+		links.add(target);
+		const link = await readlink(target);
+		// Preserve ".." until realpath has followed any preceding directory symlinks.
+		target = isAbsolute(link) ? link : `${parent}${sep}${link}`;
+	}
+}
+
+/** Same-directory replacement: a failure before rename leaves the previous note; mode/uid/gid are kept. */
+async function publishFile(path: string, content: string, signal?: AbortSignal): Promise<void> {
+	signal?.throwIfAborted();
+	const target = await resolveFileTarget(path);
+	const previous = await lstat(target).catch((error: NodeJS.ErrnoException) => {
+		if (error.code !== "ENOENT") throw error;
+		return undefined;
+	});
+	if (previous && !previous.isFile()) {
+		throw Object.assign(new Error(`Cannot publish to a non-regular file: ${target}`), { code: previous.isDirectory() ? "EISDIR" : "EINVAL", path: target });
+	}
+	if (previous) await access(target, constants.W_OK);
+	const temporary = join(dirname(target), `.posthorse-${randomUUID()}.tmp`);
+	const file = await open(temporary, "wx", previous ? 0o600 : 0o666);
+	try {
+		await file.writeFile(content, { signal });
+		if (previous) {
+			const staged = await file.stat();
+			if (staged.uid !== previous.uid || staged.gid !== previous.gid) await file.chown(previous.uid, previous.gid);
+			await file.chmod(previous.mode & 0o777);
+		}
+		await file.close();
+		signal?.throwIfAborted();
+		await rename(temporary, target);
+	} catch (error) {
+		await file.close().catch(() => {});
+		await unlink(temporary).catch(() => {});
+		throw error;
+	}
 }
 
 function isImage(part: unknown): part is ImageLike {
@@ -154,16 +245,26 @@ function safeJsonStringify(value: unknown): string {
 	}
 }
 
+function toolIdentity(name?: string, namespace?: string): string {
+	return `${name ?? "tool"}${namespace === undefined ? "" : ` (namespace: ${safeJsonStringify(namespace)})`}`;
+}
+
+function executionArgumentsText(call: ToolCallLike): string {
+	return call.executionArguments === undefined ? "" : `\nExecution arguments: ${safeJsonStringify(call.executionArguments)}`;
+}
+
 function textOf(message: MessageLike): string {
 	if (typeof message.content === "string") return message.content;
 	if (!Array.isArray(message.content)) return "";
 	return message.content
 		.map((part) => {
 			if (!part || typeof part !== "object") return "";
-			const block = part as { type?: string; text?: string; thinking?: string; name?: string; arguments?: unknown };
+			const block = part as ToolCallLike & { text?: string; thinking?: string };
 			if (block.type === "text") return block.text ?? "";
 			if (block.type === "thinking") return block.thinking ?? "";
-			if (block.type === "toolCall") return `${block.name ?? "tool"} ${safeJsonStringify(block.arguments ?? {})}`;
+			if (block.type === "toolCall") {
+				return `${toolIdentity(block.name, block.namespace)} ${safeJsonStringify(block.arguments ?? {})}${block.id === undefined ? "" : `\nCall ID: ${block.id}`}${executionArgumentsText(block)}`;
+			}
 			return "";
 		})
 		.filter(Boolean)
@@ -174,32 +275,11 @@ function textResult(text: string, images: ImageLike[] = [], display?: PosthorseD
 	return { content: [{ type: "text" as const, text }, ...images], details: display };
 }
 
-/** Import old checkout-local notes without overwriting shared notes, including concurrent writes. */
-function importLegacyNotes(source: string, target: string): void {
-	if (!existsSync(source)) return;
-	if (existsSync(target) && (!statSync(target).isDirectory() || realpathSync(source) === realpathSync(target))) return;
-	mkdirSync(target, { recursive: true });
-	for (const name of readdirSync(source)) {
-		const from = join(source, name);
-		const to = join(target, name);
-		if (statSync(from).isDirectory()) {
-			importLegacyNotes(from, to);
-		} else {
-			try {
-				copyFileSync(from, to, constants.COPYFILE_EXCL);
-			} catch (error) {
-				if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
-			}
-		}
-	}
-}
-
 /** Conventional repos use the main checkout; separate Git directories are their own shared root. */
 function notesRoot(cwd: string): string {
 	for (let dir = cwd; ; dir = dirname(dir)) {
 		const marker = join(dir, ".git");
 		if (existsSync(marker)) {
-			let root: string;
 			try {
 				let target = marker;
 				if (!statSync(marker).isDirectory()) {
@@ -210,13 +290,11 @@ function notesRoot(cwd: string): string {
 				target = realpathSync(target);
 				const commonFile = join(target, "commondir");
 				const common = realpathSync(existsSync(commonFile) ? resolve(target, readFileSync(commonFile, "utf8").trim()) : target);
-				root = basename(common) === ".git" ? dirname(common) : common;
+				return basename(common) === ".git" ? dirname(common) : common;
 			} catch {
 				// Orphaned/copied worktrees can outlive their Git metadata; local notes still work.
 				return dir;
 			}
-			if (root !== dir) importLegacyNotes(join(dir, ".pi", "notes"), join(root, ".pi", "notes"));
-			return root;
 		}
 		if (dirname(dir) === dir) return cwd;
 	}
@@ -247,7 +325,10 @@ function flattenEntry(entry: EntryLike): string | undefined {
 			if (message.excludeFromContext === true) return "[bashExecution] (excluded from model context by Pi)";
 			return `[bashExecution] $ ${message.command ?? ""}\n${message.output ?? ""}`;
 		}
-		return `[${message.role ?? "message"}] ${[textOf(message), assistantFailure(message), imageSummary(imagesOf(message.content))].filter(Boolean).join("\n")}`;
+		const resultIdentity = message.role === "toolResult"
+			? `Tool: ${toolIdentity(message.toolName, message.namespace)}${message.toolCallId === undefined ? "" : `\nCall ID: ${message.toolCallId}`}`
+			: "";
+		return `[${message.role ?? "message"}] ${[textOf(message), assistantFailure(message), imageSummary(imagesOf(message.content)), resultIdentity].filter(Boolean).join("\n")}`;
 	}
 	if (entry.type === "compaction" || entry.type === "branch_summary") {
 		return `[${entry.type}] ${entry.summary ?? ""}`;
@@ -258,6 +339,10 @@ function flattenEntry(entry: EntryLike): string | undefined {
 	if (entry.type === "context_window") {
 		return `[context_window] ${entry.handoff ? `Handoff: ${entry.handoff}` : "No handoff"}`;
 	}
+	if (entry.type === "context_edit" && entry.replacement) {
+		const content = entry.replacement.content;
+		return `[context_edit] ${[textOf({ content }), imageSummary(imagesOf(content))].filter(Boolean).join("\n")}`;
+	}
 	return undefined;
 }
 
@@ -270,6 +355,24 @@ function isRecoveryCall(part: unknown): boolean {
 	return block?.type === "toolCall" && isRecoveryTool(block.name);
 }
 
+/** Ten base64url characters of SHA-256; 0.6 file keys were the whole digest, which starts with these. */
+function shortKey(text: string): string {
+	return createHash("sha256").update(text).digest("base64url").slice(0, 10);
+}
+
+/** Nested session files are subagent runs, whose user-role input came from a parent agent. */
+function sourceTag(source: string): string {
+	return source.includes(sep) ? " [subagent]" : "";
+}
+
+function contextEdits(entries: readonly EntryLike[]): Map<string, EntryLike> {
+	const edits = new Map<string, EntryLike>();
+	for (const entry of entries) {
+		if (entry.type === "context_edit" && entry.targetId) edits.set(entry.targetId, entry);
+	}
+	return edits;
+}
+
 function historyHit(item: WindowedEntry, query: string, source = ""): HistoryHit | undefined {
 	const { entry } = item;
 	let text = item.text;
@@ -308,9 +411,10 @@ function historyHit(item: WindowedEntry, query: string, source = ""): HistoryHit
 			matchIndex = text.toLowerCase().indexOf(query);
 		}
 	}
-	const header = `${source ? `${source} ` : ""}${entry.timestamp ?? ""} [window ${item.windowId}] [${entry.id}] `;
+	const id = source ? `${entry.id}@${shortKey(source)}` : entry.id!;
+	const header = `${entry.timestamp ?? ""}${sourceTag(source)} [window ${item.windowId}] [${id}] `;
 	return {
-		id: entry.id!,
+		id,
 		priority,
 		text: `${header}${excerptAround(text, matchIndex, 100, 400)}`,
 		headerLength: header.length,
@@ -319,11 +423,11 @@ function historyHit(item: WindowedEntry, query: string, source = ""): HistoryHit
 
 function toWindowedEntry(entry: EntryLike, windows: Map<string, string>): WindowedEntry | undefined {
 	const inheritedWindow = entry.parentId ? (windows.get(entry.parentId) ?? "initial") : "initial";
-	const windowId = entry.type === "context_window" && entry.id ? entry.id : inheritedWindow;
+	const windowId = isWindow(entry) && entry.id ? entry.id : inheritedWindow;
 	if (entry.id) windows.set(entry.id, windowId);
 	const text = flattenEntry(entry);
 	if (!text || !entry.id) return undefined;
-	const images = imagesOf(entry.type === "message" ? entry.message?.content : entry.content);
+	const images = imagesOf(entry.type === "context_edit" ? entry.replacement?.content : entry.type === "message" ? entry.message?.content : entry.content);
 	return { entry, windowId, text, images };
 }
 
@@ -335,28 +439,80 @@ function* windowEntries(entries: Iterable<EntryLike>): Generator<WindowedEntry>
 	}
 }
 
-/** JSONL splits on LF, not the Unicode separators that Node's readline also recognizes. */
-async function* jsonlLines(file: string, signal?: AbortSignal): AsyncGenerator<string> {
+/** Split on LF only: JSONL strings and notes can contain Unicode separators that Node's readline also splits on. */
+async function* lfLines(file: string, signal?: AbortSignal): AsyncGenerator<string> {
 	const stream = createReadStream(file, { encoding: "utf8", signal });
-	let pending = "";
+	let pending: string[] = [];
 	for await (const chunk of stream) {
-		const lines = (pending + chunk).split("\n");
-		pending = lines.pop()!;
-		yield* lines;
+		const lines = chunk.split("\n");
+		pending.push(lines[0]);
+		if (lines.length > 1) {
+			yield pending.join("");
+			yield* lines.slice(1, -1);
+			pending = [lines.at(-1)!];
+		}
+	}
+	const last = pending.join("");
+	if (last) yield last;
+}
+
+/** Git's heuristic: a NUL byte in the first 8,000 bytes marks binary content. */
+async function isBinaryFile(path: string): Promise<boolean> {
+	const file = await open(path, "r");
+	try {
+		const { buffer, bytesRead } = await file.read(Buffer.alloc(8_000), 0, 8_000, 0);
+		return buffer.subarray(0, bytesRead).includes(0);
+	} finally {
+		await file.close();
 	}
-	if (pending) yield pending;
+}
+
+const execFileAsync = promisify(execFile);
+/**
+ * ripgrep needles whose raw JSONL matches cover every normalized match, or undefined when only a full scan is exact.
+ * Raw JSONL escapes quotes, backslashes, and control characters; flattenEntry adds brackets, parentheses, braces,
+ * colons, `$`, spaces beside those labels, and label-only phrases. Image summaries ("3 images: image/png,
+ * image/jpeg") come only from entries with an image block, so their text needs that block instead.
+ */
+function prefilterNeedles(query: string): string[] | undefined {
+	if (/["\\[\](){}:$\p{Cc}]/u.test(query) || query.trim() !== query) return undefined;
+	if (["call id", "execution arguments", "no handoff", "excluded from model context by pi"].some((phrase) => phrase.includes(query))) return undefined;
+	const image = query.includes(",") || /^\d+ ?i?m?a?g?e?s?$/.test(query) || ["images", "unknown type"].some((phrase) => phrase.includes(query));
+	return image ? [query, '"type":"image"'] : [query];
+}
+
+/** Session files whose raw JSONL contains any needle in any case, via Pi's managed ripgrep or PATH; undefined means scan every file. */
+async function filesContaining(dir: string, needles: string[], signal?: AbortSignal): Promise<Set<string> | undefined> {
+	const args = [
+		"--files-with-matches", "--fixed-strings", "--ignore-case", "--no-ignore", "--hidden", "--no-messages",
+		"--glob", "*.jsonl", ...needles.flatMap((needle) => ["--regexp", needle]), dir,
+	];
+	for (const rg of [join(getAgentDir(), "bin", "rg"), "rg"]) {
+		try {
+			const { stdout } = await execFileAsync(rg, args, { signal, maxBuffer: 64 * 1024 * 1024 });
+			return new Set(stdout.split("\n").filter(Boolean).map((file) => resolve(file)));
+		} catch (error) {
+			const { code } = error as { code?: unknown };
+			if (code === 1) return new Set();
+			if (code === "ENOENT") continue;
+			signal?.throwIfAborted();
+			return undefined;
+		}
+	}
+	return undefined;
 }
 
 async function* sessionWindowEntries(file: string, signal?: AbortSignal): AsyncGenerator<WindowedEntry> {
 	if (!existsSync(file)) return;
 	const windows = new Map<string, string>();
-	for await (const line of jsonlLines(file, signal)) {
+	for await (const line of lfLines(file, signal)) {
 		let entry: EntryLike;
 		try {
 			entry = JSON.parse(line) as EntryLike;
 		} catch {
 			continue;
 		}
+		if (!entry) continue;
 		const item = toWindowedEntry(entry, windows);
 		if (item) yield item;
 	}
@@ -364,20 +520,64 @@ async function* sessionWindowEntries(file: string, signal?: AbortSignal): AsyncG
 
 function sessionFiles(dir: string): string[] {
 	if (!existsSync(dir)) return [];
-	const files = readdirSync(dir, { recursive: true, withFileTypes: true })
+	return readdirSync(dir, { recursive: true, withFileTypes: true })
 		.filter((entry) => entry.isFile() && entry.name.endsWith(".jsonl") && !entry.name.includes(".intent."))
 		.map((entry) => join(entry.parentPath, entry.name));
-	if (files.length < 2) return files;
-	return files
+}
+
+/** Project session files, newest-modified first, optionally limited to one file key or to prefiltered candidates. */
+async function* scopedSessionFiles(
+	dir: string, cwd: string, currentFile: string | undefined, signal?: AbortSignal,
+	{ fileKey, candidates }: { fileKey?: string; candidates?: Set<string> } = {},
+): AsyncGenerator<string> {
+	const files = sessionFiles(dir);
+	const fileSet = new Set(files);
+	const visible = new Map<string, boolean>();
+	const belongs = async (file: string): Promise<boolean> => {
+		const known = visible.get(file);
+		if (known !== undefined) return known;
+		let header: { cwd?: string } | null = null;
+		for await (const line of lfLines(file, signal)) {
+			try {
+				const entry = JSON.parse(line) as { type?: string; id?: unknown; cwd?: unknown } | null;
+				if (!entry) continue;
+				if (entry.type === "session" && typeof entry.id === "string") header = { cwd: typeof entry.cwd === "string" ? entry.cwd : undefined };
+				break;
+			} catch {
+				// Pi also skips malformed lines before the first parsed entry.
+			}
+		}
+		if (!header) {
+			visible.set(file, false);
+			return false;
+		}
+		const parts = relative(dir, file).split(sep);
+		let parent: string | undefined;
+		for (let i = parts.length - 1; i > 0; i--) {
+			const candidate = `${join(dir, ...parts.slice(0, i))}.jsonl`;
+			if (fileSet.has(candidate)) {
+				parent = candidate;
+				break;
+			}
+		}
+		const allowed = file === currentFile || (parent ? await belongs(parent) : !!header.cwd && resolve(header.cwd) === cwd);
+		visible.set(file, allowed);
+		return allowed;
+	};
+	const selected = files
+		.filter((file) => (!candidates || candidates.has(resolve(file))) &&
+			(fileKey === undefined || fileKey.startsWith(shortKey(relative(dir, file)))))
 		.map((file) => ({ file, mtime: statSync(file).mtimeMs }))
-		.sort((a, b) => b.mtime - a.mtime)
-		.map(({ file }) => file);
+		.sort((a, b) => b.mtime - a.mtime);
+	for (const { file } of selected) {
+		if (await belongs(file)) yield file;
+	}
 }
 
 function currentWindowId(entries: readonly EntryLike[]): string {
 	for (let i = entries.length - 1; i >= 0; i--) {
 		const entry = entries[i];
-		if (entry.type === "context_window" && entry.id) return entry.id;
+		if (isWindow(entry) && entry.id) return entry.id;
 	}
 	return "initial";
 }
@@ -409,6 +609,7 @@ function recoveryRecord(entry: EntryLike): RecoveryRecord | undefined {
 		entry.type === "message" &&
 		entry.message?.role === "toolResult" &&
 		entry.message.toolName === "ask_question" &&
+		entry.message.namespace === undefined &&
 		entry.message.isError !== true
 	) {
 		kind = "owner";
@@ -437,77 +638,100 @@ function formatRecoveryRecord(record: RecoveryRecord, limit: number): string {
 	return boundedBlock(`[${record.label} | ${record.timestamp} | entry ${record.id}]`, record.text, limit);
 }
 
+/** Owner inputs keep a one-line preview: they are direct intent, and most are short. */
+function indexLine(record: RecoveryRecord): string {
+	const header = formatRecoveryRecord(record, 0);
+	if (record.kind !== "owner") return header;
+	const preview = record.text.replace(/\s+/g, " ").trim();
+	return `${header} ${preview.length > 120 ? `${preview.slice(0, 119)}…` : preview}`;
+}
+
 function formatPriorCheckpoint(entry: EntryLike | undefined, limit: number): string | undefined {
-	const handoff = entry?.handoff?.trim();
+	const handoff = windowHandoff(entry)?.trim();
 	if (!entry || !handoff) return undefined;
 	const id = entry.id?.slice(0, 120) ?? "unknown";
 	const header = `[older checkpoint; possibly stale | context-window entry ${id}]`;
-	if (handoff.startsWith(AUTO_HANDOFF_PREFIX) || handoff.startsWith(LEGACY_AUTO_HANDOFF_PREFIX)) {
+	if (handoff.startsWith(AUTO_HANDOFF_PREFIX)) {
 		return boundedBlock(header, `Prior automatic recovery text is not nested here. Use history read with entry ${id} if needed.`, limit);
 	}
 	return boundedBlock(header, handoff, limit);
 }
 
-/** Trailing results without a later complete assistant response; interrupted requests may have received them. */
-function trailingToolBatch(
+/** Async receipts can arrive during a later response, so its completion cannot establish receipt delivery. */
+function recoverableToolResults(
 	entries: readonly EntryLike[],
-): { callId: string; blocks: Array<{ header: string; text: string }> } | undefined {
-	const results: EntryLike[] = [];
-	let call: EntryLike | undefined;
-	for (let i = entries.length - 1; i >= 0 && !call; i--) {
+): { callId?: string; blocks: Array<{ header: string; text: string }> } | undefined {
+	const calls = new Map<string, { entry: EntryLike; block: ToolCallLike }>();
+	for (const entry of entries) {
+		if (entry.message?.role !== "assistant" || !Array.isArray(entry.message.content)) continue;
+		for (const block of entry.message.content as ToolCallLike[]) {
+			if (block?.type === "toolCall" && typeof block.id === "string") calls.set(block.id, { entry, block });
+		}
+	}
+	let trailingStart = -1;
+	let hasTrailingResult = false;
+	for (let i = entries.length - 1; i >= 0; i--) {
 		const entry = entries[i];
-		const role = entry.type === "message" ? entry.message?.role : undefined;
+		const role = entry.message?.role;
 		if (role === "toolResult") {
-			results.unshift(entry);
+			hasTrailingResult = true;
 		} else if (role === "assistant") {
 			const invalid =
 				entry.message?.stopReason === "error" ||
 				entry.message?.stopReason === "aborted" ||
 				entry.message?.stopReason === "length";
-			if (invalid) {
-				if (results.length) return undefined;
-			} else {
-				call = entry;
+			if (!invalid || hasTrailingResult) {
+				trailingStart = i;
+				break;
 			}
 		}
 	}
-	if (!call || !results.length) return undefined;
-	const calls = Array.isArray(call.message?.content)
-		? (call.message.content as Array<{ type?: string; id?: string; name?: string; arguments?: unknown }>).filter(
-				(block) => block?.type === "toolCall",
-			)
-		: [];
+	const results = entries.filter((entry, index) => {
+		const message = entry.message;
+		if (message?.role !== "toolResult" || typeof message.toolCallId !== "string") return false;
+		const call = calls.get(message.toolCallId);
+		// Use only projected provenance. An orphan may be async; never resurrect its raw call.
+		return index > trailingStart || !call || call.block.async === true;
+	});
+	if (!results.length) return undefined;
+	const call = calls.get(results[0].message!.toolCallId!)?.entry;
+	const allLinked = !!call && results.every((result) => calls.get(result.message!.toolCallId!)?.entry === call);
 	const blocks = results.map((result) => {
 		const message = result.message ?? {};
-		const matching = calls.find((block) => block.id === message.toolCallId);
-		const name = (message.toolName ?? matching?.name ?? "tool").slice(0, 80);
+		const matching = calls.get(message.toolCallId!);
+		const name = toolIdentity(message.toolName ?? matching?.block.name, message.namespace ?? matching?.block.namespace);
 		const resultId = (result.id ?? "unknown").slice(0, 120);
 		const images = imageSummary(imagesOf(message.content));
 		const output =
 			[textOf(message).trim(), images && `${images} — recover with history read id ${resultId}`]
 				.filter(Boolean)
 				.join("\n") || "(empty result)";
+		const callDetail = matching
+			? `${allLinked ? "" : `\nCall entry: ${(matching.entry.id ?? "unknown").slice(0, 120)}`}\nCall arguments: ${safeJsonStringify(matching.block.arguments ?? {})}${executionArgumentsText(matching.block)}`
+			: "\nNo matching projected call";
 		return {
 			header: `[${message.isError ? "error" : "result"} entry ${resultId}]`,
-			text: `${output}\n\nTool: ${name}\nCall arguments: ${safeJsonStringify(matching?.arguments ?? {})}`,
+			text: `${output}\n\nTool: ${name}\nCall ID: ${message.toolCallId}${callDetail}`,
 		};
 	});
-	return { callId: (call.id ?? "unknown").slice(0, 120), blocks };
+	return { callId: allLinked ? (call?.id ?? "unknown").slice(0, 120) : undefined, blocks };
 }
 
-function buildAutoHandoff(entries: readonly EntryLike[], maxChars: number): string {
-	let windowStart = 0;
-	let priorWindow: EntryLike | undefined;
-	for (let i = entries.length - 1; i >= 0; i--) {
-		if (entries[i].type === "context_window") {
-			windowStart = i + 1;
-			priorWindow = entries[i];
-			break;
-		}
-	}
-
-	const current = entries.slice(windowStart);
-	const records = current
+function buildAutoHandoff(entries: readonly EntryLike[], projected: readonly ProjectedEntry[], maxChars: number): string {
+	const { start, boundary: priorWindow } = contextStart(entries);
+	const current = entries.slice(start);
+	const edits = contextEdits(entries);
+	const omittedProjectedIds = new Set(projected.filter(({ messages }) => !messages.length).map(({ sourceEntry }) => sourceEntry.id));
+	const edited = current.flatMap((entry) => {
+		if (entry.id && omittedProjectedIds.has(entry.id)) return [];
+		const edit = entry.id ? edits.get(entry.id) : undefined;
+		if (edit?.replacement === null) return [];
+		if (!edit?.replacement) return [entry];
+		if (entry.type === "message") return [{ ...entry, id: edit.id, message: { ...entry.message, content: edit.replacement.content } }];
+		if (entry.type === "custom_message") return [{ ...entry, id: edit.id, content: edit.replacement.content }];
+		return [entry];
+	});
+	const records = edited
 		.map((entry) => recoveryRecord(entry))
 		.filter((record): record is RecoveryRecord => record !== undefined);
 	const firstOwnerRequest = records.find((record) => record.label === "owner input") ?? records[0];
@@ -523,9 +747,18 @@ function buildAutoHandoff(entries: readonly EntryLike[], maxChars: number): stri
 	const joinedLength = (parts: Array<string | undefined>) =>
 		parts.filter((part): part is string => Boolean(part)).join("\n\n").length;
 
-	const toolBatch = trailingToolBatch(current);
+	const toolEntries = projected.flatMap(({ sourceEntry, messages }) =>
+		messages
+			.filter((message) => message.role === "assistant" || message.role === "toolResult")
+			.map((message) => ({
+				type: "message",
+				id: edits.get(sourceEntry.id ?? "")?.id ?? sourceEntry.id,
+				message,
+			})),
+	);
+	const toolBatch = recoverableToolResults(toolEntries);
 	const batchHeader = toolBatch
-		? `Trailing tool batch without a later complete assistant response (failed or interrupted requests may already have received these results). Tool-call entry ${toolBatch.callId}:`
+		? `Tool result evidence (current projected window; may already have been received or handled; not current progress).${toolBatch.callId ? ` Tool-call entry ${toolBatch.callId}:` : ""}`
 		: undefined;
 	const minimumParts = [
 		preamble,
@@ -544,14 +777,14 @@ function buildAutoHandoff(entries: readonly EntryLike[], maxChars: number): stri
 	}
 	const batchBlocks = toolBatch?.blocks.slice(firstBatchBlock) ?? [];
 	const batchOmission = firstBatchBlock
-		? `Omitted ${firstBatchBlock} earlier tool result(s) whose headers could not fit. Use history read with tool-call entry ${toolBatch!.callId}, then history search/read to recover them.`
+		? `Omitted ${firstBatchBlock} earlier tool result(s) whose headers could not fit. ${toolBatch!.callId ? `Use history read with tool-call entry ${toolBatch!.callId}, then ` : "Use "}history search/read to recover them.`
 		: undefined;
 	const bareBatch = batchHeader
 		? [batchHeader, batchOmission, ...batchBlocks.map((block) => block.header)]
 				.filter((part): part is string => Boolean(part))
 				.join("\n\n")
 		: undefined;
-	const fixedCount = selected.size + (priorWindow?.handoff?.trim() ? 1 : 0);
+	const fixedCount = selected.size + (windowHandoff(priorWindow)?.trim() ? 1 : 0);
 	const fixedBudget = Math.max(
 		0,
 		maxChars - joinedLength([preamble, currentHeader, bareBatch]) - HANDOFF_OVERHEAD_RESERVE,
@@ -560,16 +793,10 @@ function buildAutoHandoff(entries: readonly EntryLike[], maxChars: number): stri
 		? Math.min(MAX_RECOVERY_RECORD_CHARS, Math.floor(fixedBudget / fixedCount))
 		: MAX_RECOVERY_RECORD_CHARS;
 	const prior = formatPriorCheckpoint(priorWindow, fixedLimit);
-	const formatted = new Map(
-		records.map((record) => [
-			record,
-			formatRecoveryRecord(record, selected.has(record) ? fixedLimit : MAX_RECOVERY_RECORD_CHARS),
-		]),
-	);
-	const fixedParts = () => [
+	const fixedParts = [
 		preamble,
 		currentHeader,
-		...records.filter((record) => selected.has(record)).map((record) => formatted.get(record)!),
+		...records.filter((record) => selected.has(record)).map((record) => formatRecoveryRecord(record, fixedLimit)),
 	];
 
 	let batch: string | undefined;
@@ -577,11 +804,11 @@ function buildAutoHandoff(entries: readonly EntryLike[], maxChars: number): stri
 		const availableText = Math.max(
 			0,
 			maxChars -
-				joinedLength([...fixedParts(), bareBatch, prior]) -
+				joinedLength([...fixedParts, bareBatch, prior]) -
 				HANDOFF_OVERHEAD_RESERVE -
 				batchBlocks.length,
 		);
-		const perBlock = Math.min(MAX_RECOVERY_RECORD_CHARS, Math.floor(availableText / batchBlocks.length));
+		const perBlock = Math.min(MAX_RECOVERY_RESULT_CHARS, Math.floor(availableText / batchBlocks.length));
 		batch = [
 			batchHeader,
 			batchOmission,
@@ -591,68 +818,40 @@ function buildAutoHandoff(entries: readonly EntryLike[], maxChars: number): stri
 			.join("\n\n");
 	}
 
-	let optionalBudget = Math.max(0, maxChars - joinedLength([...fixedParts(), batch, prior]) - HANDOFF_OVERHEAD_RESERVE);
-	for (let i = records.length - 1; i >= 0; i--) {
-		const record = records[i];
-		if (selected.has(record)) continue;
-		const length = formatted.get(record)!.length + 2;
-		if (length > optionalBudget) continue;
-		selected.add(record);
-		optionalBudget -= length;
+	// Other inputs are indexed, newest kept first when space runs out; history read recovers their full text.
+	const others = records.filter((record) => !selected.has(record));
+	const indexHeader = "Other current-window inputs, oldest first (recover with history read):";
+	let indexBudget = Math.max(0, maxChars - joinedLength([...fixedParts, indexHeader, batch, prior]) - HANDOFF_OVERHEAD_RESERVE);
+	const listed: string[] = [];
+	for (let i = others.length - 1; i >= 0; i--) {
+		const line = indexLine(others[i]);
+		if (line.length + 1 > indexBudget) break;
+		listed.unshift(line);
+		indexBudget -= line.length + 1;
 	}
-
-	const omitted = records.filter((record) => !selected.has(record));
-	const omission = omitted.length
-		? `Omitted ${omitted.length} current-window input(s) to stay within the handoff limit (${omitted.filter((record) => record.kind === "owner").length} owner, ${omitted.filter((record) => record.kind === "coordination").length} coordination; ${omitted[0].timestamp} through ${omitted.at(-1)!.timestamp}). Use history search/read to recover them.`
+	const unlisted = others.length - listed.length;
+	const index = others.length
+		? [indexHeader, ...(unlisted ? [`${unlisted} earlier input(s) not listed; use history search to find them.`] : []), ...listed].join("\n")
 		: undefined;
-	return [...fixedParts(), omission, batch, prior].filter((part): part is string => Boolean(part)).join("\n\n");
+	return [...fixedParts, index, batch, prior].filter((part): part is string => Boolean(part)).join("\n\n");
 }
 
-/** Legacy reminders carry only windowId; they match on it alone until the model changes. */
 function reminderMatches(details: unknown, fingerprint: ReminderFingerprint): boolean {
 	const stored = (details ?? {}) as Partial<ReminderFingerprint>;
 	return (
 		stored.windowId === fingerprint.windowId &&
-		(stored.contextWindow ?? fingerprint.contextWindow) === fingerprint.contextWindow &&
-		(stored.reserveTokens ?? fingerprint.reserveTokens) === fingerprint.reserveTokens
+		stored.contextWindow === fingerprint.contextWindow &&
+		stored.reserveTokens === fingerprint.reserveTokens
 	);
 }
 
-function reminderIsStale(
-	customType: unknown,
-	details: unknown,
-	fingerprint: ReminderFingerprint,
-	branch: readonly EntryLike[],
-): boolean {
-	if (!reminderMatches(details, fingerprint)) return true;
-	const stored = (details ?? {}) as Partial<ReminderFingerprint>;
-	if (customType !== LEGACY_REMINDER_TYPE || stored.contextWindow !== undefined || stored.reserveTokens !== undefined) {
-		return false;
-	}
-	let reminderIndex = -1;
-	for (let i = 0; i < branch.length; i++) {
-		const entry = branch[i];
-		if (
-			entry.type === "custom_message" &&
-			entry.customType === LEGACY_REMINDER_TYPE &&
-			((entry.details ?? {}) as Partial<ReminderFingerprint>).windowId === stored.windowId
-		) {
-			reminderIndex = i;
-		}
-	}
-	return reminderIndex !== -1 && branch.slice(reminderIndex + 1).some((entry) => entry.type === "model_change");
-}
-
 function hasReminder(entries: readonly EntryLike[], fingerprint: ReminderFingerprint): boolean {
 	return entries.some(
-		(entry) =>
-			entry.type === "custom_message" &&
-			isReminderType(entry.customType) &&
-			!reminderIsStale(entry.customType, entry.details, fingerprint, entries),
+		(entry) => entry.type === "custom_message" && isReminderType(entry.customType) && reminderMatches(entry.details, fingerprint),
 	);
 }
 
-function budgetFor(ctx: NativeContext, contextWindow = ctx.model?.contextWindow): Budget | undefined {
+function budgetFor(ctx: PolicyContext, contextWindow = ctx.model?.contextWindow): Budget | undefined {
 	if (!contextWindow || contextWindow <= 0) return undefined;
 	const { enabled, reserveTokens } = ctx.getCompactionSettings();
 	const usable = contextWindow - reserveTokens;
@@ -660,9 +859,9 @@ function budgetFor(ctx: NativeContext, contextWindow = ctx.model?.contextWindow)
 }
 
 /** Half the fresh capacity after prompt/tool/input overhead remains for continued work. */
-function freshPayloadChars(ctx: NativeContext, toolTokens: number, pendingMessages: readonly MessageLike[] = []): number {
+function freshPayloadChars(ctx: PolicyContext, toolTokens: number, pendingMessages: readonly MessageLike[] = [], cap = MAX_HANDOFF_CHARS): number {
 	const contextWindow = ctx.model?.contextWindow;
-	if (!contextWindow || contextWindow <= 0) return MAX_HANDOFF_CHARS;
+	if (!contextWindow || contextWindow <= 0) return cap;
 	const budget = budgetFor(ctx, contextWindow);
 	const line = budget?.enabled && budget.supported ? budget.rolloverAt : contextWindow;
 	const promptTokens = Math.ceil(ctx.getSystemPrompt().length / 4);
@@ -671,54 +870,141 @@ function freshPayloadChars(ctx: NativeContext, toolTokens: number, pendingMessag
 		0,
 	);
 	return Math.min(
-		MAX_HANDOFF_CHARS,
+		cap,
 		Math.max(0, Math.floor((line - PAGE_MARGIN_TOKENS - promptTokens - toolTokens - pendingTokens) / 2)) * 4,
 	);
 }
 
+/** Bound only the carried receipts; edits preserve the journal and native call/result identity. */
+function boundWindowReceipts(
+	ctx: ExtensionContext & PolicyContext,
+	projected: readonly ProjectedEntry[],
+	pending: readonly MessageLike[],
+	toolTokens: number,
+): ReceiptEdit[] | undefined {
+	if (!ctx.model) return undefined;
+	const estimate = estimateTokens as unknown as (message: MessageLike) => number;
+	const messages = projected.flatMap((entry) => entry.messages);
+	const budget = budgetFor(ctx);
+	const reserve = budget?.enabled && budget.supported ? budget.reserveTokens : 0;
+	const overhead =
+		reserve +
+		PAGE_MARGIN_TOKENS +
+		Math.max(
+			Math.ceil(ctx.getSystemPrompt().length / 4) + toolTokens,
+			messages.filter((message) => message.role === "system").reduce((sum, message) => sum + estimate(message), 0),
+		) +
+		pending.reduce((sum, message) => sum + estimate(message), 0);
+	const fixed = messages.filter((message) => message.role !== "system" && message.role !== "toolResult");
+	const available = ctx.model.contextWindow - overhead - fixed.reduce((sum, message) => sum + estimate(message), 0);
+	const edits = contextEdits(ctx.sessionManager.getBranch() as EntryLike[]);
+	const receipts = projected.flatMap(({ sourceEntry, messages }) =>
+		messages.filter((message) => message.role === "toolResult").map((message) => {
+			if (!sourceEntry.id) throw new Error("Posthorse: retained receipt has no history entry");
+			const recoveryId = edits.get(sourceEntry.id)?.id ?? sourceEntry.id;
+			const images = imageSummary(imagesOf(message.content));
+			const header = `Retained ${message.isError ? "error" : "result"} excerpt. Full content: history read id ${recoveryId}.${images ? `\n${images}` : ""}\n`;
+			const cost = estimate(message);
+			const minimum = Math.min(cost, Math.ceil(header.length / 4));
+			return { id: sourceEntry.id, message, header, cost, minimum };
+		}),
+	);
+	if (receipts.reduce((sum, receipt) => sum + receipt.cost, 0) <= available) return undefined;
+	let extra = available - receipts.reduce((sum, receipt) => sum + receipt.minimum, 0);
+	if (extra < 0) throw new Error("Posthorse: fresh context cannot fit fixed input and receipt recovery references");
+	// Like handoffs, oversized receipt excerpts leave half the remaining capacity for continued work.
+	extra = Math.floor(extra / 2);
+	const drafts: ReceiptEdit[] = [];
+	receipts.sort((a, b) => a.cost - a.minimum - (b.cost - b.minimum));
+	for (const [index, receipt] of receipts.entries()) {
+		const allowance = receipt.minimum + Math.min(receipt.cost - receipt.minimum, Math.floor(extra / (receipts.length - index)));
+		extra -= allowance - receipt.minimum;
+		if (receipt.cost <= allowance) continue;
+		const content = receipt.header + excerpt(textOf(receipt.message), allowance * 4 - receipt.header.length);
+		drafts.push({ type: "context_edit", targetId: receipt.id, replacement: { content } });
+	}
+	const replacements = new Map(drafts.map((draft) => [draft.targetId, draft.replacement.content]));
+	const total = projected.reduce(
+		(sum, entry) =>
+			sum + entry.messages.reduce(
+				(tokens, message) => tokens + (message.role === "system" ? 0 : estimate(
+					replacements.has(entry.sourceEntry.id ?? "")
+						? { ...message, content: replacements.get(entry.sourceEntry.id!) }
+						: message,
+				)),
+				0,
+			),
+		overhead,
+	);
+	if (total > ctx.model.contextWindow) throw new Error("Posthorse: retained receipts exceed fresh context capacity");
+	return drafts;
+}
+
+/** Official Pi cannot expose its live settings to extensions; budget reports say when they used the persisted snapshot. */
+const SNAPSHOT_NOTE = "Reminder and budget policy uses available settings (a persisted CLI snapshot by default); Pi's live settings control automatic compaction.";
+const CHECKPOINT_STEPS = "rewrite the task's current-state note in place with notes write (goal, progress, decisions, next steps), then call new_context";
+
 function unsupportedMessage(budget: Budget): string {
 	const n = (value: number) => value.toLocaleString("en-US");
-	return `Posthorse: unsupported configuration. The model's context window (${n(budget.contextWindow)} tokens) minus Pi's compaction.reserveTokens (${n(budget.reserveTokens)}) leaves ${n(budget.usable)} usable tokens; Posthorse needs at least ${n(MIN_USABLE_TOKENS)}. Automatic rollover and checkpoint reminders are off for this model. Lower compaction.reserveTokens in Pi settings or use a larger-context model. new_context remains available with a model-aware handoff limit.`;
+	return `Posthorse: unsupported configuration. The model's context window (${n(budget.contextWindow)} tokens) minus Pi's compaction.reserveTokens (${n(budget.reserveTokens)}) leaves ${n(budget.usable)} usable tokens; Posthorse needs at least ${n(MIN_USABLE_TOKENS)}. Automatic Posthorse rollover and checkpoint reminders are off for this model, so Pi's own compaction applies. Lower compaction.reserveTokens in Pi settings or use a larger-context model. new_context remains available with a model-aware handoff limit.`;
 }
 
 /** Capacity before Pi's automatic line (or configured context limit), including page metadata and refusals. */
-function pageCapacity(ctx: NativeContext, toolTokens: number): number {
+function pageCapacity(ctx: PolicyContext, toolTokens: number): number {
 	const usage = ctx.getContextUsage();
-	if (!usage || usage.tokens == null) return freshPayloadChars(ctx, toolTokens) / 4 + PAGE_MARGIN_TOKENS;
+	if (!usage || usage.tokens == null) return freshPayloadChars(ctx, toolTokens, [], MAX_PAGE_CHARS) / 4 + PAGE_MARGIN_TOKENS;
 	const budget = budgetFor(ctx, usage.contextWindow);
 	const line = budget?.enabled && budget.supported ? budget.rolloverAt : usage.contextWindow;
 	return line - usage.tokens;
 }
 
-function buildGuidance(ctx: NativeContext): string {
+function buildGuidance(ctx: PolicyContext, official: boolean): string {
 	const budget = budgetFor(ctx);
 	const enabled = budget?.enabled ?? ctx.getCompactionSettings().enabled;
 	let automatic: string;
 	if (!enabled) {
-		automatic =
-			"Pi compaction is disabled, so Posthorse sends no checkpoint reminder and performs no automatic rollover. new_context remains available.";
+		automatic = official
+			? "Pi compaction is disabled in the available settings, so Posthorse sends no checkpoint reminder. new_context remains available."
+			: "Pi compaction is disabled, so Posthorse sends no checkpoint reminder and performs no automatic rollover. new_context remains available.";
 	} else if (budget && !budget.supported) {
 		automatic = unsupportedMessage(budget);
 	} else {
 		const deadline = budget
 			? `${Math.max(1, Math.round((budget.rolloverAt / budget.contextWindow) * 100))}% used`
 			: "the configured Pi context limit";
-		automatic = `Automatic Posthorse rollover follows Pi's enabled compaction setting. At most one best-effort checkpoint reminder may appear before the rollover line (${deadline}); a large turn, overflow, restart, or smaller model can skip it.\nWhen reminded, stop normal work, save goal/progress/decisions/next steps, then call new_context now.`;
+		automatic = `Automatic rollover follows Pi's compaction setting. At most one checkpoint reminder may arrive before the rollover line (${deadline}); when it does, stop normal work, ${CHECKPOINT_STEPS}.`;
 	}
 	return `## Context self-management (Posthorse)
-Context windows are finite. Use get_context_remaining for the best available native estimate when it matters; routine turns do not include a changing meter.
 ${automatic}
-new_context starts a genuinely fresh Pi context after the complete tool batch. Earlier conversation remains in the session transcript and is recoverable with notes and history.
-Automatic handoffs are emergency recovery records, not proof of current state. Restore notes/todos/history and verify live state before continuing stateful or external work.`;
+After a rollover, earlier conversation stays in history. Restore notes and todos, then verify live state before stateful or external work; automatic handoffs record inputs, not progress.
+Write handoffs and notes as normal readable prose; notes and history search match literal text.`;
 }
 
-export default function (pi: ExtensionAPI) {
+function persistedPolicy(ctx: ExtensionContext): CompactionPolicy {
+	const settings = SettingsManager.create(ctx.cwd, getAgentDir(), { projectTrusted: ctx.isProjectTrusted() });
+	const errors = settings.drainErrors();
+	if (errors.length) throw new Error(`Posthorse could not read persisted Pi settings: ${errors.map((error) => error.error.message).join("; ")}`);
+	return settings.getCompactionSettings(ctx.model);
+}
+
+/** SDK hosts on official Pi can inject their live settings instead of the persisted snapshot; the fork always uses its own. */
+export const createPosthorse = (getPolicy: (ctx: ExtensionContext) => CompactionPolicy = persistedPolicy) => (pi: ExtensionAPI) => {
+	const nativePi = pi as unknown as NativeExtensionAPI;
+	const native = typeof nativePi.registerContextWindowHook === "function";
+	const policy = (ctx: ExtensionContext): PolicyContext =>
+		native ? (ctx as ExtensionContext & PolicyContext) : {
+			model: ctx.model,
+			getCompactionSettings: () => getPolicy(ctx),
+			getContextUsage: () => ctx.getContextUsage(),
+			getSystemPrompt: () => ctx.getSystemPrompt(),
+		};
 	registerPosthorseMessages(pi);
 	const activeToolTokens = () => {
 		const active = new Set(pi.getActiveTools());
 		return pi
 			.getAllTools()
-			.filter((tool) => active.has(tool.name))
+			// The fork identifies namespaced tools by id; official Pi only has names.
+			.filter((tool) => active.has((tool as typeof tool & { id?: string }).id ?? tool.name))
 			.reduce(
 				(total, tool) =>
 					total +
@@ -730,9 +1016,15 @@ export default function (pi: ExtensionAPI) {
 			);
 	};
 
+	if (native) {
+		nativePi.registerContextWindowHook((event, ctx) =>
+			boundWindowReceipts(ctx as ExtensionContext & PolicyContext, event.contextEntries, event.pendingMessages, activeToolTokens()),
+		);
+	}
+
 	let pendingPageTokens = 0;
 	let previousPageUsage: number | null | undefined;
-	const pageSize = (ctx: NativeContext, offset: number, imageCount: number, cursor?: string) => {
+	const pageSize = (ctx: PolicyContext, offset: number, imageCount: number, cursor?: string, imageOffset?: number) => {
 		const usage = ctx.getContextUsage()?.tokens;
 		// Parallel siblings are not in native usage yet; sequential results must not be counted twice.
 		if (usage != null && previousPageUsage != null) {
@@ -741,11 +1033,11 @@ export default function (pi: ExtensionAPI) {
 		previousPageUsage = usage;
 		const remaining = pageCapacity(ctx, activeToolTokens()) - pendingPageTokens;
 		const chars = Math.min(
-			MAX_HANDOFF_CHARS,
+			MAX_PAGE_CHARS,
 			Math.max(0, remaining - PAGE_MARGIN_TOKENS) * 4 - imageCount * ESTIMATED_IMAGE_CHARS,
 		);
 		if (chars < MIN_PAGE_CHARS) {
-			const message = `Too little context remains to read a page safely. Call new_context first, then retry ${cursor ? "with the same cursor" : `with offset ${offset}`}.`;
+			const message = `Too little context remains to read a page safely. Call new_context first, then retry ${cursor ? "with the same cursor" : `with offset ${offset}${imageOffset === undefined ? "" : ` and imageOffset ${imageOffset}`}`}.`;
 			// Refusals consume context too. Once even the guidance no longer fits, omit repeated text;
 			// the failed call still carries its original offset and earlier refusals explain the retry.
 			const text = Math.ceil(message.length / 4) <= remaining ? message : "";
@@ -758,12 +1050,12 @@ export default function (pi: ExtensionAPI) {
 		pendingPageTokens += Math.ceil(text.length / 4) + images.length * (ESTIMATED_IMAGE_CHARS / 4);
 		return textResult(text, images, display);
 	};
-	const pageError = (ctx: NativeContext, message: string, cursor?: string): never => {
+	const pageError = (ctx: PolicyContext, message: string, cursor?: string): never => {
 		pageSize(ctx, 0, 0, cursor);
 		pendingPageTokens += Math.ceil(message.length / 4);
 		throw new Error(message);
 	};
-	const notesPage = (ctx: NativeContext, rows: string[], offset: number, kind: "notes-list" | "notes-search", empty: string) => {
+	const notesPage = (ctx: PolicyContext, rows: string[], offset: number, kind: "notes-list" | "notes-search", empty: string) => {
 		const text = rows.length ? rows.join("\n") : empty;
 		const chars = pageSize(ctx, offset, 0);
 		if (offset && offset >= text.length) pageError(ctx, "Offset is past the end; restart with offset 0.");
@@ -772,11 +1064,12 @@ export default function (pi: ExtensionAPI) {
 		let end = Math.min(text.length, offset + chars);
 		let start = 0;
 		const starts: number[] = [];
+		const maxRows = kind === "notes-search" ? 20 : 100;
 		for (const row of rows) {
 			if (start >= end) break;
 			if (start + row.length > offset) starts.push(start);
 			start += row.length + 1;
-			if (kind === "notes-search" && starts.length === 20) { end = Math.min(end, start - 1); break; }
+			if (starts.length === maxRows) { end = Math.min(end, start - 1); break; }
 		}
 		// A result-count cap can require continuation even when the character cap did not.
 		if (end < text.length) end = Math.min(end, offset + chars - footer(text.length).length);
@@ -787,14 +1080,13 @@ export default function (pi: ExtensionAPI) {
 		previousPageUsage = undefined;
 	});
 
-	pi.on("session_start", (_event, ctx) => {
+	pi.on("session_start", () => {
 		pendingPageTokens = 0;
 		previousPageUsage = undefined;
-		nativeContext(ctx);
 	});
 
 	pi.on("before_agent_start", (event, ctx) => {
-		const guidance = buildGuidance(nativeContext(ctx));
+		const guidance = buildGuidance(policy(ctx), !native);
 		// An earlier full-prompt override makes section edits invisible to Pi.
 		if (event.systemPromptOptions.forceSystemPrompt !== undefined) {
 			return { systemPrompt: `${event.systemPrompt}\n\n${guidance}` };
@@ -803,21 +1095,32 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	pi.on("turn_end", (event, ctx) => {
-		const native = nativeContext(ctx);
+		const host = policy(ctx);
 		if (
 			event.message.role === "assistant" &&
 			(event.message.stopReason === "error" || event.message.stopReason === "aborted")
 		)
 			return;
-		// Pi commits a new_context request only when every tool in the batch succeeded.
-		if (
-			event.toolResults.some((result) => result.toolName === "new_context") &&
-			!event.toolResults.some((result) => result.isError)
-		)
-			return;
-		const usage = native.getContextUsage();
+		const requested = event.toolResults.find((result) => result.toolName === "new_context");
+		// Suppress clear successes; turn_end can also include unrelated background errors.
+		// If Pi still rolls over, context filtering below removes any stale reminder.
+		if (requested && !event.toolResults.some((result) => result.isError)) {
+			// The fork commits new_context from the tool result; official Pi needs a retain-none compaction draft.
+			if (native || event.outcome === "aborted" || ctx.signal?.aborted) return;
+			const content = (event.message as MessageLike).content;
+			const call = (Array.isArray(content) ? content as ToolCallLike[] : []).find((block) => block?.type === "toolCall" && block.id === requested.toolCallId);
+			const handoff = (call?.arguments as { handoff?: unknown } | undefined)?.handoff;
+			const summary = (typeof handoff === "string" && handoff.trim()) || EMPTY_HANDOFF;
+			// Input steered in after execute() checked capacity can leave too little room.
+			if (summary.length > freshPayloadChars(host, activeToolTokens(), event.context.pendingMessages)) {
+				return { entries: [...event.entries, { type: "custom_message" as const, customType: "posthorse-reset-deferred", display: true,
+					content: "Posthorse reset deferred: queued messages leave too little room for the requested handoff. The current context is unchanged; process those messages, then request a shorter handoff." }] };
+			}
+			return { entries: [...event.entries, { type: "compaction" as const, summary, firstKeptEntryId: null, details: { posthorse: 1, reason: "explicit" } }], continue: true };
+		}
+		const usage = host.getContextUsage();
 		if (!usage || usage.tokens == null || usage.contextWindow <= 0) return;
-		const budget = budgetFor(native, usage.contextWindow);
+		const budget = budgetFor(host, usage.contextWindow);
 		if (!budget || !budget.enabled || !budget.supported) return;
 		if (usage.tokens >= budget.rolloverAt) return;
 		const reminderBuffer = Math.min(REMINDER_BUFFER_TOKENS, Math.floor(budget.usable * 0.1));
@@ -830,11 +1133,12 @@ export default function (pi: ExtensionAPI) {
 			contextWindow: budget.contextWindow,
 			reserveTokens: budget.reserveTokens,
 		};
-		if (hasReminder(branch, fingerprint)) return;
+		// A reminder a compaction summarized away no longer reaches the model.
+		if (hasReminder(branch.slice(contextStart(branch).start), fingerprint)) return;
 		pi.sendMessage(
 			{
 				customType: REMINDER_TYPE,
-				content: `[posthorse] Checkpoint now: ${(budget.rolloverAt - usage.tokens).toLocaleString("en-US")} tokens remain before Pi's automatic rollover line. Stop normal work, save goal/progress/decisions/next steps, then call new_context now. This reminder is best-effort; a large turn, overflow, restart, or smaller model can reach rollover without one.`,
+				content: `[posthorse] Checkpoint now: ${(budget.rolloverAt - usage.tokens).toLocaleString("en-US")} tokens remain before Pi's automatic rollover line. Stop normal work, ${CHECKPOINT_STEPS}.`,
 				display: true,
 				details: fingerprint,
 			},
@@ -844,15 +1148,15 @@ export default function (pi: ExtensionAPI) {
 
 	// Filter active input only; raw reminders remain in history for deduplication and recovery.
 	pi.on("context", (event, ctx) => {
-		const marker = event.messages.find(
-			(message) => message.role === "custom" && message.customType === "context-window",
-		);
-		const windowId = marker?.role === "custom" ? (marker.details as { windowId?: unknown } | undefined)?.windowId : "initial";
-		if (typeof windowId !== "string") return;
-		const native = nativeContext(ctx);
 		if (!event.messages.some((message) => message.role === "custom" && isReminderType(message.customType))) return;
-		const budget = budgetFor(native);
-		const branch = ctx.sessionManager.getBranch() as EntryLike[];
+		// The fork's window marker saves a branch walk, but a compaction inside the window drops it.
+		const marker = event.messages.find((message) => message.role === "custom" && message.customType === "context-window");
+		const windowId = marker?.role === "custom"
+			? (marker.details as { windowId?: unknown } | undefined)?.windowId
+			: currentWindowId(ctx.sessionManager.getBranch() as EntryLike[]);
+		if (typeof windowId !== "string") return;
+		const host = policy(ctx);
+		const budget = budgetFor(host);
 		const fingerprint: ReminderFingerprint = {
 			windowId,
 			contextWindow: budget?.contextWindow,
@@ -861,58 +1165,88 @@ export default function (pi: ExtensionAPI) {
 		const stale = (message: (typeof event.messages)[number]) =>
 			message.role === "custom" &&
 			isReminderType(message.customType) &&
-			(!native.getCompactionSettings().enabled || reminderIsStale(message.customType, message.details, fingerprint, branch));
+			(!host.getCompactionSettings().enabled || !reminderMatches(message.details, fingerprint));
 		if (event.messages.some(stale)) return { messages: event.messages.filter((message) => !stale(message)) };
 	});
 
-	// Claim Pi's automatic threshold/overflow trigger with a fresh window: no summary, no summarization auth.
-	(pi as unknown as NativeExtensionAPI).on("session_before_auto_compact", (event, ctx) => {
-		const native = nativeContext(ctx);
-		const budget = budgetFor(native);
-		// An unsupported budget would roll over every turn; leave Pi's own behavior in place instead.
-		if (budget && !budget.supported) return undefined;
-		const limit = freshPayloadChars(native, activeToolTokens(), event.pendingMessages);
-		if (limit < MIN_PAGE_CHARS) return undefined;
-		const handoff = buildAutoHandoff(event.branchEntries, limit);
-		if (handoff.length > limit) return undefined;
-		return { newContext: { handoff } };
-	});
+	if (native) {
+		// Claim Pi's automatic threshold/overflow trigger with a fresh window: no summary, no summarization auth.
+		nativePi.on("session_before_auto_compact", (event, ctx) => {
+			const host = policy(ctx as ExtensionContext);
+			const budget = budgetFor(host);
+			// An unsupported budget would roll over every turn; leave Pi's own behavior in place instead.
+			if (budget && !budget.supported) return undefined;
+			const limit = freshPayloadChars(host, activeToolTokens(), event.pendingMessages);
+			const projected = (ctx as ExtensionContext).sessionManager.buildSessionProjection().entries;
+			const handoff = limit >= MIN_PAGE_CHARS ? buildAutoHandoff(event.branchEntries, projected, limit) : "";
+			if (!handoff || handoff.length > limit) {
+				// Only receipts Pi will retain require shaping; consumed results must not force an empty cut.
+				return event.retainedToolResultIds.length ? { newContext: {} } : undefined;
+			}
+			return { newContext: { handoff } };
+		});
+	} else {
+		// Official Pi owns thresholds, recovery retries, and whether another request follows.
+		pi.on("session_before_compact", (event, ctx) => {
+			if (event.reason === "manual") return;
+			const cancelled = () => event.signal.aborted || ctx.signal?.aborted;
+			if (cancelled()) return { cancel: true };
+			try {
+				// The event carries Pi's live settings; prefer them over the persisted snapshot.
+				const host: PolicyContext = { ...policy(ctx), getCompactionSettings: () => event.preparation.settings };
+				// Small/unknown context windows deliberately keep Pi's own compaction.
+				if (!budgetFor(host)?.supported) return;
+				const limit = freshPayloadChars(host, activeToolTokens());
+				const handoff = buildAutoHandoff(ctx.sessionManager.getBranch() as EntryLike[], ctx.sessionManager.buildSessionProjection().entries, limit);
+				if (limit < MIN_PAGE_CHARS || handoff.length > limit) throw new Error("Too little fresh context capacity for an automatic recovery record.");
+				if (cancelled()) return { cancel: true };
+				// firstKeptEntryId must name an entry; an invisible sentinel retains no prior conversation.
+				pi.appendEntry("posthorse-boundary", {});
+				const firstKeptEntryId = ctx.sessionManager.getLeafId();
+				if (!firstKeptEntryId) throw new Error("Pi did not persist the context boundary.");
+				return { compaction: { summary: handoff, firstKeptEntryId, tokensBefore: event.preparation.tokensBefore, details: { posthorse: 1, reason: event.reason } } };
+			} catch (error) {
+				// Pi swallows handler errors and would then run its summarizer; cancel instead.
+				if (!cancelled()) {
+					const message = `Posthorse automatic rollover cancelled: ${error instanceof Error ? error.message : String(error)}`;
+					if (ctx.hasUI) ctx.ui.notify(message, "error");
+					else console.error(message);
+				}
+				return { cancel: true };
+			}
+		});
+	}
 
 	pi.registerTool({
 		name: "new_context",
 		label: "New Context",
 		...toolCards("new_context"),
 		description:
-			"Start a genuinely fresh context window after this tool batch. Earlier conversation leaves active context without a generated summary but remains recoverable through history. Pass concise continuation state in handoff, or save richer state with notes first.",
-		promptSnippet: "start a fresh context window with an optional atomic handoff",
-		promptGuidelines: [
-			"Before calling new_context, pass concise continuation state in handoff or save durable goal/progress/decisions/next-steps with notes",
-		],
+			"Start a fresh context window once the current foreground tools succeed; background work continues across the reset. Earlier conversation stays recoverable through history. Put continuation state in handoff, or save fuller state in notes first.",
+		promptSnippet: "request a fresh context window with an optional handoff",
 		parameters: Type.Object({
 			handoff: Type.Optional(
 				Type.String({
-					description: "Concise state the fresh window needs to continue correctly",
+					description: "What the fresh window needs to continue, as readable prose",
 					maxLength: MAX_HANDOFF_CHARS,
 				}),
 			),
 		}),
 		async execute(_id, { handoff }, _signal, _onUpdate, ctx) {
-			const native = nativeContext(ctx);
 			const trimmed = handoff?.trim() || undefined;
-			const limit = freshPayloadChars(native, activeToolTokens());
+			const limit = freshPayloadChars(policy(ctx), activeToolTokens());
 			if (trimmed && trimmed.length > limit) {
 				throw new Error(
 					`Handoff is too large for the active model (${trimmed.length.toLocaleString("en-US")} characters; limit ${limit.toLocaleString("en-US")}). Save fuller state in notes, then retry with a shorter handoff or no handoff.`,
 				);
 			}
-			return {
-				...textResult(
-					"Requested a fresh Pi context after this complete tool batch succeeds. Earlier conversation stays in session history.",
-					[],
-					{ kind: "new-context" },
-				),
-				newContext: { handoff: trimmed },
-			};
+			const result = textResult(
+				"Requested a fresh Pi context after the current foreground tools succeed. Background work continues across the reset. Earlier conversation stays in session history.",
+				[],
+				{ kind: "new-context" },
+			);
+			// Official Pi ignores this field; its reset is committed at turn_end from the call arguments.
+			return native ? { ...result, newContext: { handoff: trimmed } } : result;
 		},
 	});
 
@@ -921,22 +1255,22 @@ export default function (pi: ExtensionAPI) {
 		label: "Context Remaining",
 		...toolCards("get_context_remaining"),
 		description:
-			"Best available native estimate of the context budget: tokens until Pi's automatic rollover line and until the configured context limit.",
-		promptSnippet: "check the remaining context budget only when needed",
+			"Estimate tokens left before Pi's automatic rollover and the configured context limit. A checkpoint reminder already arrives before rollover; use this only before a large step late in a window.",
+		promptSnippet: "check the context budget before a large step late in a window",
 		parameters: Type.Object({}),
 		async execute(_id, _params, _signal, _onUpdate, ctx) {
-			const native = nativeContext(ctx);
-			const usage = native.getContextUsage();
+			const host = policy(ctx);
+			const usage = host.getContextUsage();
 			if (!usage || usage.tokens == null) return textResult("Context usage is not known until the next model response.", [], { kind: "context" });
 			const n = (value: number) => value.toLocaleString("en-US");
-			const budget = budgetFor(native, usage.contextWindow);
+			const budget = budgetFor(host, usage.contextWindow);
 			const display: PosthorseDisplay = {
 				kind: "context", usage,
 				rollover: !budget?.enabled ? "disabled" : budget.supported ? "enabled" : "unsupported",
 				rolloverAt: budget?.rolloverAt,
 			};
-			const configured = `≈${n(Math.max(0, usage.contextWindow - usage.tokens))} tokens until the configured context limit (${n(usage.tokens)}/${n(usage.contextWindow)} used, ${Math.round(usage.percent ?? 0)}%). Best available native estimate.`;
-			if (!budget?.enabled) return textResult(`Automatic rollover is disabled (Pi compaction.enabled=false). ${configured}`, [], display);
+			const configured = `≈${n(Math.max(0, usage.contextWindow - usage.tokens))} tokens until the configured context limit (${n(usage.tokens)}/${n(usage.contextWindow)} used, ${Math.round(usage.percent ?? 0)}%). Best available native estimate.${native ? "" : ` ${SNAPSHOT_NOTE}`}`;
+			if (!budget?.enabled) return textResult(`Automatic rollover is disabled${native ? "" : " in the available settings"} (Pi compaction.enabled=false). ${configured}`, [], display);
 			if (!budget.supported) return textResult(`${unsupportedMessage(budget)} ${configured}`, [], display);
 			return textResult(
 				`≈${n(Math.max(0, budget.rolloverAt - usage.tokens))} tokens until automatic rollover (line at ${n(budget.rolloverAt)}); ${configured}`,
@@ -950,18 +1284,14 @@ export default function (pi: ExtensionAPI) {
 		label: "Notes",
 		...toolCards("notes"),
 		description:
-			"Persistent notes in .pi/notes/ that survive context resets. Ops: list/read/search (paged; repeat with offset to continue), write (create/replace; empty content clears), append. Search matches case-insensitive substrings over note lines. Git worktrees share notes: at the main checkout for conventional .git layouts, or in the common Git directory when metadata is stored separately. Old checkout-local notes are imported without overwriting shared notes.",
+			"Durable notes in .pi/notes/, shared across Git worktrees and kept across context resets. Ops: list (newest first, with size and date; optional folder path), read, search (case-insensitive substring over text notes), write (replace; empty content clears), append (adds one line-terminated record). list/read/search are paged; continue with the returned offset. Keep one current-state note per task and rewrite it in place.",
 		promptSnippet: "save and recall durable state that survives context resets",
-		promptGuidelines: [
-			"Use notes for durable state too large for a new_context handoff",
-			"Reload relevant notes after a context rollover",
-		],
 		parameters: Type.Object({
 			op: Type.Union(
 				[Type.Literal("list"), Type.Literal("read"), Type.Literal("write"), Type.Literal("append"), Type.Literal("search")],
 				{ description: "Operation to perform" },
 			),
-			path: Type.Optional(Type.String({ description: "Note path relative to .pi/notes/ (read/write/append)" })),
+			path: Type.Optional(Type.String({ description: "Note or folder path relative to .pi/notes/" })),
 			content: Type.Optional(Type.String({ description: "Full file content (write) or text to add (append)" })),
 			query: Type.Optional(Type.String({ description: "Substring to find in notes (search)" })),
 			offset: Type.Optional(Type.Integer({ description: "Character offset for list/read/search (default 0)", minimum: 0 })),
@@ -975,30 +1305,52 @@ export default function (pi: ExtensionAPI) {
 				}
 				return join(dir, relative);
 			};
-			const walk = (directory: string, output: string[]) => {
+			const walk = (directory: string, output: NoteFile[], ancestors = new Set<string>()) => {
+				const root = realpathSync(directory);
+				if (ancestors.has(root)) return;
+				ancestors.add(root);
 				for (const file of readdirSync(directory)) {
 					const path = join(directory, file);
-					if (statSync(path).isDirectory()) walk(path, output);
-					else output.push(path);
+					const info = statSync(path, { throwIfNoEntry: false });
+					if (!info) continue;
+					if (info.isDirectory()) walk(path, output, ancestors);
+					else output.push({ path, size: info.size, mtimeMs: info.mtimeMs });
 				}
+				ancestors.delete(root);
 			};
+			const notesUnder = (target: string): NoteFile[] => {
+				const info = statSync(target, { throwIfNoEntry: false });
+				if (!info) return [];
+				const files: NoteFile[] = [];
+				if (info.isDirectory()) walk(target, files);
+				else files.push({ path: target, size: info.size, mtimeMs: info.mtimeMs });
+				return files.sort((a, b) => b.mtimeMs - a.mtimeMs);
+			};
+			const list = (folder?: string) => notesPage(
+				policy(ctx),
+				notesUnder(folder ? safeJoin(folder) : dir).map((file) =>
+					`${file.path.slice(dir.length + 1)}  ${formatSize(file.size)}  ${new Date(file.mtimeMs).toISOString().slice(0, 16)}Z`),
+				params.offset ?? 0,
+				"notes-list",
+				folder ? `(no notes in ${folder})` : "(no notes yet)",
+			);
 
 			switch (params.op) {
-				case "list": {
-					const files: string[] = [];
-					if (existsSync(dir)) walk(dir, files);
-					return notesPage(nativeContext(ctx), files.map((file) => file.slice(dir.length + 1)), params.offset ?? 0, "notes-list", "(no notes yet)");
-				}
+				case "list":
+					return list(params.path);
 				case "read": {
 					const relative = requireValue(params.path, "path", params.op);
 					const path = safeJoin(relative);
-					if (!existsSync(path)) throw new Error(`No note at ${relative}. Use op "list" to see available notes.`);
+					const info = statSync(path, { throwIfNoEntry: false });
+					if (!info) throw new Error(`No note at ${relative}. Use op "list" to see available notes.`);
+					if (info.isDirectory()) return list(relative);
+					if (await isBinaryFile(path)) throw new Error(`${relative} is a binary file (${formatSize(info.size)}); notes read returns text only.`);
 					const text = readFileSync(path, "utf8");
 					const offset = params.offset ?? 0;
 					if (offset && offset >= text.length) {
 						throw new Error(`Offset ${offset} is past the end of ${relative} (${text.length} chars).`);
 					}
-					const end = Math.min(text.length, offset + pageSize(nativeContext(ctx), offset, 0));
+					const end = Math.min(text.length, offset + pageSize(policy(ctx), offset, 0));
 					const more =
 						end < text.length ? `\n[chars ${offset}-${end} of ${text.length}; continue with offset ${end}]` : "";
 					return pageResult(`${text.slice(offset, end)}${more}`, [], { kind: "note-read", offset, end, total: text.length });
@@ -1008,7 +1360,7 @@ export default function (pi: ExtensionAPI) {
 					if (params.content === undefined) throw new Error(`"content" is required for op "write" (use "" to clear a note).`);
 					const path = safeJoin(relative);
 					mkdirSync(dirname(path), { recursive: true });
-					await publishLocalFile(path, params.content, signal);
+					await withFileMutationQueue(path, () => publishFile(path, params.content!, signal));
 					return textResult(`Wrote ${path}`, [], { kind: "note-write" });
 				}
 				case "append": {
@@ -1019,26 +1371,30 @@ export default function (pi: ExtensionAPI) {
 					// One O_APPEND write per newline-terminated record, so concurrent Pi processes appending to a
 					// shared note never merge records. The separator only matters after a write that left no trailing
 					// newline; a torn read of another process's in-flight append costs at most one blank line.
-					const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
-					const separator = existing && !existing.endsWith("\n") ? "\n" : "";
-					appendFileSync(path, `${separator}${content.replace(/\n?$/, "\n")}`);
+					await withFileMutationQueue(path, async () => {
+						signal?.throwIfAborted();
+						const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
+						const separator = existing && !existing.endsWith("\n") ? "\n" : "";
+						appendFileSync(path, `${separator}${content.replace(/\n?$/, "\n")}`);
+					});
 					return textResult(`Appended to ${path}`, [], { kind: "note-append" });
 				}
 				case "search": {
 					const query = requireValue(params.query, "query", params.op).toLowerCase();
-					const files: string[] = [];
-					if (existsSync(dir)) walk(dir, files);
 					const hits: string[] = [];
-					for (const file of files) {
-						for (const [index, line] of readFileSync(file, "utf8").split("\n").entries()) {
+					for (const { path: file } of notesUnder(dir)) {
+						if (await isBinaryFile(file)) continue;
+						let number = 0;
+						for await (const line of lfLines(file, signal)) {
+							number++;
 							const trimmed = line.trim();
 							const match = trimmed.toLowerCase().indexOf(query);
 							if (match !== -1) {
-								hits.push(`${file.slice(dir.length + 1)}:${index + 1}: ${excerptAround(trimmed, match, 50, 200)}`);
+								hits.push(`${file.slice(dir.length + 1)}:${number}: ${excerptAround(trimmed, match, 50, 200)}`);
 							}
 						}
 					}
-					return notesPage(nativeContext(ctx), hits, params.offset ?? 0, "notes-search", `No notes match "${excerpt(params.query!, 200)}".`);
+					return notesPage(policy(ctx), hits, params.offset ?? 0, "notes-search", `No notes match "${excerpt(params.query!, 200)}".`);
 				}
 			}
 		},
@@ -1049,61 +1405,83 @@ export default function (pi: ExtensionAPI) {
 		label: "History",
 		...toolCards("history"),
 		description:
-			"Search or read normalized session entries, including earlier native context windows. Search prioritizes original content before recovery notes, handoffs, and history lookups; all remain searchable. Current branch by default; all=true searches every project session file. Within each group: newest-modified sessions first, newest entries per session. Continue searches with the returned cursor and the same query/scope; new searches see newer entries. Reads return stored images and page long text with the next offset.",
+			"Search or read earlier session entries, including previous context windows. search skips entries still in your active context and lists original content before recovery echoes, newest first; all=true also searches this project's other sessions and subagent runs. read takes an entry id exactly as search printed it and pages text and images.",
 		promptSnippet: "recover earlier conversation that left the active context window",
-		promptGuidelines: ["Use history search first, then history read with the returned entry id"],
+		promptGuidelines: ["Use history search first, then history read with the entry id exactly as printed"],
 		parameters: Type.Object({
 			op: Type.Union([Type.Literal("search"), Type.Literal("read")], { description: "Operation to perform" }),
 			query: Type.Optional(Type.String({ description: "Case-insensitive text to find (search)" })),
-			id: Type.Optional(Type.String({ description: "Entry id returned by search (read)" })),
-			all: Type.Optional(Type.Boolean({ description: "Search all project sessions instead of the current branch" })),
+			id: Type.Optional(Type.String({ description: "Entry id exactly as search printed it (read)" })),
+			all: Type.Optional(Type.Boolean({ description: "Also search this project's other sessions and subagent runs" })),
 			limit: Type.Optional(Type.Integer({ description: "Maximum search results per page (default 10, max 50)", minimum: 1, maximum: 50 })),
-			cursor: Type.Optional(Type.String({ description: "Search continuation returned by the previous page; keep query and all unchanged", maxLength: 512 })),
+			cursor: Type.Optional(Type.String({ description: "Continuation from the previous search page; keep query and all unchanged", maxLength: 512 })),
 			offset: Type.Optional(Type.Integer({ description: "Character offset for read (default 0)", minimum: 0 })),
+			imageOffset: Type.Optional(Type.Integer({ description: "First image to return (read); use the value from the continuation", minimum: 0 })),
 		}),
 		async execute(_id, params, signal, _onUpdate, ctx) {
 			const manager = ctx.sessionManager;
+			const cwd = resolve(ctx.cwd);
+			const currentFile = manager.getSessionFile?.();
+			const dir = manager.getSessionDir();
 
 			if (params.op === "search") {
 				const query = requireValue(params.query, "query", params.op).toLowerCase();
 				const limit = params.limit ?? 10;
-				const searchKey = createHash("sha256").update(JSON.stringify([query, params.all === true])).digest("base64url");
+				const searchKey = shortKey(JSON.stringify([query, params.all === true]));
+				// Projections show replacements and stripped async calls under the original id, so an entry is in
+				// context only when all of its own text is visible there. Posthorse strips stale reminders from input.
+				const seen = (message: MessageLike) => [
+					textOf(message), assistantFailure(message), imageSummary(imagesOf(message.content)), message.summary, message.command, message.output,
+				].filter(Boolean).join("\n").toLowerCase();
+				const visible = new Map((manager.buildSessionProjection().entries as readonly ProjectedEntry[]).flatMap(({ sourceEntry, messages }) =>
+					sourceEntry.id && messages.length ? [[sourceEntry.id, messages.map(seen).join("\n")] as const] : []));
+				const inContext = (entry: EntryLike) => {
+					if (entry.type === "custom_message" && isReminderType(entry.customType)) return false;
+					const own = entry.type === "message" ? entry.message ?? {}
+						: entry.type === "context_edit" ? { content: entry.replacement?.content }
+						: entry.type === "context_window" ? { content: entry.handoff }
+						: { content: entry.content, summary: entry.summary };
+					return visible.get((entry.type === "context_edit" ? entry.targetId : entry.id) ?? "")?.includes(seen(own)) === true;
+				};
+				let skipped = 0;
 				let cursor: [string, 0 | 1, number, string] | undefined;
 				if (params.cursor) {
 					try {
 						const value = JSON.parse(Buffer.from(params.cursor, "base64url").toString());
 						if (!Array.isArray(value) || value.length !== 4 || typeof value[0] !== "string" || !value[0] || ![0, 1].includes(value[1]) || !Number.isSafeInteger(value[2]) || value[2] < 0 || value[3] !== searchKey) throw new Error();
 						cursor = value as typeof cursor;
-					} catch { pageError(nativeContext(ctx), "Invalid history cursor or changed query/scope; restart the search without it.", params.cursor); }
+					} catch { pageError(policy(ctx), "Invalid history cursor or changed query/scope; restart the search without it.", params.cursor); }
 				}
 				const hits: HistoryHit[][] = [[], []];
-				// Mark skipped ids too: fork copies must not reappear on subsequent pages.
-				const seen = new Set<string>();
 				let found = !cursor;
 				const addHit = (hit: HistoryHit | undefined) => {
-					if (!hit || seen.has(hit.id)) return;
-					seen.add(hit.id);
+					if (!hit) return;
 					if (cursor && hit.priority < cursor[1]) return;
 					if (cursor && hit.priority === cursor[1] && !found) {
 						if (hit.id !== cursor[0]) return;
 						found = true;
-						if (cursor[2] > hit.text.length) pageError(nativeContext(ctx), "History cursor is past the entry; restart the search without it.", params.cursor);
+						if (cursor[2] > hit.text.length) pageError(policy(ctx), "History cursor is past the entry; restart the search without it.", params.cursor);
 						if (cursor[2] === hit.text.length) return;
 					}
 					if (hits[hit.priority].length <= limit) hits[hit.priority].push(hit);
 				};
 
 				if (params.all) {
-					for (const file of sessionFiles(manager.getSessionDir())) {
+					const needles = prefilterNeedles(query);
+					const candidates = needles && await filesContaining(dir, needles, signal);
+					const current = currentFile && resolve(currentFile);
+					for await (const file of scopedSessionFiles(dir, cwd, currentFile, signal, { candidates })) {
 						const recent: HistoryHit[][] = [[], []];
-						const matchedIds = new Set<string>();
 						let anchorHere = false;
-						const source = relative(manager.getSessionDir(), file);
+						const source = relative(dir, file);
+						const inCurrent = resolve(file) === current;
 						for await (const item of sessionWindowEntries(file, signal)) {
-							if (seen.has(item.entry.id!)) continue;
 							const hit = historyHit(item, query, source);
 							if (!hit) continue;
-							matchedIds.add(hit.id);
+							if (inCurrent && inContext(item.entry)) {
+								skipped++;
+								continue;
+							}
 							const seeking = cursor && !found && hit.priority === cursor[1];
 							if (seeking && anchorHere) continue;
 							if (seeking && hit.id === cursor?.[0]) anchorHere = true;
@@ -1114,26 +1492,34 @@ export default function (pi: ExtensionAPI) {
 						}
 						if (cursor && !found && !anchorHere) recent[cursor[1]] = [];
 						for (const group of recent) for (const hit of group.reverse()) addHit(hit);
-						for (const id of matchedIds) seen.add(id);
 						if (hits[0].length > limit) break;
 					}
 				} else {
 					const current = [...windowEntries(manager.getBranch() as EntryLike[])];
 					for (const item of current.reverse()) {
-						addHit(historyHit(item, query));
+						const hit = historyHit(item, query);
+						if (!hit) continue;
+						if (inContext(item.entry)) {
+							skipped++;
+							continue;
+						}
+						addHit(hit);
 						if (hits[0].length > limit) break;
 					}
 				}
-				const chars = pageSize(nativeContext(ctx), 0, 0, params.cursor);
-				if (!found) pageError(nativeContext(ctx), "History cursor entry no longer matches; restart the search without it.", params.cursor);
+				const chars = pageSize(policy(ctx), 0, 0, params.cursor);
+				if (!found) pageError(policy(ctx), "History cursor entry no longer matches; restart the search without it.", params.cursor);
 				const results = hits.flat();
 				const cursorFor = (hit: HistoryHit, offset: number) => Buffer.from(JSON.stringify([hit.id, hit.priority, offset, searchKey])).toString("base64url");
 				const footer = (next: string) => `\n[More results; continue with cursor "${next}" and the same query/scope.]`;
 				const reserve = Math.max(0, ...results.map((hit) => footer(cursorFor(hit, hit.text.length)).length));
-				if (reserve >= chars) pageError(nativeContext(ctx), "History entry id is too large for pagination.", params.cursor);
+				if (reserve >= chars) pageError(policy(ctx), "History entry id is too large for pagination.", params.cursor);
+				const skippedNote = skipped && !params.cursor
+					? `\n[Skipped ${skipped} match${skipped === 1 ? "" : "es"} already in your active context.]`
+					: "";
 				const parts: string[] = [];
 				const spans: Array<{ headerLength: number; length: number }> = [];
-				let available = chars - reserve;
+				let available = chars - reserve - skippedNote.length;
 				let next: string | undefined;
 				for (const hit of results) {
 					const offset = cursor?.[0] === hit.id ? cursor[2] : 0;
@@ -1150,39 +1536,62 @@ export default function (pi: ExtensionAPI) {
 					if (available <= 0 || parts.length >= limit) break;
 				}
 				const body = parts.length ? parts.join("\n") : `No history matches "${excerpt(params.query!, 200)}".`;
-				const more = next ? footer(next) : "";
-				return pageResult(body + more, [], { kind: "history-search", entries: spans, footerLength: more.length });
+				const tail = `${skippedNote}${next ? footer(next) : ""}`;
+				return pageResult(body + tail, [], { kind: "history-search", entries: spans, footerLength: tail.length, more: next !== undefined, skipped });
 			}
 
 			const id = requireValue(params.id, "id", params.op);
+			const separator = id.indexOf("@");
+			const entryId = separator < 0 ? id : id.slice(0, separator);
+			const fileKey = separator < 0 ? undefined : id.slice(separator + 1);
 			const formatEntry = (item: WindowedEntry, source = "") => {
+				// Session-file reads print the qualified id, so continuations reopen the same file.
+				const shownId = source ? `${item.entry.id}@${shortKey(source)}` : id;
 				const offset = params.offset ?? 0;
-				if (offset >= item.text.length) {
+				const imageOffset = params.imageOffset ?? (offset === 0 ? 0 : item.images.length);
+				if (imageOffset > item.images.length) {
+					throw new Error(`Image offset ${imageOffset} is past the end of history entry "${id}" (${item.images.length} images).`);
+				}
+				if (offset > item.text.length || (offset === item.text.length && imageOffset === item.images.length)) {
 					throw new Error(`Offset ${offset} is past the end of history entry "${id}" (${item.text.length} chars).`);
 				}
+				// Reserve one image first so an image-only continuation either advances or asks for fresh context.
+				const firstImage = imageOffset < item.images.length ? 1 : 0;
+				const chars = pageSize(policy(ctx), offset, firstImage, undefined, item.images.length ? imageOffset : undefined);
+				const imageEnd = Math.min(item.images.length, imageOffset + firstImage + Math.floor((chars - MIN_PAGE_CHARS) / ESTIMATED_IMAGE_CHARS));
+				const images = item.images.slice(imageOffset, imageEnd);
 				const end = Math.min(
 					item.text.length,
-					offset + pageSize(nativeContext(ctx), offset, offset === 0 ? item.images.length : 0),
+					offset + chars - (images.length - firstImage) * ESTIMATED_IMAGE_CHARS,
 				);
-				const more = end < item.text.length ? `\nMore remains; call history read with id "${id}" and offset ${end}.` : "";
-				const header = `${source ? `${source} ` : ""}${item.entry.timestamp ?? ""} [window ${item.windowId}] [${id}] [chars ${offset}-${end} of ${item.text.length}] `;
-				// Stored images ride along with the first page only.
+				const more = end < item.text.length || imageEnd < item.images.length
+					? `\nMore remains; call history read with id "${shownId}" and offset ${end}${item.images.length ? ` and imageOffset ${imageEnd}` : ""}.` : "";
+				const header = `${item.entry.timestamp ?? ""}${sourceTag(source)} [window ${item.windowId}] [${shownId}] [chars ${offset}-${end} of ${item.text.length}] `;
 				return pageResult(
 					`${header}${item.text.slice(offset, end)}${more}`,
-					offset === 0 ? item.images : [],
-					{ kind: "history-read", headerLength: header.length, offset, end, total: item.text.length },
+					images,
+					{ kind: "history-read", headerLength: header.length, offset, end, total: item.text.length, imageOffset, imageEnd, imageTotal: item.images.length },
 				);
 			};
 
-			for (const item of windowEntries(manager.getBranch() as EntryLike[])) {
-				if (item.entry.id === id) return formatEntry(item);
+			if (fileKey === undefined) {
+				for (const item of windowEntries(manager.getBranch() as EntryLike[])) {
+					if (item.entry.id === entryId) return formatEntry(item);
+				}
 			}
-			for (const file of sessionFiles(manager.getSessionDir())) {
+			// Bare ids from other sessions reach here through older notes and handoffs.
+			const candidates = fileKey === undefined && /^[\w-]+$/.test(entryId)
+				? await filesContaining(dir, [`"id":"${entryId}"`], signal)
+				: undefined;
+			for await (const file of scopedSessionFiles(dir, cwd, currentFile, signal, { fileKey, candidates })) {
+				const fileSource = relative(dir, file);
 				for await (const item of sessionWindowEntries(file, signal)) {
-					if (item.entry.id === id) return formatEntry(item, relative(manager.getSessionDir(), file));
+					if (item.entry.id === entryId) return formatEntry(item, fileSource);
 				}
 			}
-			throw new Error(`No history entry with id "${id}".`);
+			throw new Error(`No history entry "${id}" in this session or this project's other sessions. Pass an id exactly as history search prints it, such as 1a2f07de, or 1a2f07de@Ab3dE5fG7h from another session; search first when you only have text or a timestamp.`);
 		},
 	});
-}
+};
+
+export default createPosthorse();