pi-posthorse 0.10.12 → 0.10.14

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-posthorse",
-	"version": "0.10.12",
+	"version": "0.10.14",
 	"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/budget.ts

@@ -13,13 +13,6 @@ import {
 import { imagesOf, textOf } from "./message-text.ts";
 
 const MIN_USABLE_TOKENS = Math.ceil(MAX_HANDOFF_CHARS / 4) * 2;
-export const CHECKPOINT_GUIDANCE = `Keep working on the assigned task; Pi handles context rollover automatically.
-
-The current context window is not a deadline for finishing your task. Do not reduce scope, skip prescribed steps or verification, or issue a final progress summary because rollover is approaching.
-
-Update the task's current-state note if needed: goal, progress, decisions, and next steps. Use available file-editing tools at its absolute path; use notes write only for creation, substantial restructuring, or when editing tools are unavailable. Leave an already-current note unchanged. Then immediately execute the next prescribed task step in this run. No new_context call, waiting for rollover, or user "continue" is needed.
-
-Finish when the requested work and required verification are complete, or report a genuine blocker. Approaching context rollover is not a blocker.`;
 export type Budget = {
 	readonly contextWindow: number;
 	readonly reserveTokens: number;
@@ -84,8 +77,9 @@ function automaticGuidance(budget: Budget | undefined, enabled: boolean): string
 	const line =
 		budget === undefined
 			? ""
-			: ` The rollover line is ${budget.rolloverAt.toLocaleString("en-US")} tokens used under the available Pi settings.`;
-	return `${CHECKPOINT_GUIDANCE}\nAutomatic rollover follows Pi's compaction setting and retains a safe recent-message tail using compaction.keepRecentTokens, without model summarization.${line} At most one routine task-note reminder may arrive at the end of a working turn, never on a turn that ends the run. new_context is an optional deliberate clean reset, not a checkpoint requirement.`;
+			: `The rollover line is ${budget.rolloverAt.toLocaleString("en-US")} tokens used. `;
+	return `Pi rolls context over automatically, so the context window is not a deadline. Do not reduce scope, skip steps or verification, or write a final summary because rollover is near, and do not wait for the user to say "continue". Finish when the requested work and its verification are complete, or report a genuine blocker.
+${line}Rollover keeps a recent-message tail without summarizing. One task-note reminder may arrive at the end of a working turn near the line: update the note only if it is stale, then continue with the next step in the same run. new_context is an optional clean reset.`;
 }
 export function buildGuidance(ctx: PolicyContext): string {
 	const budget = budgetFor(ctx);
@@ -93,14 +87,12 @@ 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, retained recent messages, and new messages consume part of it.`;
+			: `Configured context capacity: ${budget.contextWindow.toLocaleString("en-US")} tokens (not remaining space).`;
 	return `## Automatic context management (Posthorse)
 ${automaticGuidance(budget, enabled)}
-${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.
+${capacity} Do not guess capacity or remaining space from response-token or reasoning limits. 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.
 After a rollover, earlier conversation stays in history. Restore notes and todos, then verify live state before stateful or external work; automatic handoffs record inputs, not progress.
-Keep one concise current-state note per task. Preserve decisions and safety constraints; link fuller evidence and history instead of copying them. Edit changed sections rather than resending unchanged content.
-Write handoffs and notes as normal readable prose; notes and history search match literal text.`;
+Keep one concise current-state note per task: goal, progress, decisions, and next steps. Preserve decisions and safety constraints, link fuller evidence instead of copying it, and edit only changed sections.`;
 }
 /** ponytail: native estimates omit request-local guidance; reserve it until post-transform usage is exposed. */
 export function guidanceTokens(ctx: PolicyContext): number {

package/src/history-pages.ts

@@ -84,13 +84,13 @@ export function searchPage(
 	host: PolicyContext,
 	pages: PageAccess,
 ): TextResult {
-	const chars = pages.size(host, { offset: 0, cursor: params.cursor });
+	const chars = pages.size(host);
 	const reserve = Math.max(
 		0,
 		...matches.hits.map((hit) => searchFooter(cursorFor(matches, hit, hit.text.length)).length),
 	);
 	if (reserve >= chars) {
-		pages.error(host, "History entry id is too large for pagination.", params.cursor);
+		pages.error(host, "History entry id is too large for pagination.");
 	}
 	const skippedNote =
 		matches.skipped > 0 && (params.cursor === undefined || params.cursor === "")
@@ -146,11 +146,7 @@ export function historyReadPage(
 	const shownId = shownEntryId(item, params.id, source);
 	const { offset, imageOffset } = readOffsets(item, params);
 	const firstImage = imageOffset < item.images.length ? 1 : 0;
-	const chars = access.pages.size(access.host, {
-		offset,
-		imageCount: firstImage,
-		imageOffset: item.images.length > 0 ? imageOffset : undefined,
-	});
+	const chars = access.pages.size(access.host, { imageCount: firstImage });
 	const imageEnd = Math.min(
 		item.images.length,
 		imageOffset + firstImage + Math.floor((chars - MIN_PAGE_CHARS) / ESTIMATED_IMAGE_CHARS),

package/src/history.ts

@@ -130,8 +130,7 @@ export function registerHistory(
 		async execute(...[, params, signal, , ctx]) {
 			const source = historySource(ctx);
 			if (params.op === "search") {
-				const fail = (message: string): never =>
-					pages.error(policy(ctx), message, params.cursor);
+				const fail = (message: string): never => pages.error(policy(ctx), message);
 				const matches = await historyMatches(source, params, signal, fail);
 				return searchPage(matches, params, policy(ctx), pages);
 			}

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

@@ -115,15 +115,10 @@ async function readNote(
 	const header = target.writable
 		? `File: ${path}\n`
 		: `Read-only live reference: notes read ${JSON.stringify({ scope: scopeDirectory(target.address), path: target.address.path })}\n`;
-	const host = access.host();
-	const chars = pages.size(host, { offset }) - header.length;
-	if (chars <= 0) {
-		pages.error(
-			host,
-			`Too little context remains to include the note path. Call new_context first, then retry with offset ${offset}.`,
-		);
-	}
-	const end = Math.min(text.length, offset + chars);
+	const end = Math.min(
+		text.length,
+		offset + pages.size(access.host(), { headerChars: header.length }),
+	);
 	const more =
 		end < text.length
 			? `\n[chars ${offset}-${end} of ${text.length}; continue with offset ${end}]`
@@ -295,7 +290,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/paging.ts

@@ -11,11 +11,10 @@ import {
 	type TextResult,
 } from "./contracts.ts";
 
+/** What else the page carries: images share the budget, and the header comes out of the body. */
 export type PageRequest = {
-	readonly offset: number;
 	readonly imageCount?: number;
-	readonly cursor?: string | undefined;
-	readonly imageOffset?: number | undefined;
+	readonly headerChars?: number;
 };
 export type NotesPage = {
 	readonly rows: readonly string[];
@@ -27,13 +26,13 @@ export type NotesPage = {
 	readonly more?: boolean;
 };
 export type PageAccess = {
-	readonly size: (ctx: PolicyContext, request: PageRequest) => number;
+	readonly size: (ctx: PolicyContext, request?: PageRequest) => number;
 	readonly result: (
 		text: string,
 		images: readonly ImageLike[],
 		display: PosthorseDisplay,
 	) => TextResult;
-	readonly error: (ctx: PolicyContext, message: string, cursor?: string) => never;
+	readonly error: (ctx: PolicyContext, message: string) => never;
 	readonly notes: (ctx: PolicyContext, page: NotesPage) => TextResult;
 };
 type PageAccounting = {
@@ -58,18 +57,22 @@ export class PageReservations {
 	reset(): void {
 		this.accounting = { pendingTokens: 0, usage: undefined };
 	}
-	size(ctx: PolicyContext, request: PageRequest): number {
-		this.accounting = reconcile(this.accounting, ctx.getContextUsage()?.tokens);
+	/**
+	 * Body characters for the next page. Near the rollover line pages shrink to MIN_PAGE_CHARS
+	 * instead of refusing, so reading keeps making progress; Pi's rollover handles the overshoot.
+	 */
+	size(ctx: PolicyContext, request: PageRequest = {}): number {
+		this.settle(ctx);
 		const remaining = pageCapacity(ctx, this.toolTokens) - this.accounting.pendingTokens;
-		const chars = Math.min(
+		const budget = Math.min(
 			MAX_PAGE_CHARS,
 			Math.max(0, remaining - PAGE_MARGIN_TOKENS) * 4 -
 				(request.imageCount ?? 0) * ESTIMATED_IMAGE_CHARS,
 		);
-		if (chars < MIN_PAGE_CHARS) {
-			this.refuse(remaining, request);
-		}
-		return chars;
+		return Math.max(MIN_PAGE_CHARS, budget - (request.headerChars ?? 0));
+	}
+	private settle(ctx: PolicyContext): void {
+		this.accounting = reconcile(this.accounting, ctx.getContextUsage()?.tokens);
 	}
 	private reserve(text: string, imageCount = 0): void {
 		this.accounting = {
@@ -80,38 +83,21 @@ export class PageReservations {
 				imageCount * (ESTIMATED_IMAGE_CHARS / 4),
 		};
 	}
-	private refuse(remaining: number, request: PageRequest): never {
-		const position =
-			request.cursor !== undefined && request.cursor !== ""
-				? "with the same cursor"
-				: `with offset ${request.offset}${request.imageOffset === undefined ? "" : ` and imageOffset ${request.imageOffset}`}`;
-		const message = `Too little context remains to read a page safely. Call new_context first, then retry ${position}.`;
-		// Even refusals consume context; omit repeated guidance when it no longer fits.
-		const text = Math.ceil(message.length / 4) <= remaining ? message : "";
-		this.reserve(text);
-		throw new Error(text);
-	}
 	result(text: string, images: readonly ImageLike[], display: PosthorseDisplay): TextResult {
 		this.reserve(text, images.length);
 		return textResult(text, images, display);
 	}
-	error(ctx: PolicyContext, message: string, cursor?: string): never {
-		this.size(ctx, { offset: 0, cursor });
+	error(ctx: PolicyContext, message: string): never {
+		this.settle(ctx);
 		this.reserve(message);
 		throw new Error(message);
 	}
 	notes(ctx: PolicyContext, page: NotesPage): TextResult {
 		const { rows, offset, kind, empty, header = "", more } = page;
 		const text = rows.length > 0 ? rows.join("\n") : empty;
-		const chars = this.size(ctx, { offset }) - header.length;
+		const chars = this.size(ctx, { headerChars: header.length });
 		const footer = (end: number) =>
 			`\n[chars ${offset}-${end}${more === true ? "; more matches follow" : ` of ${text.length}`}; continue with offset ${end}]`;
-		if (chars <= footer(text.length).length) {
-			this.error(
-				ctx,
-				`Too little context remains to include the notes path. Call new_context first, then retry with offset ${offset}.`,
-			);
-		}
 		if (offset > 0 && offset >= text.length) {
 			this.error(ctx, "Offset is past the end; restart with offset 0.");
 		}

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

@@ -6,7 +6,7 @@ import type {
 	SessionBeforeCompactEvent,
 	TurnEndEvent,
 } from "@earendil-works/pi-coding-agent";
-import { budgetFor, CHECKPOINT_GUIDANCE, freshPayloadChars } from "./budget.ts";
+import { budgetFor, freshPayloadChars } from "./budget.ts";
 import {
 	isRecord,
 	isReminderType,
@@ -457,7 +457,8 @@ export function registerRollover(
 			pi.sendMessage(
 				{
 					customType: REMINDER_TYPE,
-					content: `[posthorse] Routine task-note update.\n${CHECKPOINT_GUIDANCE}`,
+					content:
+						"[posthorse] Routine task-note update. Update the task's current-state note if it is stale, then continue with the next step in this run.",
 					display: true,
 					details: reminder.fingerprint,
 				},