pi-posthorse 0.10.11 → 0.10.13

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-posthorse",
-	"version": "0.10.11",
+	"version": "0.10.13",
 	"type": "module",
 	"description": "Posthorse: fresh context, same journey. No-summary context rollover for Pi, with sparse budget reminders, handoffs, notes, and history.",
 	"keywords": [

package/src/note-evidence.ts

@@ -156,9 +156,11 @@ export function scopeRecoveryTouches(
 		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) {
+		// This session's own file-tool effects keep their recorded address and kind in any scope.
+		if (touch.owner !== undefined && sameOwner(touch.owner, recovery.binding.owner)) {
+			return touch;
+		}
+		if (owned.has(touch.notePath)) {
 			return {
 				...touch,
 				absPath: notePath(recovery.binding, touch.notePath),

package/src/note-guards.ts

@@ -5,10 +5,7 @@ import { withFileMutationQueue, type ExtensionAPI } from "@earendil-works/pi-cod
 import {
 	addressOf,
 	canonicalPath,
-	inside,
-	notePath,
 	sameScope,
-	scopeDirectory,
 	type NoteAddress,
 	type NoteTouchRecord,
 } from "./note-scopes.ts";
@@ -68,48 +65,21 @@ function existingEdit(tool: string, operation: NoteOperation): boolean {
 		(tool === "write_files" && (operation.action === "write" || operation.action === "clear"))
 	);
 }
-async function guardForeign(
-	address: NoteAddress,
-	operation: NoteOperation,
-	captured: CapturedCall,
-): Promise<string> {
-	const { session, tool, call } = captured;
+/** An edit of an inherited note in this session's scope applies to its private copy. */
+async function prepareOperation(operation: NoteOperation, captured: CapturedCall): Promise<void> {
 	if (operation.action === "read") {
-		return `This is another notes scope. Use notes read with ${JSON.stringify({ scope: scopeDirectory(address), path: address.path })} for a labeled read-only comparison, or omit scope to read this session’s copy.`;
+		return;
 	}
-	return existingEdit(tool, operation) &&
-		session.scopes.some((scope) => sameScope(scope, address))
-		? session.guardReference(address.path, call)
-		: `The foreign note was not changed. This session writes ${notePath(session.binding, address.path)}. Retry explicitly there; creation semantics were not changed.`;
-}
-async function guardOperation(
-	operation: NoteOperation,
-	captured: CapturedCall,
-): Promise<string | undefined> {
 	const { session, call, tool, cwd } = captured;
 	const path = toolPath(tool, operation.path, cwd);
 	const address = await noteAddress(path, session);
-	if (address === undefined) {
-		return operation.action !== "read" &&
-			session.scopes.some((scope) =>
-				inside(canonicalPath(join(scope.root, ".forks")), canonicalPath(path)),
-			)
-			? `Managed notes metadata is not editable through file tools: ${path}. Use notes for this session’s checkpoint.`
-			: undefined;
-	}
-	if (!sameScope(address, session.binding)) {
-		return guardForeign(address, operation, captured);
+	if (address === undefined || !sameScope(address, session.binding)) {
+		return;
 	}
 	if (existingEdit(tool, operation) && !session.owns(address.path)) {
-		const copied = await withFileMutationQueue(path, () => session.adopt(address.path, call));
-		if (copied === "adopted") {
-			return `Private copy created at ${path}; no requested edit ran. Read this copy, then retry the edit.`;
-		}
-	}
-	if (operation.action !== "read") {
-		await session.prepareWrite();
+		await withFileMutationQueue(path, () => session.adopt(address.path, call));
 	}
-	return;
+	await session.prepareWrite();
 }
 async function recordedFiles(
 	operations: readonly NoteOperation[],
@@ -148,42 +118,22 @@ async function recordedFiles(
 export function registerNoteGuards(pi: ExtensionAPI, store: NotesStore): void {
 	const calls = new Map<string, CapturedCall>();
 	pi.on("tool_call", async (event, ctx) => {
-		const operations = noteOperations(event.toolName, event.input);
-		const session = await store.get(ctx).catch((error: unknown) => {
-			if (
-				event.toolName === "notes" ||
-				operations.some((operation) =>
-					store
-						.roots()
-						.some((root) =>
-							inside(
-								root,
-								canonicalPath(toolPath(event.toolName, operation.path, ctx.cwd)),
-							),
-						),
-				)
-			) {
-				throw error;
-			}
-			return;
-		});
-		if (session === undefined) {
+		let session: SessionNotes;
+		try {
+			session = await store.get(ctx);
+		} catch {
+			// Failed notes initialization skips bookkeeping; the notes tool reports the error itself.
 			return;
 		}
 		const call = session.startCall(event.toolCallId, event.parentToolCallId);
 		const captured = { session, call, cwd: ctx.cwd, tool: event.toolName };
 		calls.set(event.toolCallId, captured);
-		if (event.toolName === "notes" || operations.length === 0) {
+		if (event.toolName === "notes") {
 			return;
 		}
-		for (const operation of operations) {
-			// Preflight never mutates arguments; a copied reference needs a fresh read before retry.
-			const reason = await guardOperation(operation, captured);
-			if (reason !== undefined) {
-				return { block: true, reason };
-			}
+		for (const operation of noteOperations(event.toolName, event.input)) {
+			await prepareOperation(operation, captured);
 		}
-		return;
 	});
 	pi.on("tool_result", async (event) => {
 		const captured = calls.get(event.toolCallId);

package/src/note-provenance.ts

@@ -195,11 +195,6 @@ function seedCandidates(
 		retained: new Set(),
 		directories: new Set(scopes.map(scopeDirectory)),
 	});
-	if (scope === undefined && evidence.touches.length > 0) {
-		throw new Error(
-			"Incomplete notes snapshot: the source notes root is missing or ambiguous.",
-		);
-	}
 	const selected = touchedCandidates(evidence, scopes, allEntries);
 	for (const binding of bindings) {
 		for (const seed of seedsOf(binding, allEntries)) {
@@ -232,6 +227,7 @@ async function forkBinding(
 	);
 	for (const [index, candidate] of candidates.entries()) {
 		// Resolve against the immediate parent's files, not a historical ancestor's version.
+		// A missing source note is not copied; a known source scope still resolves it later.
 		const address = addresses[index];
 		if (address !== undefined) {
 			files.push({
@@ -242,10 +238,6 @@ async function forkBinding(
 			});
 		} else if (candidate.cleared) {
 			absent.push(candidate.path);
-		} else {
-			throw new Error(
-				`Incomplete notes snapshot: source note ${candidate.path} is unavailable.`,
-			);
 		}
 	}
 	return snapshot(

package/src/note-store.ts

@@ -1,10 +1,6 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import {
-	withFileMutationQueue,
-	type ExtensionAPI,
-	type ExtensionContext,
-} from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { EntryLike, ProjectedEntry } from "./contracts.ts";
 import { notesDir } from "./files.ts";
 import { adoptNote, ensureManifest, readManifest, saveAdoption } from "./note-snapshots.ts";
@@ -219,13 +215,6 @@ export class SessionNotes {
 	async prepareWrite(): Promise<void> {
 		await ensureManifest(this.binding);
 	}
-	async guardReference(path: string, call: NoteCall): Promise<string> {
-		const destination = notePath(this.binding, path);
-		const copied = await withFileMutationQueue(destination, () => this.adopt(path, call));
-		return copied === "adopted"
-			? `Private copy created at ${destination}; the source was not edited. Read the private copy, then retry the edit on that path.`
-			: `This session writes only ${this.directory}. Read ${destination}, then retry there; the foreign path was not edited.`;
-	}
 }
 function sessionKey(ctx: ExtensionContext): string {
 	const header = ctx.sessionManager.getHeader();
@@ -236,7 +225,6 @@ function sessionKey(ctx: ExtensionContext): string {
 }
 export type NotesStore = {
 	readonly get: (ctx: ExtensionContext) => Promise<SessionNotes>;
-	readonly roots: () => readonly string[];
 	readonly recovery: (ctx: ExtensionContext) => NotesRecovery | undefined;
 };
 type SessionState =
@@ -244,7 +232,6 @@ type SessionState =
 	| { readonly kind: "ready"; readonly value: SessionNotes };
 export function createNotesStore(pi: ExtensionAPI): NotesStore {
 	const sessions = new Map<string, SessionState>();
-	const roots = new Set<string>();
 	const get = (ctx: ExtensionContext): Promise<SessionNotes> => {
 		const key = sessionKey(ctx);
 		const existing = sessions.get(key);
@@ -258,19 +245,12 @@ export function createNotesStore(pi: ExtensionAPI): NotesStore {
 		const root =
 			bindings.findLast((binding) => header !== null && sameOwner(binding.owner, header))
 				?.root ?? canonicalPath(notesDir(ctx.cwd));
-		roots.add(root);
-		for (const binding of bindings) {
-			roots.add(binding.root);
-		}
 		const initialized = loadNotesBinding(ctx.sessionManager, root)
 			.then(({ binding, source, created }) => {
 				if (created) {
 					pi.appendEntry(NOTES_BINDING, binding);
 				}
 				const session = new SessionNotes(pi, binding, ctx.sessionManager, source);
-				for (const scope of session.scopes) {
-					roots.add(scope.root);
-				}
 				sessions.set(key, { kind: "ready", value: session });
 				return session;
 			})
@@ -283,7 +263,6 @@ export function createNotesStore(pi: ExtensionAPI): NotesStore {
 	};
 	return {
 		get,
-		roots: () => [...roots],
 		recovery: (ctx: ExtensionContext) => {
 			const state = sessions.get(sessionKey(ctx));
 			return state?.kind === "ready" ? state.value.recovery : undefined;

package/src/notes.ts

@@ -295,7 +295,7 @@ export function registerNotes(
 		label: "Notes",
 		...toolCards("notes"),
 		description:
-			"Durable notes across Git worktrees and context resets. Forks own private copies of selected-branch notes. Ops: list (newest first, size/date; optional folder), read, search (case-insensitive text), write (replace; empty clears), append (one newline-terminated record). list/search discover project-wide notes with scope selectors; use scope for read-only comparisons or a single-scope view. Omit scope for current notes and live references. list/read/search are paged; continue with the returned offset. list shows the current writable directory; current-file reads show an editable path, foreign reads a read-only reference. Edit the returned current path for small changes. A blocked foreign edit may have created a private copy: read that copy before retrying. Append adopts unowned references without losing their text. Keep one concise current-state note and link fuller evidence.",
+			"Durable task notes shared across Git worktrees and context resets; forks get private copies. Ops: list (newest first), read, search (case-insensitive), write (replace; empty clears), append (one record). list/search also cover other sessions' note scopes and show their selectors; pass scope to read, list, or search one of them. list/read/search are paged; continue with the returned offset. A read of a current note returns its file path.",
 		promptSnippet: "save and recall durable state with private notes for forks",
 		parameters: Type.Object({
 			op: Type.Union(

package/src/recovery-note-touches.ts

@@ -77,8 +77,11 @@ function matchMarkerPath(slash: string): string | undefined {
 	return /\/\.pi\/(?:agent\/)?notes\/[^/]+\/[^/]+\/[^/]+\/(.+)$/u.exec(slash)?.[1];
 }
 
+function absoluteSlashPath(slash: string): boolean {
+	return slash.startsWith("/") || /^[A-Za-z]:\//u.test(slash);
+}
 function unscopedNoteTarget(trimmed: string, slash: string): NoteTarget | undefined {
-	if (slash.startsWith("/") || /^[A-Za-z]:\//u.test(slash)) {
+	if (absoluteSlashPath(slash)) {
 		const base = normalizeRelPath(slash.slice(slash.lastIndexOf("/") + 1));
 		return base === "" ? undefined : { notePath: base, absPath: trimmed };
 	}
@@ -98,7 +101,14 @@ function resolveNoteTarget(
 	const matched = matchNoteDirectory(slash, [...knownDirs])?.path ?? matchMarkerPath(slash);
 	if (matched !== undefined) {
 		const rel = matched.startsWith(".forks/") ? "" : normalizeRelPath(matched);
-		return rel === "" ? undefined : { notePath: rel, absPath: trimmed };
+		if (rel === "") {
+			return undefined;
+		}
+		if (absoluteSlashPath(slash)) {
+			return { notePath: rel, absPath: trimmed };
+		}
+		// The journal does not record a file tool's working directory, so its relative path has no known base.
+		return fromNotesTool ? { notePath: rel } : undefined;
 	}
 	return fromNotesTool ? unscopedNoteTarget(trimmed, slash) : undefined;
 }

package/src/recovery-notes.ts

@@ -1,5 +1,7 @@
+import { join } from "node:path";
 import type { EntryLike, ProjectedEntry } from "./contracts.ts";
 import { sessionNoteTouches, scopeRecoveryTouches, type NotesRecovery } from "./note-evidence.ts";
+import { scopeDirectory } from "./note-scopes.ts";
 import type { NoteTarget, NoteTouch } from "./recovery-note-touches.ts";
 
 const MAX_WRITTEN_NOTES = 4;
@@ -77,7 +79,7 @@ function applyTouch(
 }
 function formatNoteLabel(note: TrackedNote): string {
 	if (note.referenceScope !== undefined) {
-		return `${note.notePath} (read-only reference; notes read ${JSON.stringify({ scope: note.referenceScope, path: note.notePath })})`;
+		return `${note.notePath} (another notes scope: ${note.absPath ?? `${note.referenceScope}/${note.notePath}`})`;
 	}
 	return note.absPath !== undefined && note.absPath !== note.notePath
 		? `${note.notePath} (${note.absPath})`
@@ -116,14 +118,22 @@ function formatReadNoteLine(note: ReadNote, span: RetainedSpan | undefined): str
 function formatNotesAction(
 	primaryWritten: WrittenNote | undefined,
 	span: RetainedSpan | undefined,
+	notesDirectory: string | undefined,
 ): string {
 	if (primaryWritten === undefined) {
 		return "Read the referenced note again if its context is still needed, and keep one current-state note for this task.";
 	}
+	// notes read resolves a bare name in this session's own scope, so a note elsewhere is named by its path.
+	const elsewhere =
+		primaryWritten.absPath !== undefined &&
+		notesDirectory !== undefined &&
+		primaryWritten.absPath !== join(notesDirectory, primaryWritten.notePath);
+	const target = elsewhere ? primaryWritten.absPath : primaryWritten.notePath;
 	if (span !== undefined && primaryWritten.proof.kind === "full") {
-		return `Your latest full write to ${primaryWritten.notePath} is already visible above at entry ${primaryWritten.proof.entryId}; do not rewrite it unless new findings after entry ${span.lastId} require it.`;
+		return `Your latest full write to ${target} is already visible above at entry ${primaryWritten.proof.entryId}; do not rewrite it unless new findings after entry ${span.lastId} require it.`;
 	}
-	return `Read ${primaryWritten.notePath} (notes read or read on its path) before continuing to restore the saved goal, progress, decisions, and next steps, then keep that note current as work progresses.`;
+	const how = elsewhere ? "read on its path" : "notes read or read on its path";
+	return `Read ${target} (${how}) before continuing to restore the saved goal, progress, decisions, and next steps, then keep that note current as work progresses.`;
 }
 function trackedNotes(
 	touches: readonly NoteTouch[],
@@ -176,7 +186,11 @@ export function renderSessionNotes(
 		...readOnly.map((note) => formatReadNoteLine(note, span)),
 	];
 	const header = "Task notes in this session:";
-	const action = formatNotesAction(written[0], span);
+	const action = formatNotesAction(
+		written[0],
+		span,
+		options.notes === undefined ? defaultDir : scopeDirectory(options.notes.binding),
+	);
 	const selected: string[] = [];
 	for (const line of lines) {
 		if ([header, ...selected, line, action].join("\n").length <= maxChars) {

package/src/rollover.ts

@@ -1,6 +1,6 @@
 import type {
 	BoundaryResult,
-	ContextEvent,
+	ContextWithSystemEvent,
 	ExtensionAPI,
 	ExtensionContext,
 	SessionBeforeCompactEvent,
@@ -113,25 +113,41 @@ function staleReminderPredicate(
 		isReminderType(message.customType) &&
 		(!enabled || !reminderMatches(message.details, fingerprint));
 }
+function retainedTailEnd(
+	messages: ContextWithSystemEvent["messages"],
+	start: number,
+	count: number,
+): number | undefined {
+	let remaining = count;
+	for (let index = start; index < messages.length; index += 1) {
+		if (messages[index]?.role !== "system") {
+			remaining -= 1;
+		}
+		if (remaining === 0) {
+			return index + 1;
+		}
+	}
+	return undefined;
+}
 function chronologicalRetainedTail(
-	messages: ContextEvent["messages"],
+	messages: ContextWithSystemEvent["messages"],
 	ctx: ExtensionContext,
 	stale: StaleReminderPredicate,
-): ContextEvent["messages"] {
-	const first = messages[0];
-	if (
-		messages.length >= 2 &&
-		first?.role === "compactionSummary" &&
-		hasRetainedRolloverMarker(first.summary)
-	) {
+): ContextWithSystemEvent["messages"] {
+	const summaryIndex = messages.findIndex((message) => message.role !== "system");
+	const first = messages[summaryIndex];
+	if (first?.role === "compactionSummary" && hasRetainedRolloverMarker(first.summary)) {
 		const count = countRetainedMessages(ctx, stale);
-		if (count > 0 && 1 + count <= messages.length) {
-			const retainedSlice = messages.slice(1, 1 + count);
-			const afterSlice = messages.slice(1 + count);
-			if (retainedSlice[0]?.role !== "assistant") {
-				return [...retainedSlice, first, ...afterSlice];
+		const end = count > 0 ? retainedTailEnd(messages, summaryIndex + 1, count) : undefined;
+		if (end !== undefined) {
+			const prefix = messages.slice(0, summaryIndex);
+			const retainedSlice = messages.slice(summaryIndex + 1, end);
+			const afterSlice = messages.slice(end);
+			if (retainedSlice.find((message) => message.role !== "system")?.role !== "assistant") {
+				return [...prefix, ...retainedSlice, first, ...afterSlice];
 			}
 			return [
+				...prefix,
 				{
 					role: "custom",
 					customType: "posthorse-retained-tail",
@@ -152,7 +168,7 @@ function registerReminderFilter(
 	policy: SnapshotReader,
 	reminders: ReminderLookup,
 ): void {
-	pi.on("context", (event, ctx) => {
+	pi.on("context_with_system", (event, ctx) => {
 		const stale = staleReminderPredicate(event.messages, ctx, policy, reminders);
 		const filtered = event.messages.some(stale)
 			? event.messages.filter((message) => !stale(message))
@@ -411,8 +427,8 @@ export function registerRollover(
 	pi.on("session_tree", () => {
 		reminders.reset();
 	});
-	registerGuidance(pi, policy);
 	registerReminderFilter(pi, policy, reminders);
+	registerGuidance(pi, policy);
 	registerAutomaticRollover(pi, policy, activeToolTokens, resources.notes);
 	pi.on("turn_end", (event, ctx) => {
 		const summary = resetRequests.take(event.toolResults);