pi-posthorse 0.9.2 → 0.10.0

package/README.md

@@ -1,12 +1,12 @@
 # Posthorse
 
-Posthorse starts fresh context windows for long [Pi](https://github.com/earendil-works/pi) tasks and keeps earlier conversation recoverable. Each rollover uses a handoff or recovery record without a model-generated summary.
+Posthorse starts fresh context windows for long [Pi](https://github.com/earendil-works/pi) tasks without an automatic model-generated summary. Stock Pi already preserves the session journal and retains a recent tail during compaction; Posthorse adds explicit notes and history retrieval, with a handoff or bounded recovery record instead of the automatic summary.
 
 ![A Pi conversation rolls into a fresh context window. Task notes and the complete session transcript remain available.](.github/readme/context-rollover.png)
 
 ## Install and start
 
-Use Node 24.12.0 or later and Pi 1.0.0 or later. Posthorse supports official Pi and [fitchmultz/pi](https://github.com/fitchmultz/pi).
+Use Node 24.12.0 or later and Pi 1.3.0 or later. Posthorse supports official Pi and [fitchmultz/pi](https://github.com/fitchmultz/pi).
 
 Update an older Pi installation before you install Posthorse. Run these commands:
 
@@ -23,22 +23,24 @@ Give Pi your task. For example:
 
 ## How rollover works
 
-Posthorse can remind the model to save task state before rollover. Large turns can reach rollover before this reminder. The reminder does not wake an agent after its final answer.
+Posthorse can nudge the model to update task notes before rollover, then continue working. The nudge does not require `new_context` or wake an agent after its final answer. Large turns can reach rollover before the nudge.
 
-Automatic rollover creates a recovery record from session inputs and tool results. The model must restore notes and check live state before it continues. Manual `/compact` uses Pi's normal summarization.
+Automatic rollover retains a safe recent-message tail using Pi's `compaction.keepRecentTokens`, alongside a bounded recovery record for discarded inputs and tool evidence. It never calls a summarization model. The model must restore notes and check live state before it continues. Optional `new_context` deliberately retains no prior messages; manual `/compact` uses Pi's normal summarization.
 
-See [rollover and recovery details](docs/reference.md#how-it-works).
+Safe recent-tail retention and the notes-only reminder are part of the [0.10.0 changes](CHANGELOG.md#0100). Match these docs to your installed version using the changelog; default-branch documentation may describe changes not yet published.
+
+Recoverable history is not guaranteed model recall. See the [practical guarantees and limits](docs/context-recovery.md) for the stock-Pi comparison, search scope, checkpoints, privacy, concurrency and cost, or the [rollover reference](docs/reference.md#how-it-works) for implementation details.
 
 ## Tools
 
 These tools are available to the model:
 
-| Tool                        | Use                                                                                                                                          |
-| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| `new_context({ handoff? })` | Request a fresh window after every foreground tool succeeds. Aborted turns and failed tools prevent the reset.                               |
-| `get_context_remaining()`   | Estimate tokens left until rollover and the configured context limit. Usage can be unknown before a model response.                          |
-| `notes({ op, ... })`        | List, read, search, write, or append task notes.                                                                                             |
-| `history({ op, ... })`      | Search earlier conversation and read entries, including images. `all: true` includes this project's other sessions and nested subagent runs. |
+| Tool                        | Use                                                                                                                                                |
+| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `new_context({ handoff? })` | Optionally request a clean reset with no retained messages after every foreground tool succeeds. Aborted turns and failed tools prevent the reset. |
+| `get_context_remaining()`   | Estimate tokens left until rollover and the configured context limit. Usage can be unknown before a model response.                                |
+| `notes({ op, ... })`        | List, read, search, write, or append task notes.                                                                                                   |
+| `history({ op, ... })`      | Search earlier conversation and read entries, including images. `all: true` includes this project's other sessions and nested subagent runs.       |
 
 Expand a tool card with Ctrl+O. In fullscreen mode, click a tool card to expand it. A `new_context` card shows a request. Pi's `Compacted from … tokens` card confirms the rollover.
 
@@ -48,10 +50,11 @@ See [tool examples and paging details](docs/reference.md#tools).
 
 Posthorse uses Pi's effective `compaction` settings. It has no separate settings.
 
-| Pi setting                 | Effect                                                                                                                                                             |
-| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `compaction.enabled`       | Set to `false` to disable reminders and automatic rollover. `new_context` remains available.                                                                       |
-| `compaction.reserveTokens` | Automatic Posthorse rollover needs at least 10,000 tokens after this reserve. Smaller budgets use Pi's own compaction. Lower the reserve or choose a larger model. |
+| Pi setting                    | Effect                                                                                                                                                             |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `compaction.enabled`          | Set to `false` to disable reminders and automatic rollover. `new_context` remains available.                                                                       |
+| `compaction.reserveTokens`    | Automatic Posthorse rollover needs at least 10,000 tokens after this reserve. Smaller budgets use Pi's own compaction. Lower the reserve or choose a larger model. |
+| `compaction.keepRecentTokens` | Approximate recent tail for automatic rollover (Pi's default: 20,000). Zero keeps no messages. Tail size shrinks when safe groups cannot fit the fresh budget.     |
 
 Two Posthorse copies can register the same tools and compete for rollover. Keep one copy loaded. Check installed sources with `pi list`.
 
@@ -73,7 +76,7 @@ Removal leaves notes and Pi session history in place. See the [installation refe
 
 ## Data and privacy
 
-Posthorse makes no network requests. Notes are plaintext files under `.pi/notes/`; linked Git worktrees share them. Add `.pi/notes/` to `.gitignore` if the notes must stay private.
+Posthorse makes no network requests. Notes are plaintext files under `.pi/notes/`; linked Git worktrees share them. Notes for Pi-managed Git packages live outside their checkouts because `pi update` deletes untracked files there: global packages (including their descendants) use Pi's agent-directory `notes/`, and other project-local packages use the containing project's `.pi/package-notes/`, with project-local stores keyed by a full SHA-256 digest of the host and package path. Access existing checkout-local notes with this version before updating the package so they can migrate. Add `.pi/notes/` and `.pi/package-notes/` to the containing project's `.gitignore` if the notes must stay private.
 
 History can include user messages, assistant thinking, tool arguments, errors, and images. Content you retrieve enters the context of your selected model and provider.
 

package/index.ts

@@ -1,7 +1,7 @@
 /**
  * Posthorse — fresh context, same journey.
  *
- * Pi owns persisted retain-none context boundaries. Posthorse owns reminder and
+ * Pi owns persisted context boundaries. Posthorse owns recent-tail retention, reminder and
  * rollover policy, bounded recovery, durable notes, and history retrieval.
  */
 import {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-posthorse",
-	"version": "0.9.2",
+	"version": "0.10.0",
 	"type": "module",
 	"description": "Posthorse: fresh context, same journey. No-summary context rollover for Pi, with sparse budget reminders, handoffs, notes, and history.",
 	"keywords": [
@@ -48,8 +48,8 @@
 		"prepublishOnly": "npm run verify"
 	},
 	"peerDependencies": {
-		"@earendil-works/pi-coding-agent": "*",
-		"@earendil-works/pi-tui": "*",
+		"@earendil-works/pi-coding-agent": ">=1.3.0",
+		"@earendil-works/pi-tui": ">=1.3.0",
 		"typebox": "*"
 	},
 	"peerDependenciesMeta": {
@@ -64,9 +64,9 @@
 		}
 	},
 	"devDependencies": {
-		"@earendil-works/pi-ai": "1.0.0",
-		"@earendil-works/pi-coding-agent": "1.0.0",
-		"@earendil-works/pi-tui": "1.0.0",
+		"@earendil-works/pi-ai": "1.3.0",
+		"@earendil-works/pi-coding-agent": "1.3.0",
+		"@earendil-works/pi-tui": "1.3.0",
 		"@types/node": "24.19.1",
 		"oxc-parser": "0.153.0",
 		"oxfmt": "0.72.0",

package/src/budget.ts

@@ -14,7 +14,7 @@ import { imagesOf, textOf } from "./message-text.ts";
 
 const MIN_USABLE_TOKENS = Math.ceil(MAX_HANDOFF_CHARS / 4) * 2;
 export const CHECKPOINT_STEPS =
-	"update the task's current-state note (goal, progress, decisions, next steps) with available file-editing tools at its absolute path; use notes write only for creation, substantial restructuring, or when editing tools are unavailable. If the note is already current, leave it unchanged. Then call new_context";
+	"update the task's current-state note (goal, progress, decisions, next steps) with available file-editing tools at its absolute path; use notes write only for creation, substantial restructuring, or when editing tools are unavailable. If the note is already current, leave it unchanged. Then continue working; let automatic rollover happen without calling new_context";
 export type Budget = {
 	readonly contextWindow: number;
 	readonly reserveTokens: number;
@@ -84,7 +84,7 @@ function automaticGuidance(budget: Budget | undefined, enabled: boolean): string
 		budget === undefined
 			? ""
 			: ` The rollover line is ${budget.rolloverAt.toLocaleString("en-US")} tokens used under the available Pi settings.`;
-	return `Automatic rollover follows Pi's compaction setting.${line} At most one checkpoint reminder may arrive at the end of a working turn before the rollover line (${deadline}), never on a turn that ends the run; when it does, stop normal work, ${CHECKPOINT_STEPS}.`;
+	return `Automatic rollover follows Pi's compaction setting and retains a safe recent-message tail using compaction.keepRecentTokens, without model summarization.${line} At most one notes reminder may arrive at the end of a working turn before the rollover line (${deadline}), never on a turn that ends the run; when it does, ${CHECKPOINT_STEPS}. new_context is an optional deliberate clean reset, not a checkpoint requirement.`;
 }
 export function buildGuidance(ctx: PolicyContext): string {
 	const budget = budgetFor(ctx);
@@ -92,7 +92,7 @@ export function buildGuidance(ctx: PolicyContext): string {
 	const capacity =
 		budget === undefined
 			? "Configured context capacity is unknown."
-			: `Configured context capacity: ${budget.contextWindow.toLocaleString("en-US")} tokens. This is Pi's best available native limit, not remaining space or a measured provider boundary. Fresh windows use the active configuration; system instructions, tools, the handoff, and new messages consume part of it.`;
+			: `Configured context capacity: ${budget.contextWindow.toLocaleString("en-US")} tokens. This is Pi's best available native limit, not remaining space or a measured provider boundary. Fresh windows use the active configuration; system instructions, tools, the handoff, retained recent messages, and new messages consume part of it.`;
 	return `## Context self-management (Posthorse)
 ${capacity}
 Do not guess context capacity or remaining space from response-token limits or reasoning budgets. Before reporting a remaining-token count or changing your work plan because of context limits, call get_context_remaining. If usage is unknown, report it as unknown. No routine budget checks are needed.

package/src/context-tools.ts

@@ -60,8 +60,8 @@ export function registerContextTools(
 		label: "New Context",
 		...toolCards("new_context"),
 		description:
-			"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",
+			"Optionally request a deliberate clean context reset once the current foreground tools succeed; retains no prior messages, unlike automatic rollover. Not required after a notes reminder. Background work continues. Earlier conversation stays recoverable through history. Put continuation state in handoff, or save fuller state in notes first.",
+		promptSnippet: "optionally request a clean context reset with an optional handoff",
 		parameters: Type.Object({
 			handoff: Type.Optional(
 				Type.String({
@@ -94,7 +94,7 @@ export function registerContextTools(
 		label: "Context Remaining",
 		...toolCards("get_context_remaining"),
 		description:
-			"Estimate tokens left before Pi's automatic rollover and the configured context limit. Check before reporting remaining space or changing your work plan because of context limits. A checkpoint reminder may arrive before rollover on a working turn; no routine checks are needed.",
+			"Estimate tokens left before Pi's automatic rollover and the configured context limit. Check before reporting remaining space or changing your work plan because of context limits. A notes-only reminder may arrive before rollover on a working turn; continue afterward and let rollover happen automatically. No routine checks are needed.",
 		promptSnippet:
 			"verify remaining context before reporting a token count or changing plans because of context limits",
 		parameters: Type.Object({}),

package/src/contracts.ts

@@ -4,6 +4,7 @@ import type { PosthorseDisplay } from "../ui.ts";
 export type CompactionPolicy = {
 	readonly enabled: boolean;
 	readonly reserveTokens: number;
+	readonly keepRecentTokens?: number;
 };
 export type ContextUsage = {
 	readonly tokens: number | null;

package/src/files.ts

@@ -1,5 +1,15 @@
-import { randomUUID } from "node:crypto";
-import { createReadStream, existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import {
+	createReadStream,
+	existsSync,
+	lstatSync,
+	mkdirSync,
+	readFileSync,
+	realpathSync,
+	renameSync,
+	statSync,
+	symlinkSync,
+} from "node:fs";
 import {
 	access,
 	constants,
@@ -12,7 +22,8 @@ import {
 	stat,
 	unlink,
 } from "node:fs/promises";
-import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { isRecord } from "./contracts.ts";
 
 async function lstatOrMissing(path: string) {
@@ -171,7 +182,7 @@ function gitRoot(dir: string, marker: string): string {
 	return basename(common) === ".git" ? dirname(common) : common;
 }
 /** Conventional repos share the primary checkout; separate Git directories own their shared root. */
-export function notesRoot(cwd: string): string {
+function notesRoot(cwd: string): string {
 	for (let dir = cwd; ; dir = dirname(dir)) {
 		const marker = join(dir, ".git");
 		if (existsSync(marker)) {
@@ -186,3 +197,88 @@ export function notesRoot(cwd: string): string {
 		}
 	}
 }
+function packageRelativePath(installs: string, root: string): string | undefined {
+	const path = relative(installs, root);
+	return path !== "" && path !== ".." && !path.startsWith(`..${sep}`) && !isAbsolute(path)
+		? path
+		: undefined;
+}
+function projectPackageNotes(root: string, cwd: string): string | undefined {
+	let moved: string | undefined;
+	let checkout = root;
+	for (let dir = cwd; dirname(dir) !== dir; dir = dirname(dir)) {
+		// Retain the logical checkout path when a package container or source segment is linked.
+		if (existsSync(join(dir, ".git")) && realpathSync(dir) === root) {
+			checkout = dir;
+		}
+		if (basename(dir) !== "git" || basename(dirname(dir)) !== ".pi") {
+			continue;
+		}
+		const path = packageRelativePath(dir, checkout);
+		if (path !== undefined) {
+			// Flat full keys keep arbitrary Git URL prefix paths out of one another's note stores.
+			const key = createHash("sha256").update(path.split(sep).join("/")).digest("hex");
+			moved = join(realpathSync(dirname(dir)), "package-notes", key, "notes");
+		}
+	}
+	// The outermost package container also protects packages installed inside another package.
+	return moved;
+}
+/**
+ * Pi's package manager installs Git sources in <agent>/git or <project>/.pi/git and runs
+ * `git clean -fdx` inside their checkouts on update. Keep notes alongside, not inside, that tree.
+ * ponytail: notes a package commits under `.pi/notes` return with each update and move into
+ * another `from-checkout-*` folder; skip tracked files if a package ever commits its notes.
+ */
+function packageNotes(root: string, cwd: string): string | undefined {
+	// Pi cleans only the checkouts; folders that hold several of them keep their own notes.
+	if (!existsSync(join(root, ".git"))) {
+		return;
+	}
+	const agentDir = getAgentDir();
+	const installs = join(agentDir, "git");
+	const path = packageRelativePath(
+		existsSync(installs) ? realpathSync(installs) : installs,
+		root,
+	);
+	return path === undefined
+		? (projectPackageNotes(root, cwd) ?? projectPackageNotes(root, root))
+		: join(agentDir, "notes", path);
+}
+/** Preserve every existing entry, including empty directories and dangling links. */
+function migrationTarget(moved: string): string {
+	if (lstatSync(moved, { throwIfNoEntry: false }) === undefined) {
+		return moved;
+	}
+	const base = join(moved, `from-checkout-${Date.now()}`);
+	let target = base;
+	for (let suffix = 1; lstatSync(target, { throwIfNoEntry: false }) !== undefined; suffix++) {
+		target = `${base}-${suffix}`;
+	}
+	return target;
+}
+/** The notes directory for `cwd`, moving any notes found inside a Pi package checkout. */
+export function notesDir(cwd: string): string {
+	const root = notesRoot(cwd);
+	const local = join(root, ".pi", "notes");
+	const moved = packageNotes(root, cwd);
+	if (moved === undefined) {
+		return local;
+	}
+	if (lstatSync(local, { throwIfNoEntry: false })?.isDirectory() === true) {
+		mkdirSync(dirname(moved), { recursive: true });
+		// Notes an older Posthorse wrote here after an earlier move keep a folder of their own.
+		const target = migrationTarget(moved);
+		try {
+			renameSync(local, target);
+			// Sessions still running an older Posthorse keep reaching the notes until they reload.
+			symlinkSync(moved, local, "junction");
+		} catch (error) {
+			if (lstatSync(local, { throwIfNoEntry: false })?.isDirectory() === true) {
+				throw error;
+			}
+			// Another session moved them first, or only the compatibility link failed.
+		}
+	}
+	return moved;
+}

package/src/notes.ts

@@ -23,7 +23,7 @@ import {
 	type PolicyContext,
 	type TextResult,
 } from "./contracts.ts";
-import { isBinaryFile, notesRoot, publishFile, readText } from "./files.ts";
+import { isBinaryFile, notesDir, publishFile, readText } from "./files.ts";
 import { excerpt, excerptAround } from "./message-text.ts";
 import type { PageAccess } from "./paging.ts";
 
@@ -45,7 +45,7 @@ const SEARCH_OFFSET_LIMIT = 1_000_000;
 function safeJoin(dir: string, path: string): string {
 	const relative = normalize(path.replace(/^[/\\]+/, ""));
 	if (relative === ".." || relative.startsWith(`..${sep}`) || isAbsolute(relative)) {
-		throw new Error(`Invalid path "${path}": must stay inside .pi/notes/.`);
+		throw new Error(`Invalid path "${path}": must stay inside the notes directory.`);
 	}
 	return join(dir, relative);
 }
@@ -278,7 +278,7 @@ export function registerNotes(
 				{ description: "Operation to perform" },
 			),
 			path: Type.Optional(
-				Type.String({ description: "Note or folder path relative to .pi/notes/" }),
+				Type.String({ description: "Note or folder path relative to the notes directory" }),
 			),
 			content: Type.Optional(
 				Type.String({ description: "Full file content (write) or text to add (append)" }),
@@ -296,7 +296,7 @@ export function registerNotes(
 		// Pi's fixed tool contract supplies id, params, signal, updates, and context.
 		// oxlint-disable-next-line max-params
 		async execute(_id, params, signal, _onUpdate, ctx) {
-			const dir = join(notesRoot(ctx.cwd), ".pi", "notes");
+			const dir = notesDir(ctx.cwd);
 			switch (params.op) {
 				case "list":
 					return listNotes(dir, params, policy(ctx), pages);

package/src/recovery-results.ts

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

package/src/recovery.ts

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

package/src/retention.ts

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

package/src/rollover.ts

@@ -14,7 +14,6 @@ import {
 import {
 	isRecord,
 	isReminderType,
-	MIN_PAGE_CHARS,
 	REMINDER_TYPE,
 	type CompactionPolicy,
 	type PolicyContext,
@@ -23,7 +22,7 @@ import {
 } from "./contracts.ts";
 import { registerContextTools } from "./context-tools.ts";
 import { safeJsonStringify } from "./message-text.ts";
-import { buildAutoHandoff } from "./recovery.ts";
+import { automaticRecovery } from "./retention.ts";
 import {
 	createReminderLookup,
 	hasReminder,
@@ -42,7 +41,7 @@ function registerGuidance(pi: ExtensionAPI, policy: SnapshotReader): void {
 		promptOptions = event.systemPromptOptions;
 	});
 	pi.on("agent_settled", () => {
-		// Older hosts skip the start hook for custom runs; do not reuse a settled run's options.
+		// Prompt options belong to one run, never to later idle context evaluation.
 		promptOptions = undefined;
 	});
 	pi.on("context_with_system", (event, ctx) => {
@@ -175,7 +174,7 @@ function sendReminder(
 	pi.sendMessage(
 		{
 			customType: REMINDER_TYPE,
-			content: `[posthorse] Checkpoint now: ${(budget.rolloverAt - tokens).toLocaleString("en-US")} tokens remain before Pi's automatic rollover line. Stop normal work, ${CHECKPOINT_STEPS}.`,
+			content: `[posthorse] Notes checkpoint: ${(budget.rolloverAt - tokens).toLocaleString("en-US")} tokens remain before Pi's automatic rollover line. Please ${CHECKPOINT_STEPS}.`,
 			display: true,
 			details: fingerprint,
 		},
@@ -232,12 +231,20 @@ function registerReminderFilter(
 function automaticDraft(
 	pi: ExtensionAPI,
 	ctx: ExtensionContext,
-	recovery: { readonly handoff: string; readonly tokensBefore: number; readonly reason: string },
+	recovery: {
+		readonly handoff: string;
+		readonly tokensBefore: number;
+		readonly reason: string;
+		readonly firstKeptEntryId?: string;
+	},
 ) {
-	// Public compaction requires an entry id. An invisible sentinel keeps no prior conversation.
-	pi.appendEntry("posthorse-boundary", {});
-	const firstKeptEntryId = ctx.sessionManager.getLeafId();
-	if (firstKeptEntryId === null || firstKeptEntryId === "") {
+	let firstKeptEntryId = recovery.firstKeptEntryId;
+	if (firstKeptEntryId === undefined) {
+		// Public compaction requires an entry id even when no prior conversation safely fits.
+		pi.appendEntry("posthorse-boundary", {});
+		firstKeptEntryId = ctx.sessionManager.getLeafId() ?? undefined;
+	}
+	if (firstKeptEntryId === undefined || firstKeptEntryId === "") {
 		throw new Error("Pi did not persist the context boundary.");
 	}
 	return {
@@ -316,17 +323,16 @@ function thresholdFallback(
 		return undefined;
 	}
 	const projected = event.context.contextEntries;
-	const limit = freshPayloadChars(host, toolTokens(), event.context.pendingMessages);
 	const ownerQuestionRegistered = pi
 		.getAllTools()
 		.some((tool) => tool.name === "ask_question" && tool.namespace === undefined);
-	const summary = buildAutoHandoff(
+	const recovery = automaticRecovery(
 		ctx.sessionManager.getBranch(),
 		projected,
-		limit,
+		{ host, toolTokens: toolTokens(), pendingMessages: event.context.pendingMessages },
 		ownerQuestionRegistered,
 	);
-	if (limit < MIN_PAGE_CHARS || summary.length > limit) {
+	if (recovery === undefined) {
 		return undefined;
 	}
 	// ponytail: turn_end drafts are eager. Later projection editors must replace/remove this draft;
@@ -336,8 +342,8 @@ function thresholdFallback(
 			...event.entries,
 			{
 				type: "compaction",
-				summary,
-				firstKeptEntryId: null,
+				summary: recovery.handoff,
+				firstKeptEntryId: recovery.firstKeptEntryId ?? null,
 				details: { posthorse: 1, reason: "threshold" },
 			},
 		],
@@ -362,17 +368,20 @@ function registerAutomaticRollover(
 			if (budgetFor(host)?.supported !== true) {
 				return;
 			}
-			const limit = freshPayloadChars(host, activeToolTokens());
 			const ownerQuestionRegistered = pi
 				.getAllTools()
 				.some((tool) => tool.name === "ask_question" && tool.namespace === undefined);
-			const handoff = buildAutoHandoff(
+			const recovery = automaticRecovery(
 				event.branchEntries,
 				ctx.sessionManager.buildSessionProjection().entries,
-				limit,
+				{
+					host,
+					toolTokens: activeToolTokens(),
+					firstKeptEntryId: event.preparation.firstKeptEntryId,
+				},
 				ownerQuestionRegistered,
 			);
-			if (limit < MIN_PAGE_CHARS || handoff.length > limit) {
+			if (recovery === undefined) {
 				throw new Error(
 					"Too little fresh context capacity for an automatic recovery record.",
 				);
@@ -381,7 +390,7 @@ function registerAutomaticRollover(
 				return { cancel: true };
 			}
 			return automaticDraft(pi, ctx, {
-				handoff,
+				...recovery,
 				tokensBefore: event.preparation.tokensBefore,
 				reason: event.reason,
 			});