pi-posthorse 0.4.6 → 0.5.0

package/README.md

@@ -13,7 +13,7 @@ An isolated [Codex prototype](adapters/codex-posthorse/README.md) tests local no
 ## Requirements
 
 - Node `>=22.19.0`.
-- The `fitchmultz/pi` fork. The CI baseline is `f9b06177e565f70cd243a785d088d1c491830dbd` (Pi `0.85.0`). Posthorse needs the fork's native `context_window` entries, its `session_before_auto_compact` hook, and `ctx.getCompactionSettings()`.
+- The `fitchmultz/pi` fork. The native qualification target is `8fb7886130ff1fedc415bdd6fea03aef8a8957d8` (fork package version `0.87.0`). Posthorse needs the fork's native `context_window` entries, its `session_before_auto_compact` hook, `ctx.getCompactionSettings()`, and the coding-agent SDK's `publishLocalFile` export.
 - Official, unpatched Pi is unsupported. Posthorse reports a clear extension error at session start and cannot operate; Pi itself keeps running.
 
 ## Install
@@ -23,7 +23,7 @@ Build the fork:
 ```bash
 git clone https://github.com/fitchmultz/pi.git
 cd pi
-git checkout f9b06177e565f70cd243a785d088d1c491830dbd
+git checkout 8fb7886130ff1fedc415bdd6fea03aef8a8957d8
 npm install --ignore-scripts
 npm run build
 ```
@@ -48,15 +48,15 @@ Keep exactly one copy loaded. `pi list` shows every package source; if an older
 
 ## How it works
 
-1. **Stable guidance.** Window behavior is part of the system prompt. There is no per-request meter to churn the prompt.
-2. **One best-effort checkpoint.** While Pi compaction is enabled, one reminder may appear shortly before Pi's rollover line. A large turn, overflow, restart, or smaller model can reach rollover without it. Reminders are fingerprinted by window, context size, and reserve, so switching to a different context size gets a fresh reminder and stale ones are filtered from model input.
-3. **`get_context_remaining`.** Reports the best available native estimate of tokens until Pi's automatic rollover line and until the model's hard limit. Pi's value is an estimate until the active model reports usage.
+1. **Stable guidance.** Window behavior lives in a native system-prompt section. There is no per-request meter. Posthorse preserves custom prompts and falls back to appending guidance when an earlier extension replaces the full prompt; that compatibility path can prevent Pi from preserving an additive prompt prefix.
+2. **One best-effort checkpoint.** While Pi compaction is enabled, one reminder may appear shortly before Pi's rollover line. A large turn, overflow, restart, or smaller model can reach rollover without it. Reminders are fingerprinted by window, context size, and reserve, so switching to a different context size gets a fresh reminder. Stale reminders and reminders left after disabling compaction are filtered from model input while remaining in history.
+3. **`get_context_remaining`.** Reports the best available native estimate of tokens until Pi's automatic rollover line and until the configured context limit. That configured limit is not a measured provider rejection boundary. Pi's value is an estimate until the active model reports usage.
 4. **`new_context`.** Requests an atomic rollover after the complete tool batch succeeds. An optional handoff is persisted and becomes the first state of the fresh window. If a sibling tool in the same batch fails, Pi does not commit the boundary; the checkpoint reminder still applies.
 5. **Automatic rollover without summaries.** With a supported context budget and room for a recovery record, Posthorse claims Pi's automatic threshold and overflow trigger through `session_before_auto_compact`, before Pi resolves summarization credentials or prepares a summary. Oversized first turns and tool results can then roll over even without summarization credentials. Otherwise Pi's own compaction remains in control. Manual `/compact` is unchanged.
-6. **Bounded recovery record.** The automatic handoff keeps direct user inputs, `ask_question` outcomes, visible coordination messages, and the trailing tool batch that no model has consumed yet (call arguments, bounded result text, and the entry ids to recover the rest). A clearly labeled, possibly stale older checkpoint comes last, after the current inputs and unseen results. Older assistant prose and consumed tool results are not treated as state. Newly submitted input stays separate and is saved after the boundary, not copied into the handoff.
+6. **Bounded recovery record.** The automatic handoff keeps direct user inputs, `ask_question` outcomes, visible coordination messages, and the trailing tool batch without a later complete assistant response: call arguments, bounded result text, and entry ids to recover the rest. Failed or interrupted requests may already have received those results. A clearly labeled, possibly stale older checkpoint comes last. Older assistant prose and earlier tool batches are not treated as current state. Newly submitted input stays separate and is saved after the boundary, not copied into the handoff.
 7. **`notes` and `history`.** Notes are shared across linked worktrees, at the main checkout for conventional Git layouts or inside the common Git directory when metadata is stored separately. History searches normalized transcript text and returns stored images for a requested entry.
 
-At turn end, Posthorse checks whether usage is in the reminder band before explicitly looking up the full branch. Context filtering skips its branch lookup when model input contains neither `posthorse-reminder` nor legacy `headroom-reminder` messages. History searches, reads, and recovery remain available with no new limits.
+At turn end, Posthorse checks whether usage is in the reminder band before explicitly looking up the full branch. Context filtering skips its branch lookup when model input contains neither `posthorse-reminder` nor legacy `headroom-reminder` messages. Complete history remains available through paged searches and reads.
 
 Automatic recovery is an emergency input record, not proof of progress. The fresh model is told to restore notes and todo state, inspect history when needed, and verify live state before taking stateful or external action.
 
@@ -74,21 +74,23 @@ Only one automatic compaction or rollover policy extension should be enabled at
 
 - `new_context({ handoff? })`
 - `get_context_remaining()`
-- `notes({ op, ... })`: `list`, `read` (paged; `offset` continues), `write` (empty content clears), `append` (one atomic newline-terminated record), `search` (excerpts centered on the match)
-- `history({ op, ... })`: `search`, `read`; results carry native window ids, reads return stored images with the first page and the next character offset when text remains
+- `notes({ op, ... })`: `list`, `read`, and `search` are paged; continue with the returned character `offset`. Search excerpts center on the match. `write` replaces content (empty content clears); `append` adds one newline-terminated record.
+- `history({ op, ... })`: `search` continues with the returned `cursor` and the same `query` and `all` scope; `limit` is the maximum results per page. `read` returns stored images with the first page and the next character `offset` when text remains. Results keep native entry and window ids.
 
 In the TUI, tools use Pi's native expandable cards. Collapsed cards show the operation and target, a short content preview, and counts or page ranges with the next offset when more remains. Expand with Pi's tool-output shortcut (`Ctrl+O` by default), or click the card's header or body in fullscreen mode. Expanded cards show the complete returned page and its metadata, not content the tool has not fetched yet. Writes and context requests also show the submitted content or handoff.
 
 Committed context-window messages and checkpoint reminders are compact, expandable cards too. The `new_context` tool card describes a request; only the committed context-window message says a fresh window has started.
 
-Read pages, including returned images, shrink to the context that is actually left. Parallel note and history reads share that budget; pages already counted by Pi are not counted twice. Before usage is known, they reserve prompt/tool overhead and leave half the rest free. Unsafe pages are refused with the offset preserved in the call; call `new_context` and retry. Refusal text uses the same budget, so later failures omit repeated guidance once no more fits.
+Notes list/search and history search share the remaining context budget with read pages and returned images. Search/list headers, continuation text, no-match responses, and parallel sibling results count toward that budget; pages already counted by Pi are not counted twice. Before usage is known, pages reserve prompt/tool overhead and leave half the rest free. Unsafe pages are refused with the offset or cursor preserved in the call; call `new_context` and retry. Refusal text uses the same budget, so later failures omit repeated guidance once no more fits.
 
 `history search` puts matching original content before recovery material: handoffs, compaction and branch summaries, checkpoint reminders, and `notes`, `new_context`, and `history` calls/results. Ordinary prose or another tool call in the same assistant entry keeps its priority when that content matches. Every entry remains searchable; `history read` returns the complete normalized entry, including any recovery content omitted from a search excerpt.
 
-Within each group, current-branch matches are newest first. With `all: true`, Posthorse searches every session file in the active Pi session directory, newest-modified sessions first and newest entries within each session; this is not a global timestamp sort. The result limit applies after priority, so newer echoes cannot displace older original matches. Entries copied by a fork are reported once.
+Within each group, current-branch matches are newest first. With `all: true`, Posthorse searches every session file in the active Pi session directory, newest-modified sessions first and newest entries within each session; this is not a global timestamp sort. The per-page result limit applies after priority, so newer echoes cannot displace older original matches. Entries copied by a fork are reported once. Search cursors advance past the previous entry, including partial headers or excerpts, so appending lookup calls and results does not keep pagination alive forever. Searches are live: external session edits or file reordering can change results; start a new search to include newer sources.
 
 Notes live in `.pi/notes/` at the main checkout for conventional Git layouts, or the current directory outside Git. When Git metadata is stored separately, including in submodules, all checkouts use `.pi/notes/` inside Git's common directory instead; no configuration is needed. If that metadata is unavailable, notes stay local to the checkout. Old checkout-local notes are imported when that checkout is accessed, without overwriting shared files or deleting the originals. Writes report the actual storage path. Add `.pi/notes/` to `.gitignore` when the project should not track it.
 
+`write` uses Pi's native complete-file replacement: a failed write before publication leaves the previous note intact. It follows symlink targets and preserves ordinary permissions and ownership, or fails before publication. Hardlink aliases and already-open handles keep the previous file; ACLs, extended attributes, and power-loss durability are not guaranteed. Full replacements do not merge concurrent appends or other replacements. `append` retains one `O_APPEND` write per newline-terminated record.
+
 ## Data and privacy
 
 - Posthorse makes no network requests.
@@ -105,10 +107,15 @@ Reminders persisted by pi-headroom (`headroom-reminder`) are recognized alongsid
 ## Develop
 
 ```bash
-npm ci
-npm test
-npm run check
-PI_FORK=../pi scripts/integration.sh   # loads the real extension into the fork's test harness (fork built)
+npm ci --ignore-scripts
+npm run check  # public npm declarations can check types, but cannot run Posthorse
+# After the compatibility runner installs the selected fork SDK/types cohort:
+PI_COMPAT_HOST=fork npm run check:compat
+PI_FORK=../pi scripts/integration.sh   # additional full source-harness integration (disposable fork built)
 ```
 
-`npm run check` type-checks the extension, renderers, and tests. Tests cover reminder policy, notes/history behavior, and real native card components, including width, expansion, and legacy results. The pinned Pi 0.85.0 SDK's unbundled entry imports an undeclared server package, so test-only resolution loads its shipped native bundle. Integration tests run inside the fork's harness and cover rollover and history recovery; use a disposable built fork checkout because the script briefly copies the test into its test directory. CI runs the unit tests on Node 22.19 and 24, `npm audit`, `npm pack --dry-run`, and the integration job against the pinned fork revision.
+`npm run check` type-checks the extension, renderers, and tests against the exact 0.87.0 npm declaration baseline. Runtime tests require the qualified fork SDK, including `publishLocalFile`, installed in this checkout's dependency graph. `npm test` covers reminder policy, notes/history behavior, failed note replacement, and real native card components, including width, expansion, and legacy results. Tests use the public SDK entry; official Pi is not an operating target.
+
+`check:compat` adds `test:native`: real SDK loading, prompt composition, mixed recovery-output budgets, cursor progress, reminder filtering, interrupted-response recovery, oversized-result rollover without summary compaction, explicit `new_context`, and checkpoint restore without provider replay. It requires native fork capabilities; it never substitutes synthetic windows or silently skips on official. The runner must install the fork cohort in this checkout's `node_modules` so both `tsc` and SDK imports resolve that graph. `PI_HOST_INDEX` and `PI_COMPAT_EXPECTED_PACKAGE_DIR` are verified against it, and `PI_COMPAT_EXPECTED_VERSION` verifies the version. A same-version official graph is not a fork. Official qualification is a separate actual CLI startup/refusal probe, not `check:compat`.
+
+For a focused read-only SDK diagnostic only, `PI_HOST_INDEX=/absolute/fork/dist/index.js node --test test/native.test.mjs` can inspect an immutable host; this does not qualify this checkout's types. The larger source integration suite remains available through `scripts/integration.sh`; use a disposable built fork checkout because it briefly copies a test into that host. All native fixtures must use an isolated HOME/agent directory with offline mode and no provider credentials. These checks do not claim native Windows support.

package/index.ts

@@ -6,6 +6,7 @@
  * notes, and history recovery.
  */
 
+import { createHash } from "node:crypto";
 import {
 	appendFileSync,
 	constants,
@@ -17,15 +18,15 @@ import {
 	readFileSync,
 	realpathSync,
 	statSync,
-	writeFileSync,
 } from "node:fs";
 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 { Type } from "typebox";
 import { registerPosthorseMessages, toolCards, type PosthorseDisplay } from "./ui.ts";
 
 const REMINDER_BUFFER_TOKENS = 32_000;
-/** Absolute ceiling for handoffs and read pages; pages shrink to the live remaining budget. */
+/** Absolute ceiling for handoffs and recovery pages; pages shrink to the live remaining budget. */
 const MAX_HANDOFF_CHARS = 20_000;
 const MAX_RECOVERY_RECORD_CHARS = 4_000;
 const HANDOFF_OVERHEAD_RESERVE = 1_000;
@@ -43,6 +44,11 @@ const LEGACY_AUTO_HANDOFF_PREFIX =
 
 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 = {
 	model?: { contextWindow: number };
@@ -113,9 +119,10 @@ function nativeContext<T>(ctx: T): T & NativeContext {
 	if (
 		typeof candidate.newContext !== "function" ||
 		typeof candidate.getCompactionSettings !== "function" ||
-		typeof candidate.getSystemPrompt !== "function"
+		typeof candidate.getSystemPrompt !== "function" ||
+		typeof publishLocalFile !== "function"
 	) {
-		throw new Error("Posthorse requires the fitchmultz/pi fork with native context windows (see README).");
+		throw new Error("Posthorse requires the fitchmultz/pi fork with native context windows and publishLocalFile (see README).");
 	}
 	return candidate as T & NativeContext;
 }
@@ -441,12 +448,8 @@ function formatPriorCheckpoint(entry: EntryLike | undefined, limit: number): str
 	return boundedBlock(header, handoff, limit);
 }
 
-/**
- * The trailing tool batch no model has consumed yet: an assistant tool-call message followed only by
- * its completed results (and non-message entries). Pi can roll over right after tools finish, so the
- * result that triggered the rollover would otherwise vanish before any model saw it.
- */
-function unconsumedToolBatch(
+/** Trailing results without a later complete assistant response; interrupted requests may have received them. */
+function trailingToolBatch(
 	entries: readonly EntryLike[],
 ): { callId: string; blocks: Array<{ header: string; text: string }> } | undefined {
 	const results: EntryLike[] = [];
@@ -520,9 +523,9 @@ 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 = unconsumedToolBatch(current);
+	const toolBatch = trailingToolBatch(current);
 	const batchHeader = toolBatch
-		? `Unconsumed tool batch (completed after the last assistant response; no model has seen these results). Tool-call entry ${toolBatch.callId}:`
+		? `Trailing tool batch without a later complete assistant response (failed or interrupted requests may already have received these results). Tool-call entry ${toolBatch.callId}:`
 		: undefined;
 	const minimumParts = [
 		preamble,
@@ -678,7 +681,7 @@ function unsupportedMessage(budget: Budget): string {
 	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.`;
 }
 
-/** Capacity before Pi's automatic line (or hard limit), including the margin for page metadata and refusals. */
+/** Capacity before Pi's automatic line (or configured context limit), including page metadata and refusals. */
 function pageCapacity(ctx: NativeContext, toolTokens: number): number {
 	const usage = ctx.getContextUsage();
 	if (!usage || usage.tokens == null) return freshPayloadChars(ctx, toolTokens) / 4 + PAGE_MARGIN_TOKENS;
@@ -729,7 +732,7 @@ export default function (pi: ExtensionAPI) {
 
 	let pendingPageTokens = 0;
 	let previousPageUsage: number | null | undefined;
-	const pageSize = (ctx: NativeContext, offset: number, imageCount: number) => {
+	const pageSize = (ctx: NativeContext, offset: number, imageCount: number, cursor?: string) => {
 		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) {
@@ -742,7 +745,7 @@ export default function (pi: ExtensionAPI) {
 			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 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}`}.`;
 			// 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 : "";
@@ -755,6 +758,30 @@ 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 => {
+		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 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.");
+		// Reserve the complete continuation, even when one path or excerpt needs several pages.
+		const footer = (end: number) => `\n[chars ${offset}-${end} of ${text.length}; continue with offset ${end}]`;
+		let end = Math.min(text.length, offset + chars);
+		let start = 0;
+		const starts: number[] = [];
+		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; }
+		}
+		// 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);
+		return pageResult(text.slice(offset, end) + (end < text.length ? footer(end) : ""), [], { kind, count: starts.filter((start) => start < end).length, page: { offset, end, total: text.length } });
+	};
 	pi.on("turn_start", () => {
 		pendingPageTokens = 0;
 		previousPageUsage = undefined;
@@ -766,9 +793,14 @@ export default function (pi: ExtensionAPI) {
 		nativeContext(ctx);
 	});
 
-	pi.on("before_agent_start", (event, ctx) => ({
-		systemPrompt: `${event.systemPrompt}\n\n${buildGuidance(nativeContext(ctx))}`,
-	}));
+	pi.on("before_agent_start", (event, ctx) => {
+		const guidance = buildGuidance(nativeContext(ctx));
+		// An earlier full-prompt override makes section edits invisible to Pi.
+		if (event.systemPromptOptions.forceSystemPrompt !== undefined) {
+			return { systemPrompt: `${event.systemPrompt}\n\n${guidance}` };
+		}
+		event.systemPromptOptions.sections.posthorse = guidance;
+	});
 
 	pi.on("turn_end", (event, ctx) => {
 		const native = nativeContext(ctx);
@@ -810,7 +842,7 @@ export default function (pi: ExtensionAPI) {
 		);
 	});
 
-	// Drop reminders from another window or computed for another context size/reserve from model input.
+	// 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",
@@ -829,7 +861,7 @@ export default function (pi: ExtensionAPI) {
 		const stale = (message: (typeof event.messages)[number]) =>
 			message.role === "custom" &&
 			isReminderType(message.customType) &&
-			reminderIsStale(message.customType, message.details, fingerprint, branch);
+			(!native.getCompactionSettings().enabled || reminderIsStale(message.customType, message.details, fingerprint, branch));
 		if (event.messages.some(stale)) return { messages: event.messages.filter((message) => !stale(message)) };
 	});
 
@@ -889,7 +921,7 @@ 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 model's hard limit.",
+			"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",
 		parameters: Type.Object({}),
 		async execute(_id, _params, _signal, _onUpdate, ctx) {
@@ -903,11 +935,11 @@ export default function (pi: ExtensionAPI) {
 				rollover: !budget?.enabled ? "disabled" : budget.supported ? "enabled" : "unsupported",
 				rolloverAt: budget?.rolloverAt,
 			};
-			const hard = `≈${n(Math.max(0, usage.contextWindow - usage.tokens))} tokens until the hard 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). ${hard}`, [], display);
-			if (!budget.supported) return textResult(`${unsupportedMessage(budget)} ${hard}`, [], 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.`;
+			if (!budget?.enabled) return textResult(`Automatic rollover is disabled (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)}); ${hard}`,
+				`≈${n(Math.max(0, budget.rolloverAt - usage.tokens))} tokens until automatic rollover (line at ${n(budget.rolloverAt)}); ${configured}`,
 				[], display,
 			);
 		},
@@ -918,7 +950,7 @@ export default function (pi: ExtensionAPI) {
 		label: "Notes",
 		...toolCards("notes"),
 		description:
-			"Persistent notes in .pi/notes/ that survive context resets. Ops: list, read (paged; pass offset to continue), write (create/replace; empty content clears), append, search (case-insensitive substring 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.",
+			"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.",
 		promptSnippet: "save and recall durable state that survives context resets",
 		promptGuidelines: [
 			"Use notes for durable state too large for a new_context handoff",
@@ -932,9 +964,9 @@ export default function (pi: ExtensionAPI) {
 			path: Type.Optional(Type.String({ description: "Note path relative to .pi/notes/ (read/write/append)" })),
 			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 read (default 0)", minimum: 0 })),
+			offset: Type.Optional(Type.Integer({ description: "Character offset for list/read/search (default 0)", minimum: 0 })),
 		}),
-		async execute(_id, params, _signal, _onUpdate, ctx) {
+		async execute(_id, params, signal, _onUpdate, ctx) {
 			const dir = join(notesRoot(ctx.cwd), ".pi", "notes");
 			const safeJoin = (path: string) => {
 				const relative = normalize(path.replace(/^[/\\]+/, ""));
@@ -953,10 +985,9 @@ export default function (pi: ExtensionAPI) {
 
 			switch (params.op) {
 				case "list": {
-					if (!existsSync(dir)) return textResult("(no notes yet)", [], { kind: "notes-list", count: 0 });
 					const files: string[] = [];
-					walk(dir, files);
-					return textResult(files.length ? files.map((file) => file.slice(dir.length + 1)).join("\n") : "(no notes yet)", [], { kind: "notes-list", count: files.length });
+					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 "read": {
 					const relative = requireValue(params.path, "path", params.op);
@@ -977,7 +1008,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 });
-					writeFileSync(path, params.content);
+					await publishLocalFile(path, params.content, signal);
 					return textResult(`Wrote ${path}`, [], { kind: "note-write" });
 				}
 				case "append": {
@@ -995,13 +1026,11 @@ export default function (pi: ExtensionAPI) {
 				}
 				case "search": {
 					const query = requireValue(params.query, "query", params.op).toLowerCase();
-					if (!existsSync(dir)) return textResult("(no notes yet)", [], { kind: "notes-search", count: 0 });
 					const files: string[] = [];
-					walk(dir, files);
+					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()) {
-							if (hits.length >= 20) break;
 							const trimmed = line.trim();
 							const match = trimmed.toLowerCase().indexOf(query);
 							if (match !== -1) {
@@ -1009,7 +1038,7 @@ export default function (pi: ExtensionAPI) {
 							}
 						}
 					}
-					return textResult(hits.length ? hits.join("\n") : `No notes match "${params.query}".`, [], { kind: "notes-search", count: hits.length });
+					return notesPage(nativeContext(ctx), hits, params.offset ?? 0, "notes-search", `No notes match "${excerpt(params.query!, 200)}".`);
 				}
 			}
 		},
@@ -1020,7 +1049,7 @@ 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. Reads return stored images and page long text with the next offset.",
+			"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.",
 		promptSnippet: "recover earlier conversation that left the active context window",
 		promptGuidelines: ["Use history search first, then history read with the returned entry id"],
 		parameters: Type.Object({
@@ -1028,7 +1057,8 @@ export default function (pi: ExtensionAPI) {
 			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" })),
-			limit: Type.Optional(Type.Integer({ description: "Maximum results (default 10, max 50)", minimum: 1, maximum: 50 })),
+			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 })),
 			offset: Type.Optional(Type.Integer({ description: "Character offset for read (default 0)", minimum: 0 })),
 		}),
 		async execute(_id, params, signal, _onUpdate, ctx) {
@@ -1037,42 +1067,91 @@ export default function (pi: ExtensionAPI) {
 			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");
+				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); }
+				}
 				const hits: HistoryHit[][] = [[], []];
-				// Forks copy ancestor entries under the same ids into new session files; report each id once.
+				// 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) || hits[hit.priority].length >= limit) return;
+					if (!hit || seen.has(hit.id)) return;
 					seen.add(hit.id);
-					hits[hit.priority].push(hit);
+					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) return;
+					}
+					if (hits[hit.priority].length <= limit) hits[hit.priority].push(hit);
 				};
 
 				if (params.all) {
 					for (const file of sessionFiles(manager.getSessionDir())) {
 						const recent: HistoryHit[][] = [[], []];
+						const matchedIds = new Set<string>();
+						let anchorHere = false;
 						const source = relative(manager.getSessionDir(), file);
 						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);
+							const seeking = cursor && !found && hit.priority === cursor[1];
+							if (seeking && anchorHere) continue;
+							if (seeking && hit.id === cursor?.[0]) anchorHere = true;
 							const group = recent[hit.priority];
 							group.push(hit);
-							if (group.length > limit - hits[hit.priority].length) group.shift();
+							// Keep one page plus its anchor and lookahead, not every matching excerpt.
+							if (group.length > limit + 2) group.shift();
 						}
+						if (cursor && !found && !anchorHere) recent[cursor[1]] = [];
 						for (const group of recent) for (const hit of group.reverse()) addHit(hit);
-						if (hits[0].length >= limit) break;
+						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));
-						if (hits[0].length >= limit) break;
+						if (hits[0].length > limit) break;
 					}
 				}
-				const results = hits.flat().slice(0, limit);
-				return textResult(results.length ? results.map((hit) => hit.text).join("\n") : `No history matches "${params.query}".`, [], {
-					kind: "history-search",
-					entries: results.map((hit) => ({ headerLength: hit.headerLength, length: hit.text.length })),
-				});
+				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 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);
+				const parts: string[] = [];
+				const spans: Array<{ headerLength: number; length: number }> = [];
+				let available = chars - reserve;
+				let next: string | undefined;
+				for (const hit of results) {
+					const offset = cursor?.[0] === hit.id ? cursor[2] : 0;
+					if (parts.length && hit.text.length - offset > available) break;
+					// A split header or excerpt must still identify the native entry on every page.
+					const prefix = offset || hit.text.length > available ? `[entry ${hit.id}; from char ${offset}] ` : "";
+					if (prefix.length >= available) break;
+					const end = Math.min(hit.text.length, offset + available - prefix.length);
+					const part = prefix + hit.text.slice(offset, end);
+					parts.push(part);
+					spans.push({ headerLength: prefix.length + Math.max(0, Math.min(hit.headerLength - offset, end - offset)), length: part.length });
+					available -= part.length + 1;
+					next = end < hit.text.length || parts.length < results.length ? cursorFor(hit, end) : undefined;
+					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 id = requireValue(params.id, "id", params.op);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-posthorse",
-	"version": "0.4.6",
+	"version": "0.5.0",
 	"type": "module",
 	"description": "Posthorse: fresh context, same journey. Native no-summary context windows for the fitchmultz/pi fork, with sparse budget reminders, handoffs, notes, and history.",
 	"keywords": ["pi-package", "pi-extension", "context", "posthorse", "rollover"],
@@ -19,6 +19,8 @@
 	},
 	"scripts": {
 		"check": "tsc --noEmit",
+		"check:compat": "npm run check && npm test && npm run test:native",
+		"test:native": "node --import ./test/pi-loader.ts --test test/native.test.mjs",
 		"test": "node --import ./test/pi-loader.ts --test test/*.test.ts",
 		"prepublishOnly": "npm test && npm run check"
 	},
@@ -39,8 +41,8 @@
 		}
 	},
 	"devDependencies": {
-		"@earendil-works/pi-coding-agent": "0.85.0",
-		"@earendil-works/pi-tui": "0.85.0",
+		"@earendil-works/pi-coding-agent": "0.87.0",
+		"@earendil-works/pi-tui": "0.87.0",
 		"typebox": "1.3.7",
 		"typescript": "^5.5.0"
 	}

package/ui.ts

@@ -4,10 +4,10 @@ import { Box, MouseRegion, Text, stripTerminalSequences, truncateToWidth, type C
 /** Display-only facts and offsets into content, never a second copy of a note or history page. */
 export type PosthorseDisplay =
 	| { kind: "context"; usage?: { tokens: number | null; contextWindow: number; percent: number | null }; rollover?: "enabled" | "disabled" | "unsupported"; rolloverAt?: number }
-	| { kind: "notes-list" | "notes-search"; count: number }
+	| { kind: "notes-list" | "notes-search"; count: number; page?: { offset: number; end: number; total: number } }
 	| { kind: "note-read"; offset: number; end: number; total: number }
 	| { kind: "note-write" | "note-append" | "new-context" }
-	| { kind: "history-search"; entries: Array<{ headerLength: number; length: number }> }
+	| { kind: "history-search"; entries: Array<{ headerLength: number; length: number }>; footerLength?: number }
 	| { kind: "history-read"; headerLength: number; offset: number; end: number; total: number };
 
 type ToolName = "notes" | "history" | "get_context_remaining" | "new_context";
@@ -43,14 +43,17 @@ function pageSummary(page: { offset: number; end: number; total: number }): stri
 function historySections(raw: string, display: PosthorseDisplay | undefined): Array<{ body: string; header: string }> | undefined {
 	const spans = display?.kind === "history-search" ? display.entries : display?.kind === "history-read" ? [{ headerLength: display.headerLength, length: raw.length }] : undefined;
 	if (!Array.isArray(spans) || !spans.length) return undefined;
+	const footerLength = display?.kind === "history-search" ? display.footerLength ?? 0 : 0;
+	if (!Number.isInteger(footerLength) || footerLength < 0 || footerLength > raw.length) return undefined;
+	const bodyLength = raw.length - footerLength;
 	let start = 0;
 	const sections: Array<{ body: string; header: string }> = [];
 	for (const span of spans) {
-		if (!Number.isInteger(span.headerLength) || !Number.isInteger(span.length) || span.headerLength < 0 || span.headerLength > span.length || start + span.length > raw.length) return undefined;
+		if (!Number.isInteger(span.headerLength) || !Number.isInteger(span.length) || span.headerLength < 0 || span.headerLength > span.length || start + span.length > bodyLength) return undefined;
 		sections.push({ header: raw.slice(start, start + span.headerLength).trimEnd(), body: raw.slice(start + span.headerLength, start + span.length) });
 		start += span.length + 1;
 	}
-	return start === raw.length + 1 ? sections : undefined;
+	return start === bodyLength + 1 ? sections : undefined;
 }
 
 export function toolCards(name: ToolName): Pick<ToolDefinition, "renderCall" | "renderResult"> {
@@ -88,22 +91,23 @@ export function toolCards(name: ToolName): Pick<ToolDefinition, "renderCall" | "
 					case "context": {
 						const usage = display.usage;
 						if (!usage || usage.tokens == null) { summary = "Context usage unknown"; break; }
-						const hard = `≈${n(Math.max(0, usage.contextWindow - usage.tokens))} tokens to hard limit`;
+						const configured = `≈${n(Math.max(0, usage.contextWindow - usage.tokens))} tokens to configured context limit`;
 						const rollover = display.rollover === "enabled" && display.rolloverAt !== undefined ? `≈${n(Math.max(0, display.rolloverAt - usage.tokens))} tokens to rollover` : `Automatic rollover ${display.rollover ?? "unknown"}`;
-						summary = `${rollover}\n${hard}\n≈${n(usage.tokens)} / ${n(usage.contextWindow)} used${usage.percent == null ? "" : ` (≈${Math.round(usage.percent)}%)`}`;
+						summary = `${rollover}\n${configured}\n≈${n(usage.tokens)} / ${n(usage.contextWindow)} used${usage.percent == null ? "" : ` (≈${Math.round(usage.percent)}%)`}`;
 						if (display.rollover === "unsupported") color = "warning";
 						break;
 					}
-					case "notes-list": summary = display.count ? `${n(display.count)} note${display.count === 1 ? "" : "s"}` : "No notes yet"; break;
+					case "notes-list": summary = display.count ? `${n(display.count)} note${display.count === 1 ? "" : "s"} returned` : "No notes yet"; break;
 					case "notes-search": summary = display.count ? `${n(display.count)} matches returned` : "No matches"; break;
 					case "note-read": summary = pageSummary(display); break;
 					case "note-write": summary = args.content === "" ? "Cleared note" : "Saved note"; break;
 					case "note-append": summary = "Appended to note"; break;
-					case "history-search": if (Array.isArray(display.entries) && (!display.entries.length || sections)) summary = `${display.entries.length ? `${n(display.entries.length)} matches` : "No matches"} · ${args.all === true ? "all sessions" : "current branch"}`; break;
+					case "history-search": if (Array.isArray(display.entries) && (!display.entries.length || sections)) summary = `${display.entries.length ? `${n(display.entries.length)} matches` : "No matches"} · ${args.all === true ? "all sessions" : "current branch"}${display.footerLength ? "\nMore results; continue with cursor" : ""}`; break;
 					case "history-read": summary = pageSummary(display); break;
 					case "new-context": summary = "Requested for after the whole tool batch succeeds."; break;
 				}
 			}
+			if (!context.isError && !isPartial && (display?.kind === "notes-list" || display?.kind === "notes-search") && display.page && (display.page.offset || display.page.end < display.page.total)) summary += `\n${pageSummary(display.page)}`;
 			if (!body.trim()) body = context.isError ? "No error details returned." : isPartial ? "Running…" : name === "notes" && args.op === "read" ? "Empty note" : "No text returned.";
 			const submitted = name === "new_context" && typeof args.handoff === "string" ? `Handoff supplied:\n${args.handoff}` : name === "notes" && (args.op === "write" || args.op === "append") && typeof args.content === "string" ? `Submitted content:\n${args.content || "(empty)"}` : "";
 			const images = Array.isArray(result.content) ? result.content.filter((part) => part.type === "image") : [];
@@ -121,7 +125,7 @@ export function toolCards(name: ToolName): Pick<ToolDefinition, "renderCall" | "
 				invalidate() {},
 				render(width) {
 					if (expanded) {
-						return [...fullText.render(width), ...attachmentText.render(width), ...(submitted ? ["", ...submittedText.render(width)] : [])];
+						return [...fullText.render(width), ...attachmentText.render(width), ...(sections && display?.kind === "history-search" && display.footerLength ? textBlock(raw.slice(-display.footerLength), theme, "muted").render(width) : []), ...(submitted ? ["", ...submittedText.render(width)] : [])];
 					}
 					const summaryRows = summaryText.render(width).slice(0, 5);
 					const previewRows = summaryOnly && !context.isError && !isPartial ? [] : searchPreviews