pi-posthorse 0.10.22 → 0.10.24

package/index.ts

@@ -12,6 +12,7 @@ import {
 import { registerPosthorseMessages } from "./ui.ts";
 import { policySnapshot } from "./src/budget.ts";
 import type { CompactionPolicy, PolicyReader } from "./src/contracts.ts";
+import { createWindowGuidance } from "./src/guidance.ts";
 import { registerHistory } from "./src/history.ts";
 import { safeJsonStringify } from "./src/message-text.ts";
 import { registerNotes } from "./src/notes.ts";
@@ -44,8 +45,11 @@ export function createPosthorse(getPolicy?: PolicyReader): (pi: ExtensionAPI) =>
 		const readPolicy: PolicyReader =
 			getPolicy ??
 			((ctx) => SettingsManager.inMemory(pi.getSettings()).getCompactionSettings(ctx.model));
+		const guidance = createWindowGuidance(pi);
 		const policy = (ctx: ExtensionContext, livePolicy?: CompactionPolicy) =>
-			policySnapshot(ctx, readPolicy, livePolicy);
+			policySnapshot(ctx, readPolicy, livePolicy, (target, host) =>
+				guidance.resolve(target, host),
+			);
 		const toolTokens = () => activeToolTokens(pi);
 		const pages = new PageReservations(toolTokens);
 		registerPosthorseMessages(pi);
@@ -55,6 +59,7 @@ export function createPosthorse(getPolicy?: PolicyReader): (pi: ExtensionAPI) =>
 				pages.reset();
 			},
 			notes: (ctx) => notes.recovery(ctx),
+			guidance,
 		});
 		pi.on("session_start", async (_event, ctx) => {
 			await notes.get(ctx);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-posthorse",
-	"version": "0.10.22",
+	"version": "0.10.24",
 	"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,6 +13,14 @@ import {
 import { imagesOf, textOf } from "./message-text.ts";
 
 const MIN_USABLE_TOKENS = Math.ceil(MAX_HANDOFF_CHARS / 4) * 2;
+export type GuidanceTools = {
+	readonly newContext: boolean;
+	readonly getContextRemaining: boolean;
+};
+export const ALL_GUIDANCE_TOOLS: GuidanceTools = {
+	newContext: true,
+	getContextRemaining: true,
+};
 export type Budget = {
 	readonly contextWindow: number;
 	readonly reserveTokens: number;
@@ -26,11 +34,13 @@ export function policySnapshot(
 	ctx: ExtensionContext,
 	getPolicy: PolicyReader,
 	livePolicy?: CompactionPolicy,
+	resolveGuidance?: (ctx: ExtensionContext, host: PolicyContext) => string,
 ): PolicyContext {
 	let usageRead = false;
 	let usage: ContextUsage | undefined;
 	let settings: CompactionPolicy | undefined;
-	return {
+	let guidance: string | undefined;
+	const host: PolicyContext = {
 		getCompactionSettings: () => {
 			settings ??= { ...(livePolicy ?? getPolicy(ctx)) };
 			return settings;
@@ -43,7 +53,13 @@ export function policySnapshot(
 			return usage;
 		},
 		getSystemPrompt: () => ctx.getSystemPrompt(),
+		getGuidance: () => {
+			guidance ??=
+				resolveGuidance !== undefined ? resolveGuidance(ctx, host) : buildGuidance(host);
+			return guidance;
+		},
 	};
+	return host;
 }
 export function budgetFor(
 	ctx: PolicyContext,
@@ -63,45 +79,75 @@ export function budgetFor(
 		supported: !enabled || usable >= MIN_USABLE_TOKENS,
 	};
 }
-export function unsupportedMessage(budget: Budget): string {
+export function budgetGuidanceKey(ctx: PolicyContext): string {
+	const budget = budgetFor(ctx);
+	if (budget === undefined) {
+		return ctx.getCompactionSettings().enabled ? "1:unknown" : "0:unknown";
+	}
+	return budget.enabled
+		? `1:${budget.contextWindow}:${budget.reserveTokens}`
+		: `0:${budget.contextWindow}`;
+}
+export function unsupportedMessage(budget: Budget, newContextAvailable = true): string {
 	const n = (value: number) => value.toLocaleString("en-US");
-	return `Posthorse: unsupported configuration. The model's context window (${n(budget.contextWindow)} tokens) minus Pi's compaction.reserveTokens (${n(budget.reserveTokens)}) leaves ${n(budget.usable)} usable tokens; Posthorse needs at least ${n(MIN_USABLE_TOKENS)}. Automatic Posthorse rollover and checkpoint reminders are off for this model, so Pi's own compaction applies. Lower compaction.reserveTokens in Pi settings or use a larger-context model. new_context remains available with a model-aware handoff limit.`;
+	const reset = newContextAvailable
+		? " new_context remains available with a model-aware handoff limit."
+		: "";
+	return `Posthorse: unsupported configuration. The model's context window (${n(budget.contextWindow)} tokens) minus Pi's compaction.reserveTokens (${n(budget.reserveTokens)}) leaves ${n(budget.usable)} usable tokens; Posthorse needs at least ${n(MIN_USABLE_TOKENS)}. Automatic Posthorse rollover and checkpoint reminders are off for this model, so Pi's own compaction applies. Lower compaction.reserveTokens in Pi settings or use a larger-context model.${reset}`;
 }
-function automaticGuidance(budget: Budget | undefined, enabled: boolean): string {
+function automaticGuidance(
+	budget: Budget | undefined,
+	enabled: boolean,
+	tools: GuidanceTools,
+): string {
 	if (!enabled) {
-		return "Pi compaction is disabled in the available settings, so Posthorse sends no checkpoint reminder. new_context remains available.";
+		const reset = tools.newContext ? " new_context remains available." : "";
+		return `Pi compaction is disabled in the available settings, so Posthorse sends no checkpoint reminder.${reset}`;
 	}
 	if (budget !== undefined && !budget.supported) {
-		return unsupportedMessage(budget);
+		return unsupportedMessage(budget, tools.newContext);
 	}
 	const line =
 		budget === undefined
 			? ""
 			: `The rollover line is ${budget.rolloverAt.toLocaleString("en-US")} tokens used. `;
+	const reset = tools.newContext ? " new_context is an optional clean reset." : "";
 	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, or write one if the task has none, then continue with the next step in the same run. new_context is an optional clean reset.`;
+${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, or write one if the task has none, then continue with the next step in the same run.${reset}`;
 }
-export function buildGuidance(ctx: PolicyContext): string {
+export function buildGuidance(
+	ctx: PolicyContext,
+	tools: GuidanceTools = ALL_GUIDANCE_TOOLS,
+): string {
 	const budget = budgetFor(ctx);
 	const enabled = budget?.enabled ?? ctx.getCompactionSettings().enabled;
 	const capacity =
 		budget === undefined
 			? "Configured context capacity is unknown."
 			: `Configured context capacity: ${budget.contextWindow.toLocaleString("en-US")} tokens (not remaining space).`;
+	const checkRemaining = tools.getContextRemaining
+		? " Before reporting a remaining-token count or changing your work plan because of context limits, call get_context_remaining."
+		: "";
 	return `## Automatic context management (Posthorse)
-${automaticGuidance(budget, enabled)}
-${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.
+${automaticGuidance(budget, enabled, tools)}
+${capacity} Do not guess capacity or remaining space from response-token or reasoning limits.${checkRemaining} 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: 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 {
+export function guidanceFor(ctx: PolicyContext): string {
+	return ctx.getGuidance !== undefined ? ctx.getGuidance() : buildGuidance(ctx);
+}
+function guidanceTokenCount(guidance: string): number {
 	return estimateTokens({
 		role: "system",
-		content: `<posthorse>\n${buildGuidance(ctx)}\n</posthorse>`,
+		content: `<posthorse>\n${guidance}\n</posthorse>`,
 		timestamp: 0,
 	});
 }
+/** ponytail: native estimates omit request-local guidance; reserve it until post-transform usage is exposed. */
+export function guidanceTokens(ctx: PolicyContext): number {
+	return guidanceTokenCount(guidanceFor(ctx));
+}
 /** Half the fresh capacity after prompt/tool/input overhead remains for continued work. */
 export function freshPayloadChars(
 	ctx: PolicyContext,
@@ -114,7 +160,9 @@ export function freshPayloadChars(
 		return cap;
 	}
 	const line = budget.enabled && budget.supported ? budget.rolloverAt : budget.contextWindow;
-	const promptTokens = Math.ceil(ctx.getSystemPrompt().length / 4) + guidanceTokens(ctx);
+	const reservedGuidance =
+		cap === MAX_HANDOFF_CHARS ? guidanceTokenCount(buildGuidance(ctx)) : guidanceTokens(ctx);
+	const promptTokens = Math.ceil(ctx.getSystemPrompt().length / 4) + reservedGuidance;
 	const pendingTokens = pendingMessages.reduce(
 		(total, message) =>
 			total +

package/src/context-tools.ts

@@ -2,6 +2,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { Type } from "typebox";
 import { toolCards, type PosthorseDisplay } from "../ui.ts";
 import { budgetFor, freshPayloadChars, unsupportedMessage, type Budget } from "./budget.ts";
+import { activeGuidanceTools } from "./guidance.ts";
 import {
 	EMPTY_HANDOFF,
 	MAX_HANDOFF_CHARS,
@@ -16,7 +17,7 @@ function rolloverStatus(budget: Budget | undefined): "disabled" | "enabled" | "u
 	}
 	return budget.supported ? "enabled" : "unsupported";
 }
-function contextReport(host: PolicyContext): TextResult {
+function contextReport(host: PolicyContext, newContextAvailable: boolean): TextResult {
 	const usage = host.getContextUsage();
 	if (usage === undefined || usage.tokens === null) {
 		return textResult("Context usage is not known until the next model response.", [], {
@@ -41,7 +42,11 @@ function contextReport(host: PolicyContext): TextResult {
 		);
 	}
 	if (!budget.supported) {
-		return textResult(`${unsupportedMessage(budget)} ${configured}`, [], display);
+		return textResult(
+			`${unsupportedMessage(budget, newContextAvailable)} ${configured}`,
+			[],
+			display,
+		);
 	}
 	return textResult(
 		`≈${n(Math.max(0, budget.rolloverAt - usage.tokens))} tokens until automatic rollover (line at ${n(budget.rolloverAt)}); ${configured}`,
@@ -97,7 +102,7 @@ export function registerContextTools(
 			"verify remaining context before reporting a token count or changing plans because of context limits",
 		parameters: Type.Object({}),
 		async execute(...[, , , , ctx]) {
-			return contextReport(policy(ctx));
+			return contextReport(policy(ctx), activeGuidanceTools(pi).newContext);
 		},
 	});
 }

package/src/contracts.ts

@@ -17,6 +17,7 @@ export type PolicyContext = {
 	readonly getCompactionSettings: () => CompactionPolicy;
 	readonly getContextUsage: () => ContextUsage | undefined;
 	readonly getSystemPrompt: () => string;
+	readonly getGuidance?: () => string;
 };
 export type PolicyReader = (ctx: ExtensionContext) => CompactionPolicy;
 export type SnapshotReader = (
@@ -70,6 +71,7 @@ export type EntryLike = {
 	readonly parentSession?: string | undefined;
 	readonly handoff?: string | undefined;
 	readonly firstKeptEntryId?: string | null | undefined;
+	readonly providerSummary?: unknown;
 	readonly targetId?: string | undefined;
 	readonly replacement?: { readonly content: unknown } | null | undefined;
 };

package/src/guidance.ts

@@ -1,8 +1,250 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { buildGuidance } from "./budget.ts";
-import type { SnapshotReader } from "./contracts.ts";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type, type Static } from "typebox";
+import { Check } from "typebox/value";
+import {
+	ALL_GUIDANCE_TOOLS,
+	budgetGuidanceKey,
+	buildGuidance,
+	type GuidanceTools,
+} from "./budget.ts";
+import { isRecord, type EntryLike, type PolicyContext, type SnapshotReader } from "./contracts.ts";
 
-export function registerGuidance(pi: ExtensionAPI, policy: SnapshotReader): void {
+export const WINDOW_GUIDANCE_TYPE = "posthorse-window-guidance";
+const guidanceRecordSchema = Type.Object({
+	version: Type.Literal(1),
+	budgetKey: Type.String(),
+	text: Type.String(),
+	tools: Type.Object({
+		newContext: Type.Boolean(),
+		getContextRemaining: Type.Boolean(),
+	}),
+});
+type WindowGuidanceRecord = Static<typeof guidanceRecordSchema>;
+type MemoryEpoch = {
+	readonly byBudget: Map<string, string>;
+	tools: GuidanceTools | undefined;
+};
+type EpochState = {
+	readonly manager: ExtensionContext["sessionManager"];
+	readonly sessionId: string;
+	readonly file: string | undefined;
+	readonly leaf: EntryLike | undefined;
+	readonly anchorKey: string;
+	readonly byBudget: ReadonlyMap<string, string>;
+	readonly tools: GuidanceTools | undefined;
+};
+export type WindowGuidance = {
+	readonly resolve: (ctx: ExtensionContext, host: PolicyContext) => string;
+	readonly deliver: (ctx: ExtensionContext, host: PolicyContext) => string;
+	readonly reset: () => void;
+};
+
+export function activeGuidanceTools(pi: ExtensionAPI): GuidanceTools {
+	const active = new Set(pi.getActiveTools());
+	const unnamespaced = new Set(
+		pi
+			.getAllTools()
+			.filter((tool) => tool.namespace === undefined)
+			.map((tool) => tool.name),
+	);
+	return {
+		newContext: active.has("new_context") && unnamespaced.has("new_context"),
+		getContextRemaining:
+			active.has("get_context_remaining") && unnamespaced.has("get_context_remaining"),
+	};
+}
+/**
+ * A compaction with a provider summary block carries forward the previous window's leading system
+ * message unchanged, so its guidance section must stay locked to that earlier epoch too.
+ */
+function startsFreshGuidanceEpoch(entry: EntryLike): boolean {
+	if (entry.type === "context_window") {
+		return true;
+	}
+	return (
+		entry.type === "compaction" &&
+		!(isRecord(entry.providerSummary) && isRecord(entry.providerSummary.block))
+	);
+}
+function parentEntry(
+	manager: ExtensionContext["sessionManager"],
+	id: string | null | undefined,
+): EntryLike | undefined {
+	const raw: unknown = manager;
+	if (id === undefined || id === null || id === "" || !isRecord(raw)) {
+		return undefined;
+	}
+	return typeof raw.getEntry === "function" ? manager.getEntry(id) : undefined;
+}
+function sessionIdentityOf(manager: ExtensionContext["sessionManager"]): {
+	readonly sessionId: string;
+	readonly file: string | undefined;
+	readonly leaf: EntryLike | undefined;
+} {
+	const raw: unknown = manager;
+	const sessionId =
+		isRecord(raw) && typeof raw.getSessionId === "function" ? manager.getSessionId() : "";
+	const file =
+		isRecord(raw) && typeof raw.getSessionFile === "function"
+			? manager.getSessionFile()
+			: undefined;
+	const leafId =
+		isRecord(raw) && typeof raw.getLeafId === "function" ? manager.getLeafId() : null;
+	return { sessionId, file, leaf: parentEntry(manager, leafId) };
+}
+function collectGuidanceEntries(
+	entries: readonly EntryLike[],
+	baseByBudget?: ReadonlyMap<string, string>,
+	baseTools?: GuidanceTools,
+): { readonly byBudget: Map<string, string>; readonly tools: GuidanceTools | undefined } {
+	const byBudget = new Map<string, string>(baseByBudget);
+	let tools = baseTools;
+	for (const entry of entries) {
+		if (
+			entry.type === "custom" &&
+			entry.customType === WINDOW_GUIDANCE_TYPE &&
+			Check(guidanceRecordSchema, entry.data)
+		) {
+			byBudget.set(entry.data.budgetKey, entry.data.text);
+			tools ??= entry.data.tools;
+		}
+	}
+	return { byBudget, tools };
+}
+function withMemoryEpoch(
+	collected: {
+		readonly byBudget: Map<string, string>;
+		readonly tools: GuidanceTools | undefined;
+	},
+	memory: MemoryEpoch | undefined,
+): { readonly byBudget: ReadonlyMap<string, string>; readonly tools: GuidanceTools | undefined } {
+	if (memory === undefined) {
+		return collected;
+	}
+	const merged = new Map(collected.byBudget);
+	for (const [key, text] of memory.byBudget) {
+		if (!merged.has(key)) {
+			merged.set(key, text);
+		}
+	}
+	return { byBudget: merged, tools: collected.tools ?? memory.tools };
+}
+function scanGuidanceEpoch(
+	manager: ExtensionContext["sessionManager"],
+	identity: { readonly sessionId: string; readonly leaf: EntryLike | undefined },
+	previous: EpochState | undefined,
+	memoryByEpoch: ReadonlyMap<string, MemoryEpoch> | undefined,
+): Pick<EpochState, "anchorKey" | "byBudget" | "tools"> {
+	const reversed: EntryLike[] = [];
+	let anchor: EntryLike | undefined;
+	for (
+		let entry = identity.leaf;
+		entry !== undefined;
+		entry = parentEntry(manager, entry.parentId)
+	) {
+		if (previous !== undefined && previous.leaf === entry) {
+			const collected = collectGuidanceEntries(
+				reversed.reverse(),
+				previous.byBudget,
+				previous.tools,
+			);
+			return {
+				anchorKey: previous.anchorKey,
+				...withMemoryEpoch(collected, memoryByEpoch?.get(previous.anchorKey)),
+			};
+		}
+		if (startsFreshGuidanceEpoch(entry)) {
+			anchor = entry;
+			break;
+		}
+		reversed.push(entry);
+	}
+	const anchorKey =
+		anchor === undefined
+			? `${identity.sessionId}:root`
+			: `${identity.sessionId}:${anchor.id ?? "boundary"}`;
+	const collected = collectGuidanceEntries(reversed.reverse());
+	return {
+		anchorKey,
+		...withMemoryEpoch(collected, memoryByEpoch?.get(anchorKey)),
+	};
+}
+export function createWindowGuidance(pi: ExtensionAPI): WindowGuidance {
+	let state: EpochState | undefined;
+	let memoryByManager = new WeakMap<object, Map<string, MemoryEpoch>>();
+	const readEpoch = (ctx: ExtensionContext): EpochState => {
+		const manager = ctx.sessionManager;
+		const { sessionId, file, leaf } = sessionIdentityOf(manager);
+		const previous =
+			state?.manager === manager && state.sessionId === sessionId && state.file === file
+				? state
+				: undefined;
+		if (previous !== undefined && previous.leaf === leaf) {
+			return previous;
+		}
+		state = {
+			manager,
+			sessionId,
+			file,
+			leaf,
+			...scanGuidanceEpoch(
+				manager,
+				{ sessionId, leaf },
+				previous,
+				memoryByManager.get(manager),
+			),
+		};
+		return state;
+	};
+	return {
+		resolve(ctx, host) {
+			const epoch = readEpoch(ctx);
+			const key = budgetGuidanceKey(host);
+			return (
+				epoch.byBudget.get(key) ?? buildGuidance(host, epoch.tools ?? ALL_GUIDANCE_TOOLS)
+			);
+		},
+		deliver(ctx, host) {
+			const epoch = readEpoch(ctx);
+			const key = budgetGuidanceKey(host);
+			const existing = epoch.byBudget.get(key);
+			if (existing !== undefined) {
+				return existing;
+			}
+			const tools = epoch.tools ?? activeGuidanceTools(pi);
+			const text = buildGuidance(host, tools);
+			let byEpoch = memoryByManager.get(ctx.sessionManager);
+			if (byEpoch === undefined) {
+				byEpoch = new Map();
+				memoryByManager.set(ctx.sessionManager, byEpoch);
+			}
+			let memory = byEpoch.get(epoch.anchorKey);
+			if (memory === undefined) {
+				memory = { byBudget: new Map(), tools };
+				byEpoch.set(epoch.anchorKey, memory);
+			}
+			memory.byBudget.set(key, text);
+			memory.tools ??= tools;
+			state = undefined;
+			pi.appendEntry(WINDOW_GUIDANCE_TYPE, {
+				version: 1,
+				budgetKey: key,
+				text,
+				tools,
+			} satisfies WindowGuidanceRecord);
+			return text;
+		},
+		reset() {
+			state = undefined;
+			memoryByManager = new WeakMap();
+		},
+	};
+}
+export function registerGuidance(
+	pi: ExtensionAPI,
+	policy: SnapshotReader,
+	windowGuidance: WindowGuidance,
+): void {
 	let promptOptions: { readonly forceSystemPrompt?: string } | undefined;
 	pi.on("before_agent_start", (event) => {
 		promptOptions = event.systemPromptOptions;
@@ -12,7 +254,7 @@ export function registerGuidance(pi: ExtensionAPI, policy: SnapshotReader): void
 		promptOptions = undefined;
 	});
 	pi.on("context_with_system", (event, ctx) => {
-		const guidance = buildGuidance(policy(ctx));
+		const guidance = windowGuidance.deliver(ctx, policy(ctx));
 		const system =
 			event.messages.findLast(
 				(message) =>

package/src/note-provenance.ts

@@ -1,4 +1,4 @@
-import { existsSync } from "node:fs";
+import { statSync } from "node:fs";
 import { isAbsolute, join } from "node:path";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { isRecord, type EntryLike } from "./contracts.ts";
@@ -115,10 +115,22 @@ async function sourceScope(
 		source.file === undefined ? manager.getEntries() : await journalMetadata(source.file, true);
 	return legacySource(legacy.length > 0 ? legacy : manager.getEntries());
 }
+function hasReferencedTarget(
+	current: NoteScope,
+	path: string,
+	includeDirectories: boolean,
+): boolean {
+	const info = statSync(notePath(current, path), { throwIfNoEntry: false });
+	if (info === undefined) {
+		return false;
+	}
+	return info.isFile() || (includeDirectories && info.isDirectory());
+}
 export async function resolveReference(
 	scope: NoteScope,
 	path: string,
 	entries: readonly EntryLike[],
+	options: { readonly includeDirectories?: boolean | undefined } = {},
 ): Promise<NoteAddress | undefined> {
 	let source: NoteScope | null = scope;
 	const bindings = bindingsOf(entries);
@@ -130,7 +142,7 @@ export async function resolveReference(
 			throw new Error(`Cyclic note provenance at ${directory}.`);
 		}
 		visited.add(directory);
-		if (existsSync(notePath(current, path))) {
+		if (hasReferencedTarget(current, path, options.includeDirectories === true)) {
 			return addressIn(current, path);
 		}
 		// A manifest includes later adoptions; the journal includes later writes and deletions.

package/src/note-scopes.ts

@@ -113,6 +113,36 @@ export function noteRelative(path: string): string {
 	}
 	return normalized;
 }
+function ancestorsOf(path: string): string[] {
+	const ancestors: string[] = [];
+	let current = dirname(path);
+	while (true) {
+		ancestors.push(current);
+		const parent = dirname(current);
+		if (parent === current) {
+			return ancestors.toReversed();
+		}
+		current = parent;
+	}
+}
+export function scopeNoteRelative(scope: NoteScope, path: string): string {
+	if (
+		path !== "" &&
+		isAbsolute(path) &&
+		!path.includes("\0") &&
+		!path.split(/[/\\]/u).includes("..")
+	) {
+		const targetDirectory = canonicalPath(scopeDirectory(scope));
+		const resolved = resolve(path);
+		const matched = ancestorsOf(resolved).find(
+			(ancestor) => canonicalPath(ancestor) === targetDirectory,
+		);
+		if (matched !== undefined) {
+			return noteRelative(relative(matched, resolved));
+		}
+	}
+	return noteRelative(path);
+}
 /** Resolve existing ancestors too, so aliases to files not created yet have one owner. */
 export function canonicalPath(path: string): string {
 	const absolute = isAbsolute(path) ? path : `${process.cwd()}${sep}${path}`;

package/src/note-store.ts

@@ -23,6 +23,7 @@ import {
 	sameOwner,
 	sameScope,
 	scopeDirectory,
+	scopeNoteRelative,
 	type NoteAddress,
 	type NoteBinding,
 	type NoteScope,
@@ -133,16 +134,24 @@ export class SessionNotes {
 			`Unknown notes scope ${JSON.stringify(selector)}. Omit scope for this session's notes, or copy a scope selector from notes list/search.`,
 		);
 	}
-	async #reference(path: string, signal?: AbortSignal): Promise<NoteAddress | undefined> {
+	async #reference(
+		path: string,
+		options: {
+			readonly includeDirectories?: boolean | undefined;
+			readonly signal?: AbortSignal | undefined;
+		} = {},
+	): Promise<NoteAddress | undefined> {
 		if (this.binding.kind !== "fork" || this.binding.source === null) {
 			return;
 		}
 		const entries = [
 			...this.#manager.getEntries(),
 			...this.#source.entries,
-			...(await sourceEntries(this.#source.file, signal)),
+			...(await sourceEntries(this.#source.file, options.signal)),
 		];
-		return resolveReference(this.binding.source, path, entries);
+		return resolveReference(this.binding.source, path, entries, {
+			includeDirectories: options.includeDirectories,
+		});
 	}
 	async read(
 		path: string,
@@ -151,8 +160,8 @@ export class SessionNotes {
 			readonly signal?: AbortSignal | undefined;
 		} = {},
 	): Promise<NoteRead> {
-		const relative = noteRelative(path);
 		if (options.scope !== undefined) {
+			const relative = noteRelative(path);
 			const scope = await this.selectScope(options.scope);
 			return {
 				address: addressIn(scope, relative),
@@ -160,9 +169,13 @@ export class SessionNotes {
 				writable: sameScope(scope, this.binding),
 			};
 		}
+		const relative = scopeNoteRelative(this.binding, path);
 		const reference = this.owns(relative)
 			? undefined
-			: await this.#reference(relative, options.signal);
+			: await this.#reference(relative, {
+					includeDirectories: true,
+					signal: options.signal,
+				});
 		const address = reference ?? addressIn(this.binding, relative);
 		return { address, path: notePath(address, relative), writable: reference === undefined };
 	}

package/src/notes.ts

@@ -92,15 +92,20 @@ async function readNote(
 	access: NotesAccess,
 ): Promise<TextResult> {
 	const { pages } = access;
-	const relative = requireValue(params.path, "path", params.op);
-	const target = await session.read(relative, { scope: params.scope, signal: access.signal });
+	const requested = requireValue(params.path, "path", params.op);
+	const target = await session.read(requested, { scope: params.scope, signal: access.signal });
+	const relative = target.address.path;
 	const path = target.path;
 	const info = statSync(path, { throwIfNoEntry: false });
 	if (info === undefined) {
 		throw new Error(`No note at ${relative}. Use op "list" to see available notes.`);
 	}
 	if (info.isDirectory()) {
-		return listNotes(session, { ...params, scope: scopeDirectory(target.address) }, access);
+		return listNotes(
+			session,
+			{ ...params, path: relative, scope: scopeDirectory(target.address) },
+			access,
+		);
 	}
 	if (await isBinaryFile(path)) {
 		throw new Error(
@@ -283,6 +288,40 @@ function withoutEmptyScope(params: NotesParams): NotesParams {
 	const { scope, ...unscoped } = params;
 	return scope === "" ? unscoped : params;
 }
+const notesParameters = Type.Object({
+	op: Type.Union(
+		[
+			Type.Literal("list"),
+			Type.Literal("read"),
+			Type.Literal("write"),
+			Type.Literal("append"),
+			Type.Literal("search"),
+		],
+		{ description: "Operation to perform" },
+	),
+	path: Type.Optional(
+		Type.String({
+			description:
+				"Note or folder path relative to the notes directory (read also accepts a path in this session's notes directory)",
+		}),
+	),
+	scope: Type.Optional(
+		Type.String({
+			description:
+				"Absolute scope selector from list/search; only for read/list/search. Omit for current notes and project-wide discovery.",
+		}),
+	),
+	content: Type.Optional(
+		Type.String({ description: "Full file content (write) or text to add (append)" }),
+	),
+	query: Type.Optional(Type.String({ description: "Substring to find in notes (search)" })),
+	offset: Type.Optional(
+		Type.Integer({
+			description: "Character offset for list/read/search (default 0)",
+			minimum: 0,
+		}),
+	),
+});
 export function registerNotes(
 	pi: ExtensionAPI,
 	policy: (ctx: ExtensionContext) => PolicyContext,
@@ -297,39 +336,7 @@ export function registerNotes(
 		description:
 			"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(
-				[
-					Type.Literal("list"),
-					Type.Literal("read"),
-					Type.Literal("write"),
-					Type.Literal("append"),
-					Type.Literal("search"),
-				],
-				{ description: "Operation to perform" },
-			),
-			path: Type.Optional(
-				Type.String({ description: "Note or folder path relative to the notes directory" }),
-			),
-			scope: Type.Optional(
-				Type.String({
-					description:
-						"Absolute scope selector from list/search; only for read/list/search. Omit for current notes and project-wide discovery.",
-				}),
-			),
-			content: Type.Optional(
-				Type.String({ description: "Full file content (write) or text to add (append)" }),
-			),
-			query: Type.Optional(
-				Type.String({ description: "Substring to find in notes (search)" }),
-			),
-			offset: Type.Optional(
-				Type.Integer({
-					description: "Character offset for list/read/search (default 0)",
-					minimum: 0,
-				}),
-			),
-		}),
+		parameters: notesParameters,
 		async execute(...[_id, received, signal, , ctx]) {
 			const params = withoutEmptyScope(received);
 			// Migrate newly returned legacy package notes without changing this session’s binding.

package/src/recovery-note-touches.ts

@@ -244,11 +244,24 @@ function notesCallKind(args: Readonly<Record<string, unknown>>): ContentTouchKin
 	return args.op === "read" ? "read" : undefined;
 }
 
+function preferredNotePath(
+	callTarget: NoteTarget | undefined,
+	resTarget: NoteTarget | undefined,
+): string | undefined {
+	if (callTarget === undefined) {
+		return resTarget?.notePath;
+	}
+	if (callTarget.absPath !== undefined && resTarget !== undefined) {
+		return resTarget.notePath;
+	}
+	return callTarget.notePath;
+}
+
 function mergeNoteTargets(
 	callTarget: NoteTarget | undefined,
 	resTarget: NoteTarget | undefined,
 ): NoteTarget | undefined {
-	const notePath = callTarget?.notePath ?? resTarget?.notePath;
+	const notePath = preferredNotePath(callTarget, resTarget);
 	return notePath === undefined
 		? undefined
 		: { notePath, absPath: resTarget?.absPath ?? callTarget?.absPath };

package/src/rollover.ts

@@ -17,7 +17,7 @@ import {
 	type SnapshotReader,
 } from "./contracts.ts";
 import { registerContextTools } from "./context-tools.ts";
-import { registerGuidance } from "./guidance.ts";
+import { registerGuidance, type WindowGuidance } from "./guidance.ts";
 import { safeJsonStringify } from "./message-text.ts";
 import {
 	hostMakesProviderSummary,
@@ -31,6 +31,7 @@ import type { NotesRecovery } from "./note-evidence.ts";
 type RolloverResources = {
 	readonly resetPages: () => void;
 	readonly notes: (ctx: ExtensionContext) => NotesRecovery | undefined;
+	readonly guidance: WindowGuidance;
 };
 import {
 	countRetainedMessages,
@@ -428,12 +429,14 @@ export function registerRollover(
 	pi.on("session_start", () => {
 		resetTurn();
 		reminders.reset();
+		resources.guidance.reset();
 	});
 	pi.on("session_tree", () => {
 		reminders.reset();
+		resources.guidance.reset();
 	});
 	registerReminderFilter(pi, policy, reminders);
-	registerGuidance(pi, policy);
+	registerGuidance(pi, policy, resources.guidance);
 	registerAutomaticRollover(pi, policy, activeToolTokens, resources.notes);
 	pi.on("turn_end", (event, ctx) => {
 		const summary = resetRequests.take(event.toolResults);