pi-posthorse 0.10.2 → 0.10.4

package/README.md

@@ -48,7 +48,12 @@ These tools are available to the model:
 
 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.
 
-See [tool examples and paging details](https://github.com/fitchmultz/pi-posthorse/blob/main/docs/reference.md#tools).
+Forks get private copies of the notes used on their selected branch. The parent and fork can
+update the same note name without overwriting each other. Project-wide lists and searches still
+find both, with scope selectors for read-only comparisons.
+
+See [tool examples and paging details](https://github.com/fitchmultz/pi-posthorse/blob/main/docs/reference.md#tools)
+and [fork notes](https://github.com/fitchmultz/pi-posthorse/blob/main/docs/reference.md#forks-references-and-discovery).
 
 ## Settings and limits
 
@@ -80,7 +85,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. 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.
+Posthorse makes no network requests. Notes are plaintext files under `.pi/notes/`. Linked Git worktrees share that store; forks keep private note files inside its `.forks/` directory. 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

@@ -15,6 +15,8 @@ import type { CompactionPolicy, PolicyReader } from "./src/contracts.ts";
 import { registerHistory } from "./src/history.ts";
 import { safeJsonStringify } from "./src/message-text.ts";
 import { registerNotes } from "./src/notes.ts";
+import { createNotesStore } from "./src/note-store.ts";
+import { registerNoteGuards } from "./src/note-guards.ts";
 import { PageReservations } from "./src/paging.ts";
 import { registerRollover } from "./src/rollover.ts";
 
@@ -47,10 +49,18 @@ export function createPosthorse(getPolicy?: PolicyReader): (pi: ExtensionAPI) =>
 		const toolTokens = () => activeToolTokens(pi);
 		const pages = new PageReservations(toolTokens);
 		registerPosthorseMessages(pi);
-		registerRollover(pi, policy, toolTokens, () => {
-			pages.reset();
+		const notes = createNotesStore(pi);
+		registerRollover(pi, policy, toolTokens, {
+			resetPages: () => {
+				pages.reset();
+			},
+			notes: (ctx) => notes.recovery(ctx),
 		});
-		registerNotes(pi, policy, pages);
+		pi.on("session_start", async (_event, ctx) => {
+			await notes.get(ctx);
+		});
+		registerNoteGuards(pi, notes);
+		registerNotes(pi, policy, pages, notes);
 		registerHistory(pi, policy, pages);
 	};
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-posthorse",
-	"version": "0.10.2",
+	"version": "0.10.4",
 	"type": "module",
 	"description": "Posthorse: fresh context, same journey. No-summary context rollover for Pi, with sparse budget reminders, handoffs, notes, and history.",
 	"keywords": [
@@ -31,25 +31,28 @@
 		"image": "https://raw.githubusercontent.com/fitchmultz/pi-posthorse/main/diagram.png"
 	},
 	"scripts": {
-		"check": "tsc",
-		"quality:prepare": "node scripts/quality-prepare.ts",
-		"quality:policy": "node scripts/quality-policy.ts && node scripts/config-policy.ts",
-		"quality:probes": "npm run quality:prepare && node --test test/quality*.test.ts",
-		"lint": "npm run quality:prepare && npm run quality:policy && oxlint --deny-warnings .",
-		"lint:agent": "npm run quality:prepare && npm run quality:policy && oxlint --deny-warnings --format=agent .",
-		"lint:fix": "npm run quality:prepare && npm run quality:policy && oxlint --fix .",
+		"check": "tsc --noEmit",
+		"quality:policy": "node scripts/quality-policy.ts",
+		"quality:probes": "node --test test/quality*.test.ts",
+		"lint": "node scripts/verify.ts quality:policy quality:config lint:oxlint",
+		"lint:agent": "node scripts/verify.ts quality:policy quality:config lint:agent:oxlint",
+		"lint:fix": "node scripts/verify.ts quality:policy quality:config lint:fix:oxlint",
 		"format": "oxfmt --write .",
 		"format:check": "oxfmt --check .",
 		"build": "npm pack --dry-run",
-		"verify": "node scripts/toolchain-policy.ts && npm run lint && npm run format:check && npm run check:compat && npm run build",
-		"check:compat": "npm run check && npm test",
+		"verify": "node scripts/toolchain-policy.ts && node scripts/verify.ts quality:policy quality:config lint:oxlint format:check check test build",
+		"check:compat": "node scripts/verify.ts check test",
 		"test:native": "node --import ./test/pi-loader.ts --test test/host.test.mjs",
-		"test": "npm run quality:prepare && node --import ./test/pi-loader.ts --test test/*.test.ts test/host.test.mjs",
-		"prepublishOnly": "npm run verify"
+		"test": "node --import ./test/pi-loader.ts --test test/*.test.ts test/host.test.mjs",
+		"prepublishOnly": "npm run verify",
+		"quality:config": "node scripts/config-policy.ts",
+		"lint:oxlint": "oxlint --deny-warnings .",
+		"lint:agent:oxlint": "oxlint --deny-warnings --format=agent .",
+		"lint:fix:oxlint": "oxlint --fix ."
 	},
 	"peerDependencies": {
-		"@earendil-works/pi-coding-agent": ">=1.3.0",
-		"@earendil-works/pi-tui": ">=1.3.0",
+		"@earendil-works/pi-coding-agent": ">=1.4.0",
+		"@earendil-works/pi-tui": ">=1.4.0",
 		"typebox": "*"
 	},
 	"peerDependenciesMeta": {
@@ -64,14 +67,14 @@
 		}
 	},
 	"devDependencies": {
-		"@earendil-works/pi-ai": "1.3.0",
-		"@earendil-works/pi-coding-agent": "1.3.0",
-		"@earendil-works/pi-tui": "1.3.0",
+		"@earendil-works/pi-ai": "1.4.0",
+		"@earendil-works/pi-coding-agent": "1.4.0",
+		"@earendil-works/pi-tui": "1.4.0",
 		"@types/node": "24.19.1",
-		"oxc-parser": "0.153.0",
-		"oxfmt": "0.72.0",
-		"oxlint": "1.87.0",
-		"oxlint-tsgolint": "7.0.2003",
+		"oxc-parser": "0.156.0",
+		"oxfmt": "0.75.0",
+		"oxlint": "1.90.0",
+		"oxlint-tsgolint": "7.0.2005",
 		"typebox": "1.3.27",
 		"typescript": "7.0.2",
 		"yaml": "2.9.1"

package/src/context-tools.ts

@@ -71,7 +71,7 @@ export function registerContextTools(
 			),
 		}),
 		// Pi's fixed tool contract supplies id, params, signal, updates, and context.
-		// oxlint-disable-next-line max-params
+		// oxlint-disable-next-line max-params -- QX-002: Pi supplies five fixed positional tool arguments.
 		async execute(id, { handoff }, _signal, _onUpdate, ctx) {
 			const trimmed = handoff?.trim();
 			const limit = freshPayloadChars(policy(ctx), activeToolTokens());
@@ -99,7 +99,7 @@ export function registerContextTools(
 			"verify remaining context before reporting a token count or changing plans because of context limits",
 		parameters: Type.Object({}),
 		// Pi's fixed tool contract supplies id, params, signal, updates, and context.
-		// oxlint-disable-next-line max-params
+		// oxlint-disable-next-line max-params -- QX-002: Pi supplies five fixed positional tool arguments.
 		async execute(_id, _params, _signal, _onUpdate, ctx) {
 			return contextReport(policy(ctx));
 		},

package/src/contracts.ts

@@ -4,7 +4,7 @@ import type { PosthorseDisplay } from "../ui.ts";
 export type CompactionPolicy = {
 	readonly enabled: boolean;
 	readonly reserveTokens: number;
-	readonly keepRecentTokens?: number;
+	readonly keepRecentTokens?: number | undefined;
 };
 export type ContextUsage = {
 	readonly tokens: number | null;
@@ -17,52 +17,59 @@ export type PolicyContext = {
 	readonly getSystemPrompt: () => string;
 };
 export type PolicyReader = (ctx: ExtensionContext) => CompactionPolicy;
+export type SnapshotReader = (
+	ctx: ExtensionContext,
+	livePolicy?: CompactionPolicy,
+) => PolicyContext;
 export type ImageLike = {
 	readonly type: "image";
 	readonly data: string;
 	readonly mimeType: string;
 };
 export type ToolCallLike = {
-	readonly type?: string;
-	readonly id?: string;
-	readonly name?: string;
-	readonly namespace?: string;
+	readonly type?: string | undefined;
+	readonly id?: string | undefined;
+	readonly name?: string | undefined;
+	readonly namespace?: string | undefined;
 	readonly arguments?: unknown;
 	readonly executionArguments?: unknown;
-	readonly async?: boolean;
+	readonly async?: boolean | undefined;
 };
 export type MessageLike = {
-	readonly role?: string;
-	readonly stopReason?: string;
-	readonly errorMessage?: string;
+	readonly role?: string | undefined;
+	readonly stopReason?: string | undefined;
+	readonly errorMessage?: string | undefined;
 	readonly content?: unknown;
-	readonly summary?: string;
-	readonly toolName?: string;
-	readonly customType?: string;
-	readonly namespace?: string;
-	readonly toolCallId?: string;
-	readonly isError?: boolean;
+	readonly summary?: string | undefined;
+	readonly toolName?: string | undefined;
+	readonly customType?: string | undefined;
+	readonly namespace?: string | undefined;
+	readonly toolCallId?: string | undefined;
+	readonly isError?: boolean | undefined;
 	readonly details?: unknown;
 	readonly nestedCalls?: unknown;
-	readonly command?: string;
-	readonly output?: string;
-	readonly excludeFromContext?: boolean;
+	readonly command?: string | undefined;
+	readonly output?: string | undefined;
+	readonly excludeFromContext?: boolean | undefined;
 };
 export type EntryLike = {
-	readonly type?: string;
-	readonly id?: string;
-	readonly parentId?: string | null;
-	readonly timestamp?: string;
-	readonly message?: MessageLike;
-	readonly summary?: string;
-	readonly customType?: string;
+	readonly type?: string | undefined;
+	readonly id?: string | undefined;
+	readonly parentId?: string | null | undefined;
+	readonly timestamp?: string | undefined;
+	readonly message?: MessageLike | undefined;
+	readonly summary?: string | undefined;
+	readonly customType?: string | undefined;
 	readonly content?: unknown;
 	readonly details?: unknown;
-	readonly display?: boolean;
-	readonly handoff?: string;
-	readonly firstKeptEntryId?: string | null;
-	readonly targetId?: string;
-	readonly replacement?: { readonly content: unknown } | null;
+	readonly display?: boolean | undefined;
+	readonly data?: unknown;
+	readonly cwd?: string | undefined;
+	readonly parentSession?: string | undefined;
+	readonly handoff?: string | undefined;
+	readonly firstKeptEntryId?: string | null | undefined;
+	readonly targetId?: string | undefined;
+	readonly replacement?: { readonly content: unknown } | null | undefined;
 };
 export type WindowedEntry = {
 	readonly entry: EntryLike;
@@ -82,8 +89,8 @@ export type HistoryHit = {
 };
 export type ReminderFingerprint = {
 	readonly windowId: string;
-	readonly contextWindow?: number;
-	readonly reserveTokens?: number;
+	readonly contextWindow?: number | undefined;
+	readonly reserveTokens?: number | undefined;
 };
 export type TextResult = {
 	content: Array<

package/src/files.ts

@@ -45,22 +45,18 @@ export async function resolveFileTarget(absolutePath: string): Promise<string> {
 		if (target.endsWith(sep) || target.endsWith("/")) {
 			// Trailing separators require an existing directory, never a new regular file.
 			// Resolution follows dependent links in filesystem order.
-			// oxlint-disable-next-line no-await-in-loop
 			await stat(target);
 			return realpath(target);
 		}
 		const parentInput = dirname(target);
 		// stat enforces regular-file/.. traversal that macOS realpath alone accepts.
-		// oxlint-disable-next-line no-await-in-loop
 		if (!(await stat(parentInput)).isDirectory()) {
 			throw Object.assign(new Error(`Not a directory: ${parentInput}`), { code: "ENOTDIR" });
 		}
 		// Each parent must resolve before its child link can be examined.
-		// oxlint-disable-next-line no-await-in-loop
 		const parent = await realpath(parentInput);
 		target = join(parent, basename(target));
 		// Link targets cannot be known before examining the current link.
-		// oxlint-disable-next-line no-await-in-loop
 		const info = await lstatOrMissing(target);
 		if (info === undefined) {
 			return target;
@@ -73,7 +69,6 @@ export async function resolveFileTarget(absolutePath: string): Promise<string> {
 		}
 		links.add(target);
 		// Preserve .. until the preceding directory symlink has been followed.
-		// oxlint-disable-next-line no-await-in-loop
 		const link = await readlink(target);
 		target = isAbsolute(link) ? link : `${parent}${sep}${link}`;
 	}

package/src/guidance.ts

@@ -0,0 +1,41 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { buildGuidance } from "./budget.ts";
+import type { SnapshotReader } from "./contracts.ts";
+
+export function registerGuidance(pi: ExtensionAPI, policy: SnapshotReader): void {
+	let promptOptions: { readonly forceSystemPrompt?: string } | undefined;
+	pi.on("before_agent_start", (event) => {
+		promptOptions = event.systemPromptOptions;
+	});
+	pi.on("agent_settled", () => {
+		// Prompt options belong to one run, never to later idle context evaluation.
+		promptOptions = undefined;
+	});
+	pi.on("context_with_system", (event, ctx) => {
+		const guidance = buildGuidance(policy(ctx));
+		const system =
+			event.messages.findLast(
+				(message) =>
+					message.role === "system" && typeof message.sections?.posthorse === "string",
+			) ?? event.messages.find((message) => message.role === "system");
+		if (system === undefined || system.role !== "system") {
+			return;
+		}
+		if (promptOptions?.forceSystemPrompt !== undefined) {
+			// ponytail: Pi applies forced prompts after this hook; keep request-local guidance
+			// until the host projects forced text before context_with_system.
+			event.messages.splice(1, 0, {
+				role: "custom",
+				customType: "posthorse-guidance",
+				content: guidance,
+				display: false,
+				timestamp: 0,
+			});
+		} else {
+			system.sections = {
+				...system.sections,
+				posthorse: `<posthorse>\n${guidance}\n</posthorse>`,
+			};
+		}
+	});
+}

package/src/history-entries.ts

@@ -36,10 +36,10 @@ export function contextStart(entries: readonly EntryLike[]): {
 } {
 	for (let i = entries.length - 1; i >= 0; i--) {
 		const entry = entries[i];
-		if (entry.type === "context_window") {
+		if (entry?.type === "context_window") {
 			return { start: i + 1, boundary: entry };
 		}
-		if (entry.type === "compaction") {
+		if (entry?.type === "compaction") {
 			const kept = entries.findIndex((candidate) => candidate.id === entry.firstKeptEntryId);
 			return { start: kept >= 0 ? kept : i + 1, boundary: entry };
 		}
@@ -101,27 +101,26 @@ function contentText(content: unknown): string {
 		.join("\n");
 }
 function ownAssistantText(message: MessageLike, images: WindowedEntry["images"]): string[] {
-	const originals = [""];
+	const originals: string[] = [];
+	let current = "";
 	for (const part of unknownArray(message.content) ?? []) {
 		if (isRecoveryCall(part)) {
-			originals.push("");
+			originals.push(current);
+			current = "";
 		} else {
 			const partText = textOf({ content: [part] });
-			const index = originals.length - 1;
 			if (partText !== "") {
-				originals[index] += `${originals[index] === "" ? "" : "\n"}${partText}`;
+				current = current === "" ? partText : `${current}\n${partText}`;
 			}
 		}
 	}
-	const metadata = [assistantFailure(message), imageSummary(images)]
+	const last = [current, assistantFailure(message), imageSummary(images)]
 		.filter((part) => part !== "")
 		.join("\n");
-	const last = originals.length - 1;
-	if (metadata !== "") {
-		originals[last] += `${originals[last] === "" ? "" : "\n"}${metadata}`;
-	}
-	if (originals[0] !== "") {
-		originals[0] = `[assistant] ${originals[0]}`;
+	originals.push(last);
+	const first = originals[0] ?? "";
+	if (first !== "") {
+		originals[0] = `[assistant] ${first}`;
 	}
 	return originals;
 }
@@ -228,9 +227,10 @@ export function windowProjection(): (entry: EntryLike) => string {
 export function* reverseWindowEntries(entries: readonly EntryLike[]): Generator<WindowedEntry> {
 	// Preserve parent-relative window labels without normalizing the whole branch.
 	// ponytail: ancestry still scans metadata; a native window-aware iterator could remove that cost.
-	const windows = entries.map(windowProjection());
-	for (let i = entries.length - 1; i >= 0; i--) {
-		const item = toWindowedEntry(entries[i], windows[i]);
+	const project = windowProjection();
+	const windows = entries.map((entry) => ({ entry, windowId: project(entry) }));
+	for (const { entry, windowId } of windows.reverse()) {
+		const item = toWindowedEntry(entry, windowId);
 		if (item !== undefined) {
 			yield item;
 		}

package/src/history-pages.ts

@@ -13,7 +13,7 @@ import type { PageAccess } from "./paging.ts";
 type SearchPage = {
 	readonly parts: readonly string[];
 	readonly spans: readonly { readonly headerLength: number; readonly length: number }[];
-	readonly next?: string;
+	readonly next?: string | undefined;
 };
 function cursorFor(matches: HistoryMatches, hit: HistoryHit, offset: number): string {
 	return Buffer.from(JSON.stringify([hit.id, hit.priority, offset, matches.key])).toString(

package/src/history-search.ts

@@ -30,7 +30,7 @@ export type HistoryParams = {
 export type HistorySource = {
 	readonly dir: string;
 	readonly cwd: string;
-	readonly currentFile?: string;
+	readonly currentFile?: string | undefined;
 	readonly branch: () => readonly EntryLike[];
 	readonly projection: () => readonly ProjectedEntry[];
 };
@@ -38,7 +38,7 @@ export type HistoryCursor = readonly [id: string, priority: 0 | 1, offset: numbe
 export type HistoryMatches = {
 	readonly hits: readonly HistoryHit[];
 	readonly skipped: number;
-	readonly cursor?: HistoryCursor;
+	readonly cursor?: HistoryCursor | undefined;
 	readonly key: string;
 	readonly limit: number;
 };
@@ -109,7 +109,7 @@ function contextVisibility(project: HistorySource["projection"]): (entry: EntryL
 	};
 }
 type SearchProgress = {
-	readonly cursor?: HistoryCursor;
+	readonly cursor?: HistoryCursor | undefined;
 	readonly limit: number;
 	readonly add: (hit: HistoryHit) => void;
 	readonly seeking: (priority: 0 | 1) => boolean;
@@ -201,8 +201,8 @@ async function scanArchive(
 	options: {
 		readonly source: string;
 		readonly query: string;
-		readonly signal?: AbortSignal;
-		readonly wanted?: LineMatcher;
+		readonly signal?: AbortSignal | undefined;
+		readonly wanted?: LineMatcher | undefined;
 		readonly inContext: (entry: EntryLike) => boolean;
 	},
 	accumulator: SearchProgress,
@@ -231,7 +231,7 @@ async function archivedMatches(
 	source: HistorySource,
 	search: {
 		readonly query: string;
-		readonly signal?: AbortSignal;
+		readonly signal?: AbortSignal | undefined;
 		readonly inContext: (entry: EntryLike) => boolean;
 	},
 	accumulator: SearchProgress,

package/src/history.ts

@@ -10,7 +10,10 @@ import type { PageAccess } from "./paging.ts";
 import { scopedSessionFiles, sessionWindowEntries } from "./session-files.ts";
 
 type LocatedEntry = { readonly item: WindowedEntry; readonly source: string };
-function entryReference(id: string): { readonly entryId: string; readonly fileKey?: string } {
+function entryReference(id: string): {
+	readonly entryId: string;
+	readonly fileKey?: string | undefined;
+} {
 	const separator = id.indexOf("@");
 	return {
 		entryId: separator < 0 ? id : id.slice(0, separator),
@@ -125,7 +128,7 @@ export function registerHistory(
 			),
 		}),
 		// Pi's fixed tool contract supplies id, params, signal, updates, and context.
-		// oxlint-disable-next-line max-params
+		// oxlint-disable-next-line max-params -- QX-002: Pi supplies five fixed positional tool arguments.
 		async execute(_id, params, signal, _onUpdate, ctx) {
 			const source = historySource(ctx);
 			if (params.op === "search") {