pi-posthorse 0.10.3 → 0.10.5

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.3",
+	"version": "0.10.5",
 	"type": "module",
 	"description": "Posthorse: fresh context, same journey. No-summary context rollover for Pi, with sparse budget reminders, handoffs, notes, and history.",
 	"keywords": [
@@ -51,8 +51,8 @@
 		"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.5.0",
+		"@earendil-works/pi-tui": ">=1.5.0",
 		"typebox": "*"
 	},
 	"peerDependenciesMeta": {
@@ -67,9 +67,9 @@
 		}
 	},
 	"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.5.0",
+		"@earendil-works/pi-coding-agent": "1.5.0",
+		"@earendil-works/pi-tui": "1.5.0",
 		"@types/node": "24.19.1",
 		"oxc-parser": "0.156.0",
 		"oxfmt": "0.75.0",

package/src/contracts.ts

@@ -63,6 +63,9 @@ export type EntryLike = {
 	readonly content?: unknown;
 	readonly details?: unknown;
 	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;

package/src/note-discovery.ts

@@ -0,0 +1,291 @@
+import { readdir, stat } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { isRecord } from "./contracts.ts";
+import { sessionNoteTouches } from "./note-evidence.ts";
+import { notesUnder, type NoteFile } from "./note-inventory.ts";
+import { fileDigest, fileIdentity, readManifest, sameIdentity } from "./note-snapshots.ts";
+import {
+	sameScope,
+	scopeDirectory,
+	type ForkBinding,
+	type NoteAddress,
+	type NoteIdentity,
+	type NoteScope,
+	type NoteSeed,
+} from "./note-scopes.ts";
+import type { SessionNotes } from "./note-store.ts";
+
+export type DiscoveredNote = NoteFile & {
+	readonly address: NoteAddress;
+	readonly lineage: NoteAddress;
+	readonly seed: NoteSeed | undefined;
+	readonly copies: readonly NoteAddress[];
+};
+type ScopeInventory = { readonly scope: NoteScope; readonly manifest: ForkBinding | undefined };
+type DiscoveryOptions = {
+	readonly path?: string | undefined;
+	readonly scope?: string | undefined;
+	readonly signal: AbortSignal | undefined;
+};
+type ComparisonOptions = DiscoveryOptions & { readonly notice: (message: string) => void };
+type DigestCache = {
+	readonly identity: NoteIdentity;
+	readonly digest: string;
+	readonly revision: number;
+};
+async function projectScopes(
+	session: SessionNotes,
+	notice: (message: string) => void,
+): Promise<ScopeInventory[]> {
+	const scopes: ScopeInventory[] = [
+		{ scope: { root: session.binding.root, scope: "" }, manifest: undefined },
+	];
+	const directory = join(session.binding.root, ".forks");
+	const entries = await readdir(directory, { withFileTypes: true }).catch((error: unknown) => {
+		if (isRecord(error) && error.code === "ENOENT") {
+			return [];
+		}
+		throw error;
+	});
+	for (const entry of entries) {
+		const path = join(directory, entry.name);
+		if (entry.name.startsWith(".staging-")) {
+			continue;
+		}
+		const manifest = entry.isDirectory() ? await readManifest(join(path, "notes")) : undefined;
+		if (manifest === undefined || manifest.root !== session.binding.root) {
+			notice(`Not indexed: unmanaged or incomplete notes data at ${path}.`);
+		} else {
+			scopes.push({ scope: manifest, manifest });
+		}
+	}
+	if (!scopes.some(({ scope }) => sameScope(scope, session.binding))) {
+		scopes.push({
+			scope: session.binding,
+			manifest: session.binding.kind === "fork" ? session.binding : undefined,
+		});
+	}
+	return scopes;
+}
+async function scopedFiles(
+	inventory: ScopeInventory,
+	options: DiscoveryOptions,
+	notice: (message: string) => void,
+): Promise<DiscoveredNote[]> {
+	const files = await notesUnder(inventory.scope, options.path, {
+		signal: options.signal,
+		notice,
+	});
+	const seeds = new Map(inventory.manifest?.seeds.map((seed) => [seed.path, seed]));
+	return files.map((file) => {
+		const path = relative(scopeDirectory(inventory.scope), file.path);
+		const address = { root: inventory.scope.root, scope: inventory.scope.scope, path };
+		const seed = seeds.get(path);
+		return Object.assign({}, file, {
+			address,
+			seed,
+			lineage: seed?.lineage ?? address,
+			copies: [],
+		});
+	});
+}
+function noteKey(address: NoteAddress): string {
+	return JSON.stringify([address.root, address.scope, address.path]);
+}
+export function noteReadTarget(note: DiscoveredNote): string {
+	return JSON.stringify({ scope: scopeDirectory(note.address), path: note.address.path });
+}
+export function noteLabel(note: DiscoveredNote, session: SessionNotes, labeled: boolean): string {
+	if (!labeled) {
+		return note.address.path;
+	}
+	const mode = sameScope(note.address, session.binding) ? "current" : "read-only";
+	const copies =
+		note.copies.length === 0
+			? ""
+			: `; identical copies: ${note.copies.map((copy) => JSON.stringify({ scope: scopeDirectory(copy), path: copy.path })).join(", ")}`;
+	return `${note.address.path} [${mode}; read ${noteReadTarget(note)}${copies}]`;
+}
+async function readReference(
+	session: SessionNotes,
+	path: string,
+	signal: AbortSignal | undefined,
+): Promise<DiscoveredNote | undefined> {
+	const target = await session.read(path, { signal });
+	if (target.writable) {
+		return;
+	}
+	const info = await stat(target.path).catch((error: unknown) => {
+		if (isRecord(error) && error.code === "ENOENT") {
+			return;
+		}
+		throw error;
+	});
+	if (info?.isFile() !== true) {
+		return;
+	}
+	return {
+		...fileIdentity(info),
+		path: target.path,
+		address: target.address,
+		lineage: target.address,
+		seed: undefined,
+		copies: [],
+	};
+}
+export class NoteDiscovery {
+	readonly #digests = new Map<string, DigestCache>();
+	#knownDigest(note: DiscoveredNote, revision: number): string | undefined {
+		const cached = this.#digests.get(note.path);
+		if (
+			cached !== undefined &&
+			cached.revision === revision &&
+			sameIdentity(cached.identity, note)
+		) {
+			return cached.digest;
+		}
+		if (revision === 0 && note.seed !== undefined && sameIdentity(note.seed.identity, note)) {
+			return note.seed.digest;
+		}
+		return;
+	}
+	async #digest(
+		note: DiscoveredNote,
+		session: SessionNotes,
+		options: ComparisonOptions,
+	): Promise<string | undefined> {
+		const { signal } = options;
+		const revision = session.revision(note.path);
+		const known = this.#knownDigest(note, revision);
+		if (known !== undefined) {
+			return known;
+		}
+		try {
+			const digest = await fileDigest(note.path, signal);
+			if (!sameIdentity(note, await stat(note.path))) {
+				return;
+			}
+			this.#digests.set(note.path, { identity: note, digest, revision });
+			return digest;
+		} catch (error) {
+			signal?.throwIfAborted();
+			options.notice(
+				`Duplicate comparison unavailable for ${noteReadTarget(note)}: ${error instanceof Error ? error.message : String(error)}. Copies remain separate.`,
+			);
+			return;
+		}
+	}
+	async #collapse(
+		files: readonly DiscoveredNote[],
+		session: SessionNotes,
+		options: ComparisonOptions,
+	): Promise<DiscoveredNote[]> {
+		const groups = new Map<string, DiscoveredNote[]>();
+		for (const file of files) {
+			const key = `${noteKey(file.lineage)}\0${file.size}`;
+			const group = groups.get(key) ?? [];
+			group.push(file);
+			groups.set(key, group);
+		}
+		const selected: DiscoveredNote[] = [];
+		for (const group of groups.values()) {
+			if (group.length === 1) {
+				selected.push(...group);
+				continue;
+			}
+			const matches = new Map<string, DiscoveredNote>();
+			group.sort(
+				(a, b) =>
+					Number(sameScope(b.address, session.binding)) -
+					Number(sameScope(a.address, session.binding)),
+			);
+			for (const file of group) {
+				// Only same-lineage, same-size candidates need content comparison.
+				const digest = await this.#digest(file, session, options);
+				const previous = digest === undefined ? undefined : matches.get(digest);
+				if (previous === undefined || digest === undefined) {
+					matches.set(digest ?? noteKey(file.address), file);
+				} else {
+					matches.set(digest, {
+						...previous,
+						copies: [...previous.copies, file.address],
+					});
+				}
+			}
+			selected.push(...matches.values());
+		}
+		return selected;
+	}
+	async #references(session: SessionNotes, options: DiscoveryOptions): Promise<DiscoveredNote[]> {
+		if (session.binding.kind !== "fork" || options.scope !== undefined) {
+			return [];
+		}
+		const recovery = session.recovery;
+		const { touches } = sessionNoteTouches({
+			branch: session.branch,
+			allEntries: recovery.entries,
+			projected: session.projection,
+			retained: new Set(),
+			directories: new Set(session.scopes.map(scopeDirectory)),
+		});
+		const paths = new Set(touches.map((touch) => touch.notePath));
+		const files: DiscoveredNote[] = [];
+		for (const path of paths) {
+			if (
+				session.owns(path) ||
+				(options.path !== undefined &&
+					path !== options.path &&
+					!path.startsWith(`${options.path}/`))
+			) {
+				continue;
+			}
+			const file = await readReference(session, path, options.signal);
+			if (file !== undefined) {
+				files.push(file);
+			}
+		}
+		return files;
+	}
+	async list(
+		session: SessionNotes,
+		options: DiscoveryOptions,
+	): Promise<{
+		readonly files: readonly DiscoveredNote[];
+		readonly notices: readonly string[];
+		readonly labeled: boolean;
+	}> {
+		const notices: string[] = [];
+		const notice = (text: string) => {
+			notices.push(text);
+		};
+		const scopes =
+			options.scope === undefined
+				? await projectScopes(session, notice)
+				: [
+						{
+							scope: await session.selectScope(options.scope),
+							manifest: await readManifest(options.scope),
+						},
+					];
+		const files: DiscoveredNote[] = [];
+		for (const scope of scopes) {
+			// Preserve native listing order while walking each scope independently.
+			files.push(...(await scopedFiles(scope, options, notice)));
+		}
+		for (const reference of await this.#references(session, options)) {
+			if (!files.some((file) => noteKey(file.address) === noteKey(reference.address))) {
+				files.push(reference);
+			}
+		}
+		const selected =
+			options.scope === undefined
+				? await this.#collapse(files, session, { ...options, notice })
+				: files;
+		return {
+			files: selected.sort((a, b) => b.mtimeMs - a.mtimeMs),
+			notices,
+			labeled:
+				scopes.length > 1 || scopes.some(({ scope }) => !sameScope(scope, session.binding)),
+		};
+	}
+}

package/src/note-evidence.ts

@@ -0,0 +1,179 @@
+import { join } from "node:path";
+import { isRecord, optionalString, type EntryLike, type ProjectedEntry } from "./contracts.ts";
+import { contextEdits } from "./history-entries.ts";
+import { collectTouches, type NoteTouch, type ScannedNoteEntry } from "./recovery-note-touches.ts";
+import {
+	addressOf,
+	bindingsOf,
+	notePath,
+	ownedPaths,
+	sameOwner,
+	sameScope,
+	scopeDirectory,
+	touchRecords,
+	type NoteBinding,
+} from "./note-scopes.ts";
+
+export type NotesRecovery = {
+	readonly binding: NoteBinding;
+	readonly entries: readonly EntryLike[];
+};
+
+export type NoteEvidence = {
+	readonly branch: readonly EntryLike[];
+	readonly allEntries: readonly EntryLike[];
+	readonly projected: readonly ProjectedEntry[];
+	readonly retained: ReadonlySet<string>;
+	readonly directories?: ReadonlySet<string>;
+};
+/** Compaction removes context, not provenance. Only active-branch edits suppress old receipts. */
+function projectedNotes(evidence: NoteEvidence): ScannedNoteEntry[] {
+	const edits = contextEdits(evidence.branch);
+	const omitted = new Set(
+		evidence.projected
+			.filter(({ messages }) => messages.length === 0)
+			.map(({ sourceEntry }) => sourceEntry.id),
+	);
+	return evidence.branch.flatMap((entry) => {
+		const id = entry.id ?? "";
+		const edit = edits.get(id);
+		if (omitted.has(id) || edit?.replacement === null) {
+			return [];
+		}
+		const effective =
+			edit?.replacement !== undefined && entry.type === "message"
+				? { ...entry, message: { ...entry.message, content: edit.replacement.content } }
+				: entry;
+		return [
+			{ entry: effective, entryId: edit?.id ?? id, inRetained: evidence.retained.has(id) },
+		];
+	});
+}
+function receiptKey(entry: EntryLike): string | undefined {
+	if (entry.type === "message" && entry.message?.role === "toolResult") {
+		return entry.message.toolCallId;
+	}
+	return entry.type === "custom_message" && isRecord(entry.details)
+		? optionalString(entry.details.runId)
+		: undefined;
+}
+function effectReceipts(branch: readonly EntryLike[]): ReadonlyMap<string, EntryLike> {
+	const receipts = new Map<string, EntryLike>();
+	for (const entry of branch) {
+		const key = receiptKey(entry);
+		if (key !== undefined) {
+			// A delivered completion wins over the launch, including when an edit omits it.
+			receipts.set(key, entry);
+		}
+	}
+	return receipts;
+}
+function recordedTouches(
+	evidence: NoteEvidence,
+	visible: readonly ScannedNoteEntry[],
+): NoteTouch[] {
+	const receipts = effectReceipts(evidence.branch);
+	const shown = new Map(visible.map((item) => [item.entry.id, item]));
+	const seen = new Set<string>();
+	return touchRecords(evidence.allEntries).flatMap((record) => {
+		const receipt = receipts.get(record.rootToolCallId);
+		const item = shown.get(receipt?.id);
+		const key = `${record.owner.id}\0${record.owner.timestamp}\0${record.toolCallId}`;
+		if (item === undefined || seen.has(key)) {
+			return [];
+		}
+		seen.add(key);
+		return record.files.map((file): NoteTouch => {
+			let kind: NoteTouch["kind"] = "observed-write";
+			if (file.kind === "read") {
+				kind = "read";
+			} else if (file.kind === "delete" || file.kind === "clear") {
+				kind = "clear";
+			}
+			return {
+				notePath: file.path,
+				absPath: join(scopeDirectory(file), file.path),
+				kind,
+				entryId: item.entryId,
+				receiptId: item.entry.id ?? item.entryId,
+				inRetained: false,
+				owner: record.owner,
+			};
+		});
+	});
+}
+function touchKey(touch: NoteTouch): string {
+	return JSON.stringify([touch.receiptId ?? touch.entryId, touch.absPath ?? touch.notePath]);
+}
+export function sessionNoteTouches(evidence: NoteEvidence): {
+	readonly touches: readonly NoteTouch[];
+	readonly defaultDir: string | undefined;
+	readonly visibleIds: ReadonlySet<string>;
+} {
+	const visible = projectedNotes(evidence);
+	const directories = new Set([
+		...bindingsOf(evidence.allEntries).map(scopeDirectory),
+		...(evidence.directories ?? []),
+	]);
+	const legacy = collectTouches(visible, directories);
+	const recorded = recordedTouches(evidence, visible);
+	const recordedByReceipt = new Map(recorded.map((touch) => [touchKey(touch), touch]));
+	const covered = new Set<string>();
+	const identified = legacy.touches.map((touch) => {
+		const key = touchKey(touch);
+		covered.add(key);
+		return { ...touch, owner: recordedByReceipt.get(key)?.owner };
+	});
+	const touches = [...identified, ...recorded.filter((touch) => !covered.has(touchKey(touch)))];
+	const order = new Map(visible.map((entry, index) => [entry.entry.id ?? entry.entryId, index]));
+	touches.sort(
+		(a, b) =>
+			(order.get(a.receiptId ?? a.entryId) ?? 0) - (order.get(b.receiptId ?? b.entryId) ?? 0),
+	);
+	return {
+		touches,
+		defaultDir: legacy.defaultDir,
+		visibleIds: new Set(visible.map((item) => item.entry.id ?? "")),
+	};
+}
+
+/** Inherited history describes source bytes, not necessarily the bytes snapshotted at fork time. */
+export function scopeRecoveryTouches(
+	touches: readonly NoteTouch[],
+	recovery: NotesRecovery | undefined,
+): readonly NoteTouch[] {
+	if (recovery === undefined || recovery.binding.kind === "project") {
+		return touches;
+	}
+	const owned = ownedPaths(recovery.binding, recovery.entries);
+	const scopes = [
+		recovery.binding,
+		...bindingsOf(recovery.entries),
+		...(recovery.binding.source === null ? [] : [recovery.binding.source]),
+	];
+	return touches.map((touch): NoteTouch => {
+		const address = touch.absPath === undefined ? undefined : addressOf(touch.absPath, scopes);
+		if (address !== undefined && sameScope(address, recovery.binding)) {
+			return touch;
+		}
+		const currentOwner =
+			touch.owner !== undefined && sameOwner(touch.owner, recovery.binding.owner);
+		if (owned.has(touch.notePath) && !currentOwner) {
+			return {
+				...touch,
+				absPath: notePath(recovery.binding, touch.notePath),
+				kind:
+					touch.kind === "read" || touch.kind === "clear" ? touch.kind : "observed-write",
+				inRetained: false,
+			};
+		}
+		return address === undefined
+			? touch
+			: {
+					...touch,
+					kind: "read",
+					referenceScope: scopeDirectory(address),
+					inRetained: false,
+				};
+	});
+}