@howaboua/pi-notes-compaction 0.0.3 → 0.0.5

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @howaboua/pi-notes-compaction
 
+## 0.0.5
+
+- We've been informed that Astra and Sol currently retain their prompt caches for around an hour. If you use notes-managed idle rollover, consider increasing it from 25 to 55 minutes. Cache retention can vary. YMMV. We'll keep monitoring. Please share your cache-retention and long-context quota observations in [the feedback thread](https://github.com/IgorWarzocha/howaboua-pi-stuff/issues/508).
+
+  Added configurable task-boundary reminders and a clearer settings layout.
+
+  - Added optional reminders at preset or custom token counts when context capacity exceeds 272k, showing the remaining percentage.
+  - Status text and keyboard hints now wrap to fit narrow terminals.
+  - Notes help now lists required arguments. Writes accept `content` when `text` is omitted.
+  - Fixed fresh worker startup with Notes enabled.
+
+## 0.0.4
+
+- Fixed note queries and manual context rollover with Codex Conversion.
+
+  - Restored negative line ranges, default limits, result ordering, metadata and complete read and search content. Help now shows concrete call syntax, and invalid arguments are reported before execution.
+  - `/compact` now honours the Normal compaction setting. With it off, Notes Compaction reuses fresh saved notes or requests a checkpoint, then opens a new context window without starting a continuation turn.
+
 ## 0.0.3
 
 - Fixed shared agent startup after package updates when the startup changelog is present.

package/PCC-INTEGRATION.md

@@ -35,7 +35,7 @@ Required boundaries in the current source:
 
 - `context-management/tools.ts` and `extension/tools.ts`: replace the four tools through the registration callback. Active-tool and schema rewrites must preserve delegated definitions. Do not reinstall legacy routers on model changes or settings changes.
 - `extension/session-lifecycle.ts` and `extension/turn-lifecycle.ts`: skip legacy notes/window initialization, input holding, checkpoint admission, note freshness, reminders, settlement records and continuation scheduling. Leave PCC's prompt preparation, runtime synchronization, Notebook status, voice, quota and provider lifecycle active.
-- `extension/compaction-lifecycle.ts`: skip only legacy `contextWindows.prepareCompaction` and notes checkpoint overrides. When this extension allows normal compaction, run the unchanged installed PCC normal-compaction path. Overflow stays in the same window. Notebook checkpointing, native compaction, replay, transport reset and presentation remain PCC-owned.
+- `extension/compaction-lifecycle.ts`: consult `owner.allowsCompaction(reason)` before any compaction work. When false, return without work so the owner's hook can cancel and handle notes-only rollover, regardless of extension order. Skip legacy `contextWindows.prepareCompaction` and notes checkpoint overrides. When this extension allows normal compaction, run the unchanged installed PCC normal-compaction path. Overflow stays in the same window. Notebook checkpointing, native compaction, replay, transport reset and presentation remain PCC-owned.
 - `context-management/window-manager.ts`, `window-request.ts` and native replay serializers: use `owner.identity(ctx)` and `owner.projectBranch(entries)` for the active window and retirement boundary. Preserve PCC request metadata and zero-based generation semantics. Do not recreate remote history-ingest requirements for local notes.
 - PCC message preparation and `adapter/developer-messages.ts`: preserve `notes-compaction:window:v1` and `notes-compaction:checkpoint:v1` custom messages on every model. Compatible Responses routes may promote them to developer messages. Ordinary Pi conversion must retain them on other routes. Use `owner.projectMessages(messages)` before native replay/prewarm, without overwriting another extension's preparation.
 - Settings UI: show notes continuity as externally managed. Preserve old PCC values for sessions without the external extension. Do not add another compaction setting to this extension.

package/README.md

@@ -20,7 +20,9 @@ The agent keeps the familiar `notes`, `history`, `new_context` and `get_context_
 
 By default, `new_context` starts a fresh window without generating a summary. The agent receives recent note paths, and Pi's saved history remains available for lookup.
 
-Reminders arrive at 85% and 90% context use. `/compact` requests a notes checkpoint and opens a new window only after a completed run with fresh saved notes. Abort, errors and failed writes retain the old context. Overflow recovery still uses Pi's normal compaction.
+Reminders arrive at 85% and 90% context use. With normal compaction off, `/compact` opens a fresh window immediately if the latest completed turn saved fresh notes. Otherwise it requests a checkpoint first. The new window waits for your next prompt; it does not start a continuation turn. Abort, errors and failed writes retain the old context. Overflow recovery still uses Pi's normal compaction.
+
+Pi rejects `/compact` when there is too little history to prepare compaction, before extensions run. In that case, the agent can still use `new_context`.
 
 Idle rollover is off by default. Choose 5, 15, 25 or 55 minutes in `/notes`. After that interval, the next input waits for rollover only if the latest completed turn saved fresh notes. Otherwise it proceeds in the current window without requesting a checkpoint. These intervals are user preferences, not provider cache-expiry guarantees. Held input retains its original text, attachments and SDK options. A failed rollover keeps input pending. Submit another prompt to retry, or reload to cancel it.
 
@@ -28,7 +30,7 @@ Idle rollover is off by default. Choose 5, 15, 25 or 55 minutes in `/notes`. Aft
 
 `/notes` opens the settings panel in interactive Pi. It shows continuity status, storage counts and remote capabilities. Changes save immediately.
 
-- **Normal compaction** includes the installed Pi or PCC compaction flow on `new_context`. Off keeps notes-only rollover, the default.
+- **Normal compaction** uses the installed Pi or PCC compaction flow for `/compact` and `new_context`. Off keeps notes-only rollover, the default.
 - **Idle rollover** selects the interval or disables it.
 - **Prune missing sessions** removes records for missing session files after confirmation. Unknown paths, permission errors and the active session are retained.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@howaboua/pi-notes-compaction",
-	"version": "0.0.3",
+	"version": "0.0.5",
 	"publishConfig": {
 		"access": "public"
 	},

package/src/bridge.ts

@@ -1,8 +1,10 @@
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import type {
 	AgentToolResult,
+	CustomMessageEntryDraft,
 	ExtensionAPI,
 	ExtensionContext,
+	SessionBeforeCompactEvent,
 	SessionEntry,
 	ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
@@ -68,6 +70,8 @@ export interface NotesOwner {
 	identity(ctx: ExtensionContext): WindowIdentity | undefined;
 	projectMessages(messages: readonly AgentMessage[]): AgentMessage[];
 	projectBranch(entries: readonly SessionEntry[]): SessionEntry[];
+	/** Consult before compaction work; the owner's hook performs notes-only rollover. */
+	allowsCompaction?(reason: SessionBeforeCompactEvent["reason"]): boolean;
 	canBind?(ctx: ExtensionContext): boolean;
 	snapshotNotes?(
 		entries: readonly SessionEntry[],
@@ -83,6 +87,8 @@ export interface NotesOwner {
 
 export interface NotesBridge {
 	protocol: 1;
+	/** Preserve the owner's chronological entry while enabling developer-role delivery. */
+	prepareReminder?(entry: CustomMessageEntryDraft): CustomMessageEntryDraft;
 	/** Synchronous atomic handoff. No legacy registrations or lifecycle owners remain active. */
 	claim(owner: NotesOwner):
 		| {

package/src/index.ts

@@ -43,6 +43,7 @@ export default function notesCompaction(pi: ExtensionAPI): void {
 			lifecycle.windows.current ? { ...lifecycle.windows.current } : undefined,
 		projectMessages: (messages) => lifecycle.windows.projectMessages(messages),
 		projectBranch: (entries) => lifecycle.windows.projectBranch(entries),
+		allowsCompaction: (reason) => lifecycle.allowsCompaction(reason),
 		canBind: (ctx) =>
 			lifecycle.active &&
 			ctx.isIdle() &&
@@ -53,6 +54,15 @@ export default function notesCompaction(pi: ExtensionAPI): void {
 					entry.customType === "@howaboua/pi-stuff/changelog"
 				)
 					return true;
+				// PCC links the fresh worker before binding its shared notes family.
+				if (
+					entry.type === "custom" &&
+					entry.customType === "codex-agent-relationship"
+				)
+					return (
+						(entry.data as { threadId?: unknown } | undefined)?.threadId ===
+						ctx.sessionManager.getSessionId()
+					);
 				// Herdr activation persists its empty registry before first task delivery.
 				if (
 					entry.type === "custom" &&
@@ -167,10 +177,29 @@ export default function notesCompaction(pi: ExtensionAPI): void {
 			);
 		}
 	});
-	pi.on("turn_end", (_event, ctx) => {
-		if (!lifecycle.active || lifecycle.fresh(ctx, lifecycle.runId)) return;
-		const reminder = lifecycle.windows.reminder(ctx);
-		return reminder ? { entries: [reminder] } : undefined;
+	pi.on("turn_end", (event, ctx) => {
+		if (!lifecycle.active) return;
+		const reminder = lifecycle.windows.reminder(
+			ctx,
+			event.message.role === "assistant" &&
+				!ctx.signal?.aborted &&
+				!["error", "length", "aborted"].includes(event.message.stopReason) &&
+				event.toolResults.length > 0 &&
+				pi.getActiveTools().includes("new_context")
+				? lifecycle.taskBoundaryReminder
+				: 0,
+			!lifecycle.fresh(ctx, lifecycle.runId),
+		);
+		return reminder
+			? {
+					entries: [
+						...event.entries,
+						windowDetails(reminder)?.kind === "task-boundary"
+							? (lifecycle.bridge?.prepareReminder?.(reminder) ?? reminder)
+							: reminder,
+					],
+				}
+			: undefined;
 	});
 	pi.on("context", (event, ctx) => {
 		if (!lifecycle.active) return;
@@ -239,8 +268,10 @@ export default function notesCompaction(pi: ExtensionAPI): void {
 					settings: () => ({
 						normalCompaction: lifecycle.normalCompaction,
 						idleMinutes: lifecycle.idleMinutes,
+						taskBoundaryReminder: lifecycle.taskBoundaryReminder,
 					}),
 					save,
+					settingsPath,
 					prune,
 					status: () => {
 						const counts = store.status();

package/src/lifecycle.ts

@@ -50,6 +50,7 @@ export class NotesLifecycle {
 	active = false;
 	normalCompaction = false;
 	idleMinutes: IdleMinutes = 0;
+	taskBoundaryReminder = 0;
 	bridge: NotesBridge | undefined;
 	runId = "";
 	private checkpoint: Checkpoint | undefined;
@@ -357,11 +358,7 @@ export class NotesLifecycle {
 		event: SessionBeforeCompactEvent,
 		ctx: ExtensionContext,
 	): { cancel: true } | undefined {
-		if (
-			this.normalCompaction ||
-			this.rollover?.phase === "compacting" ||
-			event.reason === "overflow"
-		) {
+		if (this.allowsCompaction(event.reason)) {
 			// PCC owns preparation when bridged, including native checkpoint routes.
 			if (this.bridge) return;
 			try {
@@ -435,6 +432,13 @@ export class NotesLifecycle {
 			};
 		return { cancel: true };
 	}
+	allowsCompaction(reason: SessionBeforeCompactEvent["reason"]): boolean {
+		return (
+			this.normalCompaction ||
+			this.rollover?.phase === "compacting" ||
+			reason === "overflow"
+		);
+	}
 	async compactFailed(
 		event: SessionCompactFailedEvent,
 		ctx: ExtensionContext,
@@ -450,7 +454,7 @@ export class NotesLifecycle {
 		)
 			return;
 		if (!pending.instructions?.trim() && this.fresh(ctx))
-			await this.roll(ctx, true);
+			await this.roll(ctx, false);
 		else this.startCheckpoint(ctx, pending.instructions);
 	}
 	async settled(
@@ -517,7 +521,7 @@ export class NotesLifecycle {
 				);
 				return;
 			}
-			await this.roll(ctx, true);
+			await this.roll(ctx, false);
 			return;
 		}
 		if (this.held?.phase === "draining") {

package/src/notes.ts

@@ -216,25 +216,34 @@ export function exportNotesSnapshot(
 }
 
 function canonicalPath(path: unknown, agent: string, required = true): string {
-	if (typeof path !== "string" || !path.trim()) {
-		if (required) throw new Error("Supply a note path");
+	if (path === undefined || path === null || path === "") {
+		if (required) throw new Error("Note file path is required");
 		return "";
 	}
+	if (typeof path !== "string")
+		throw new Error(
+			required ? "Note file path is required" : "Note prefix must be a string",
+		);
 	const root = `${agent}/notes`;
 	let value = path;
-	if (value === root) value = "";
-	else if (value.startsWith(`${root}/`)) value = value.slice(root.length + 1);
+	if (value === root) {
+		if (required)
+			throw new Error("Absolute note paths must use <agent>/notes/<path>");
+		value = "";
+	} else if (value.startsWith(`${root}/`)) value = value.slice(root.length + 1);
 	else if (value.startsWith("/"))
 		throw new Error(
 			"That agent's notes are not available here. Use a relative path for this agent.",
 		);
 	if (
 		(required && !value) ||
-		value.split("/").some((part) => part === ".." || part === ".") ||
-		/[\0\r\n]/.test(value)
+		(value !== "" &&
+			value.split("/").some((part) => !part || part === ".." || part === "."))
 	)
 		throw new Error(
-			"Use a virtual note path without dot segments or control characters",
+			required
+				? "Note paths cannot contain empty, . or .. components"
+				: "Note prefixes cannot contain empty, . or .. components",
 		);
 	return value;
 }
@@ -244,11 +253,8 @@ export function normalizeNoteParams(
 	agent: string,
 ): Record<string, unknown> {
 	const result = { ...params };
-	const needsPath = ["read_file", "write_file", "append_to_file"].includes(
-		String(params["action"]),
-	);
 	for (const field of ["path", "prefix", "path_prefix"])
-		if (field in params || field !== "path" || needsPath)
+		if (field in params)
 			result[field] = canonicalPath(params[field], agent, field === "path");
 	return result;
 }
@@ -285,12 +291,13 @@ export function useNotes(
 	if (action === "write_file" || action === "append_to_file") {
 		const path = params["path"] as string;
 		const text = params["text"];
-		if (typeof text !== "string") throw new Error("Supply note text");
+		if (typeof text !== "string")
+			throw new Error(`notes ${action} requires text`);
 		const previous = notes.get(path);
 		const next =
 			action === "append_to_file" ? (previous?.text ?? "") + text : text;
 		if (Buffer.byteLength(next) > 1_000_000)
-			throw new Error("Note exceeds 1 MB. Split it into separate paths.");
+			throw new Error("Note file exceeds the 1,000,000-byte limit");
 		const now = Date.now();
 		// Append never pretends to decode a remote base. The remote fragment remains separate.
 		const mode =
@@ -324,113 +331,101 @@ export function useNotes(
 			);
 		}
 		return {
-			path: `${root}${path}`,
-			chars: next.length,
-			operation:
-				mode === "append" ? "local_append_overlay" : "local_replacement",
+			source: "pi-session",
+			file: noteMetadata(revision, root),
 		};
 	}
+
 	if (action === "read_file") {
 		const path = params["path"] as string;
 		const note = notes.get(path);
-		if (!note) return { path: `${root}${path}`, file: null };
+		if (!note) return { source: "pi-session", file: null };
 		const lines = note.text.split("\n");
-		const start = integer(params["start_line"], 1, lines.length + 1);
-		const stop = integer(params["stop_line"], lines.length, lines.length);
-		let text = "";
-		let next = start;
-		while (next <= stop) {
-			const line = lines[next - 1] ?? "";
-			if (text.length + line.length > 32_000) {
-				if (!text)
-					throw new Error(
-						"This note line exceeds 32000 characters. Rewrite it as shorter lines to read it.",
-					);
-				break;
-			}
-			text += `${next > start ? "\n" : ""}${line}`;
-			next++;
-		}
+		const start = lineIndex(params["start_line"], lines.length, 0);
+		const stop = lineIndex(params["stop_line"], lines.length, lines.length - 1);
 		return {
-			path: `${root}${path}`,
-			text,
-			start_line: start,
-			total_lines: lines.length,
-			...(next <= stop ? { next_start_line: next } : {}),
-			operation:
-				note.mode === "replace" ? "local_replacement" : "local_append_overlay",
+			source: "pi-session",
+			file: {
+				...noteMetadata(note, root),
+				content: start <= stop ? lines.slice(start, stop + 1).join("\n") : "",
+				start_line: start + 1,
+				stop_line: Math.max(start, stop) + 1,
+				total_lines: lines.length,
+			},
 		};
 	}
 	if (action === "list_files_by_prefix") {
-		let files = [...notes.values()].filter((note) =>
-			note.path.startsWith(String(params["prefix"] ?? "")),
-		);
 		const by = params["file_order_by"];
-		files.sort((a, b) =>
-			by === "created_at"
-				? a.createdAt - b.createdAt
-				: by === "updated_at"
-					? a.updatedAt - b.updatedAt
-					: a.path.localeCompare(b.path),
-		);
-		if (params["file_order"] === "descending") files.reverse();
-		const maximum = integer(params["max_results"], 100, 100);
-		return {
-			files: files.slice(0, maximum).map((note) => ({
-				path: `${root}${note.path}`,
-				chars: note.text.length,
-				updated_at: note.updatedAt,
-			})),
-			truncated: files.length > maximum,
-		};
+		const direction = params["file_order"] === "descending" ? -1 : 1;
+		const files = [...notes.values()]
+			.filter((note) => note.path.startsWith(String(params["prefix"] ?? "")))
+			.sort(
+				(a, b) =>
+					(by === "created_at"
+						? a.createdAt - b.createdAt
+						: by === "updated_at"
+							? a.updatedAt - b.updatedAt
+							: a.path.localeCompare(b.path)) * direction,
+			)
+			.slice(0, integer(params["max_results"], 20, 100))
+			.map((note) => noteMetadata(note, root));
+		return { source: "pi-session", files };
 	}
-	if (
-		action !== "search_contents" ||
-		typeof params["query"] !== "string" ||
-		!params["query"]
-	)
-		throw new Error("Supply a nonempty search query");
+	if (action !== "search_contents")
+		throw new Error("notes requires a supported action");
+	const query = params["query"];
+	if (typeof query !== "string" || !query)
+		throw new Error("notes search_contents requires query");
 	const files = [...notes.values()].filter((note) =>
 		note.path.startsWith(String(params["path_prefix"] ?? "")),
 	);
-	if (params["recent_file_first"] === true)
-		files.sort((a, b) => b.updatedAt - a.updatedAt);
-	const found: {
-		path: string;
-		matches: { line: number; text: string }[];
-		truncated: boolean;
-	}[] = [];
-	let chars = 0;
-	let truncated = false;
+	files.sort(
+		params["recent_file_first"] === true
+			? (a, b) => b.createdAt - a.createdAt
+			: (a, b) => a.path.localeCompare(b.path),
+	);
+	const found: Record<string, unknown>[] = [];
 	for (const note of files) {
-		const all = note.text
+		const matches = note.text
 			.split("\n")
-			.flatMap((line, i) =>
-				line.includes(params["query"] as string)
-					? [{ line: i + 1, text: line.slice(0, 1000) }]
-					: [],
-			);
-		if (!all.length) continue;
-		const matches = all.slice(
-			0,
-			integer(params["max_matches_per_file"], 10, 100),
-		);
-		const size = JSON.stringify(matches).length;
-		if (
-			found.length >= integer(params["max_files"], 20, 100) ||
-			chars + size > 32_000
-		) {
-			truncated = true;
-			break;
-		}
+			.map((line, index) => ({ line_number: index + 1, line }))
+			.filter(({ line }) => line.includes(query))
+			.slice(0, integer(params["max_matches_per_file"], 20, 100));
+		if (!matches.length) continue;
 		found.push({
 			path: `${root}${note.path}`,
 			matches,
-			truncated: matches.length < all.length,
+			operation:
+				note.mode === "replace" ? "local_replacement" : "local_append_overlay",
 		});
-		chars += size;
+		if (found.length >= integer(params["max_files"], 20, 100)) break;
 	}
-	return { files: found, truncated };
+	return { source: "pi-session", files: found };
+}
+
+function noteMetadata(
+	note: NoteRevision,
+	root: string,
+): Record<string, unknown> {
+	return {
+		operation:
+			note.mode === "replace" ? "local_replacement" : "local_append_overlay",
+		path: `${root}${note.path}`,
+		bytes: Buffer.byteLength(note.text, "utf8"),
+		created_at: new Date(note.createdAt).toISOString(),
+		updated_at: new Date(note.updatedAt).toISOString(),
+	};
+}
+
+function lineIndex(
+	value: unknown,
+	lineCount: number,
+	fallback: number,
+): number {
+	if (typeof value !== "number" || !Number.isInteger(value) || value === 0)
+		return fallback;
+	const index = value > 0 ? value - 1 : lineCount + value;
+	return Math.max(0, Math.min(index, Math.max(0, lineCount - 1)));
 }
 
 function integer(value: unknown, fallback: number, max: number): number {

package/src/settings-screen.ts

@@ -2,13 +2,19 @@ import {
 	type ExtensionContext,
 	getSettingsListTheme,
 } from "@earendil-works/pi-coding-agent";
-import { SettingsList, truncateToWidth } from "@earendil-works/pi-tui";
+import {
+	SettingsList,
+	truncateToWidth,
+	wrapTextWithAnsi,
+} from "@earendil-works/pi-tui";
 import { IDLE_MINUTES, type NotesSettings } from "./settings.js";
+import { TASK_BOUNDARY_PRESETS, taskBoundaryLabel } from "./task-boundary.js";
 
 export async function openNotesSettings(
 	ctx: ExtensionContext,
 	options: {
 		settings: () => NotesSettings;
+		settingsPath: string;
 		save: (settings: NotesSettings) => void;
 		status: () => string[];
 		prune: () => Promise<void>;
@@ -27,10 +33,21 @@ export async function openNotesSettings(
 							id: "compact",
 							label: "Normal compaction",
 							description:
-								"Include the installed Pi/PCC compaction flow on new_context. Off keeps notes-only rollover.",
+								"Use Pi/PCC compaction for /compact and new_context. Off uses notes-only rollover; /compact then waits for your next prompt.",
 							currentValue: settings.normalCompaction ? "on" : "off",
 							values: ["off", "on"],
 						},
+						{
+							id: "taskBoundaryReminder",
+							label: "Task-boundary reminder",
+							description:
+								"Suggest a separate-task rollover after this many used tokens, only with active capacity above 272k. Custom: edit taskBoundaryReminder in the notes settings JSON (whole tokens); 0 is off.",
+							currentValue: taskBoundaryLabel(settings.taskBoundaryReminder),
+							values: [
+								...TASK_BOUNDARY_PRESETS.map(taskBoundaryLabel),
+								"custom (edit JSON)",
+							],
+						},
 						{
 							id: "idle",
 							label: "Idle rollover",
@@ -56,9 +73,31 @@ export async function openNotesSettings(
 							return;
 						}
 						const current = options.settings();
+						if (
+							id === "taskBoundaryReminder" &&
+							value === "custom (edit JSON)"
+						) {
+							ctx.ui.notify(
+								`Set taskBoundaryReminder to a positive whole token count in ${options.settingsPath}, then reload Pi. 0 is off.`,
+								"info",
+							);
+							list.updateValue(
+								id,
+								taskBoundaryLabel(current.taskBoundaryReminder),
+							);
+							return;
+						}
 						try {
 							if (id === "compact")
 								options.save({ ...current, normalCompaction: value === "on" });
+							else if (id === "taskBoundaryReminder")
+								options.save({
+									...current,
+									taskBoundaryReminder:
+										TASK_BOUNDARY_PRESETS.find(
+											(tokens) => taskBoundaryLabel(tokens) === value,
+										) ?? current.taskBoundaryReminder,
+								});
 							else {
 								const idleMinutes = IDLE_MINUTES.find(
 									(minutes) => idleValue(minutes) === value,
@@ -69,11 +108,13 @@ export async function openNotesSettings(
 						} catch (error) {
 							list.updateValue(
 								id,
-								id === "compact"
-									? current.normalCompaction
-										? "on"
-										: "off"
-									: idleValue(current.idleMinutes),
+								id === "taskBoundaryReminder"
+									? taskBoundaryLabel(current.taskBoundaryReminder)
+									: id === "compact"
+										? current.normalCompaction
+											? "on"
+											: "off"
+										: idleValue(current.idleMinutes),
 							);
 							ctx.ui.notify(
 								`Could not save notes settings: ${String(error)}`,
@@ -86,20 +127,36 @@ export async function openNotesSettings(
 					{ enableSearch: false },
 				);
 				return {
-					render: (width) =>
-						[
-							theme.fg("accent", "Notes & context"),
-							...status.map((line) => theme.fg("dim", line)),
+					render: (width) => {
+						const wrap = (text: string) =>
+							wrapTextWithAnsi(text, Math.max(1, width - 2)).map(
+								(line) => `  ${line}`,
+							);
+						const rule = theme.fg("accent", "─".repeat(Math.max(0, width)));
+						return [
+							rule,
+							`  ${theme.bold("Notes & context")}`,
+							"",
+							...status.flatMap((line) =>
+								wrap(line).map((part) => theme.fg("dim", part)),
+							),
 							"",
-							...list.render(width),
+							...list.render(width).slice(0, -2),
 							"",
-							theme.fg(
-								"dim",
-								"↑↓ navigate · Enter/Space change · Esc close · saved immediately",
+							...wrap("↑/↓ select · Enter/Space change · Esc close").map(
+								(line) => theme.fg("dim", line),
 							),
-						].map((line) => truncateToWidth(line, width)),
+							...wrap("Settings saved immediately").map((line) =>
+								theme.fg("dim", line),
+							),
+							rule,
+						].map((line) => truncateToWidth(line, width, ""));
+					},
 					invalidate: () => list.invalidate(),
-					handleInput: (data) => list.handleInput(data),
+					handleInput: (data) => {
+						list.handleInput(data);
+						tui.requestRender();
+					},
 				};
 			},
 		);

package/src/settings.ts

@@ -6,6 +6,7 @@ export type IdleMinutes = (typeof IDLE_MINUTES)[number];
 export interface NotesSettings {
 	normalCompaction: boolean;
 	idleMinutes: IdleMinutes;
+	taskBoundaryReminder: number;
 }
 
 export function readSettings(path: string): NotesSettings {
@@ -14,7 +15,11 @@ export function readSettings(path: string): NotesSettings {
 		source = readFileSync(path, "utf8");
 	} catch (error) {
 		if ((error as NodeJS.ErrnoException).code === "ENOENT")
-			return { normalCompaction: false, idleMinutes: 0 };
+			return {
+				normalCompaction: false,
+				idleMinutes: 0,
+				taskBoundaryReminder: 0,
+			};
 		throw error;
 	}
 	const settings: unknown = JSON.parse(source);
@@ -28,6 +33,16 @@ export function readSettings(path: string): NotesSettings {
 			"Invalid notes settings. Save a setting in /notes, then reload Pi.",
 		);
 	const idleMinutes = "idleMinutes" in settings ? settings.idleMinutes : 0;
+	const taskBoundaryReminder =
+		"taskBoundaryReminder" in settings ? settings.taskBoundaryReminder : 0;
+	if (
+		typeof taskBoundaryReminder !== "number" ||
+		!Number.isSafeInteger(taskBoundaryReminder) ||
+		taskBoundaryReminder < 0
+	)
+		throw new Error(
+			"Invalid task-boundary reminder setting. Save a setting in /notes, then reload Pi.",
+		);
 	if (!IDLE_MINUTES.some((value) => value === idleMinutes))
 		throw new Error(
 			"Invalid idle rollover interval. Choose off, 5, 15, 25 or 55 minutes.",
@@ -35,6 +50,7 @@ export function readSettings(path: string): NotesSettings {
 	return {
 		normalCompaction: settings.normalCompaction,
 		idleMinutes: idleMinutes as IdleMinutes,
+		taskBoundaryReminder,
 	};
 }
 

package/src/task-boundary.ts

@@ -0,0 +1,32 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export function renderTaskBoundaryReminder(remainingPercent: number): string {
+	return `<context_window_reminder>\nThis window is approaching the recommended token budget. You still have ${remainingPercent}% of your context window remaining, so there is no need to start a new window immediately. If you are working through a sequence of tasks toward a larger goal, finish the current task, save a checkpoint, and start a new window before continuing with the next task. Otherwise, continue here.\n</context_window_reminder>`;
+}
+
+export const TASK_BOUNDARY_PRESETS = [
+	0, 250_000, 300_000, 400_000, 450_000,
+] as const;
+export function taskBoundaryLabel(tokens: number): string {
+	return tokens === 0
+		? "off"
+		: TASK_BOUNDARY_PRESETS.some((value) => value === tokens)
+			? `${tokens / 1000}k`
+			: "custom (edit JSON)";
+}
+export function taskBoundaryEligible(
+	ctx: ExtensionContext,
+	threshold: number,
+	tokens = ctx.getContextUsage()?.tokens,
+): boolean {
+	const capacity =
+		ctx.getContextUsage()?.contextWindow ?? ctx.model?.contextWindow ?? 0;
+	return (
+		threshold > 0 &&
+		Number.isFinite(capacity) &&
+		capacity > 272_000 &&
+		typeof tokens === "number" &&
+		Number.isFinite(tokens) &&
+		tokens >= threshold
+	);
+}

package/src/tools.ts

@@ -6,6 +6,7 @@ import type {
 	ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
+import { Check } from "typebox/value";
 import type {
 	CachedResponse,
 	LookupQuery,
@@ -40,20 +41,23 @@ const HISTORY_ACTIONS = [
 	"read_item",
 	"search_contents",
 ] as const;
-export const NOTES_USAGE = "await tools.notes() // help";
+export const NOTES_USAGE =
+	"await tools.notes({ action, ...args }) // no args: help; actions(required args): list_files_by_prefix(); read_file(path); search_contents(query); append_to_file(path,text); write_file(path,text)";
 export const HISTORY_USAGE = "await tools.history() // help";
 const STRING = Type.Optional(Type.String());
 const INTEGER = Type.Optional(Type.Integer({ minimum: 1 }));
+const NULLABLE_STRING = Type.Optional(Type.Union([Type.String(), Type.Null()]));
+const LINE = Type.Optional(Type.Union([Type.Integer(), Type.Null()]));
 const NOTES_SCHEMA = Type.Object(
 	{
 		action: Type.Optional(StringEnum(NOTES_ACTIONS)),
 		path: STRING,
 		text: STRING,
-		prefix: STRING,
+		prefix: NULLABLE_STRING,
 		query: STRING,
-		path_prefix: STRING,
-		start_line: INTEGER,
-		stop_line: INTEGER,
+		path_prefix: NULLABLE_STRING,
+		start_line: LINE,
+		stop_line: LINE,
 		max_results: INTEGER,
 		max_files: INTEGER,
 		max_matches_per_file: INTEGER,
@@ -146,7 +150,32 @@ function relevant(
 	const key =
 		action === "search_contents" ? `search_${namespace}` : String(action);
 	const fields = FIELDS[key];
-	if (!fields) throw new Error("Unknown action");
+	if (!fields)
+		throw new Error(
+			namespace === "notes"
+				? "notes requires a supported action"
+				: "Unknown action",
+		);
+	if (namespace === "notes") {
+		for (const field of Object.keys(params))
+			if (field !== "action" && !fields.includes(field))
+				throw new Error(`notes ${String(action)} does not accept ${field}`);
+		if (
+			["read_file", "write_file", "append_to_file"].includes(String(action)) &&
+			(typeof params["path"] !== "string" || !params["path"])
+		)
+			throw new Error(`notes ${String(action)} requires path`);
+		if (
+			action === "search_contents" &&
+			(typeof params["query"] !== "string" || !params["query"])
+		)
+			throw new Error("notes search_contents requires query");
+		if (
+			["write_file", "append_to_file"].includes(String(action)) &&
+			typeof params["text"] !== "string"
+		)
+			throw new Error(`notes ${String(action)} requires text`);
+	}
 	return Object.fromEntries(
 		Object.entries(params).filter(
 			([key]) => key === "action" || fields.includes(key),
@@ -192,6 +221,16 @@ function discovery(
 							).join(" "),
 				]),
 			),
+			...(namespace === "notes"
+				? {
+						usage:
+							'await tools.notes({ action: "read_file", path: "checkpoint" })',
+						ranges:
+							"start_line/stop_line inclusive, 1-based; negative counts from end; 0/null/omitted uses first/last line; out-of-range clamps; reversed range returns empty content",
+						defaults:
+							"list max_results 20; search max_files/max_matches_per_file 20; limits clamp to 1..100; list name ascending; search name ascending, recent_file_first sorts created_at descending",
+					}
+				: {}),
 		});
 	}
 	return undefined;
@@ -484,15 +523,37 @@ export function createTools(
 			prepareArguments(args) {
 				if (args === undefined) return {};
 				if (!args || typeof args !== "object" || Array.isArray(args))
-					return args;
+					throw new Error(
+						'Supply an action object: await tools.notes({ action: "read_file", path: "checkpoint" }); tools.notes() returns help',
+					);
 				const params = { ...args } as Record<string, unknown>;
+				if (
+					(params["action"] === "write_file" ||
+						params["action"] === "append_to_file") &&
+					"content" in params
+				) {
+					if (!("text" in params)) params["text"] = params["content"];
+					delete params["content"];
+				}
 				if (
 					params["action"] === "list_files_by_prefix" &&
 					params["max_files"] !== undefined
 				) {
-					params["max_results"] ??= params["max_files"];
+					if (!("max_results" in params))
+						params["max_results"] = params["max_files"];
 					delete params["max_files"];
 				}
+				if (!discovery("notes", params)) relevant("notes", params);
+				for (const [field, value] of Object.entries(params)) {
+					const schema =
+						NOTES_SCHEMA.properties[
+							field as keyof typeof NOTES_SCHEMA.properties
+						];
+					if (!schema || !Check(schema, value))
+						throw new Error(
+							`Invalid notes ${field}; call tools.notes() for exact arguments`,
+						);
+				}
 				return params;
 			},
 			execute: (callId, input, signal, _update, ctx) =>

package/src/windows.ts

@@ -10,12 +10,16 @@ import type {
 import { keyHint } from "@earendil-works/pi-coding-agent";
 import { Box, Text, TruncatedText } from "@earendil-works/pi-tui";
 import type { WindowIdentity } from "./bridge.js";
+import {
+	renderTaskBoundaryReminder,
+	taskBoundaryEligible,
+} from "./task-boundary.js";
 
 export const WINDOW_MESSAGE = "notes-compaction:window:v1";
 export const SETTLEMENT_ENTRY = "notes-compaction:settled:v1";
 export interface WindowDetails {
 	protocol: 1;
-	kind: "window" | "identity" | "reminder" | "urgent";
+	kind: "window" | "identity" | "reminder" | "urgent" | "task-boundary";
 	identity: WindowIdentity;
 	trim: boolean;
 }
@@ -32,11 +36,13 @@ export function registerWindowRenderer(pi: ExtensionAPI): void {
 			const details = parseWindowDetails(message.details);
 			if (!details || typeof message.content !== "string") return undefined;
 			const title =
-				details.kind === "urgent"
-					? "Context nearly full · Save notes and start a new window now"
-					: details.kind === "reminder"
-						? "Context checkpoint reminder · Save notes and start a new window"
-						: `Context window ${details.identity.windowNumber + 1} · Notes and history`;
+				details.kind === "task-boundary"
+					? "Task-boundary reminder"
+					: details.kind === "urgent"
+						? "Context nearly full · Save notes and start a new window now"
+						: details.kind === "reminder"
+							? "Context checkpoint reminder · Save notes and start a new window"
+							: `Context window ${details.identity.windowNumber + 1} · Notes and history`;
 			const box = new Box(outputPad, 1, (text) =>
 				theme.bg("customMessageBg", text),
 			);
@@ -85,7 +91,7 @@ function parseWindowDetails(value: unknown): WindowDetails | undefined {
 	if (
 		details.protocol !== 1 ||
 		!ids ||
-		!["window", "identity", "reminder", "urgent"].includes(
+		!["window", "identity", "reminder", "urgent", "task-boundary"].includes(
 			details.kind ?? "",
 		) ||
 		typeof details.trim !== "boolean"
@@ -100,7 +106,9 @@ function parseWindowDetails(value: unknown): WindowDetails | undefined {
 }
 
 /** Understand previous PCC window IDs for familiar history lookup, without importing its runtime. */
-export function windowDetails(entry: SessionEntry): WindowDetails | undefined {
+export function windowDetails(
+	entry: SessionEntry | CustomMessageEntryDraft,
+): WindowDetails | undefined {
 	if (entry.type !== "custom_message") return;
 	return messageWindowDetails(entry.customType, entry.details);
 }
@@ -122,14 +130,14 @@ function messageWindowDetails(
 		!details ||
 		typeof details !== "object" ||
 		!("kind" in details) ||
-		details.kind !== "window"
+		(details.kind !== "window" && details.kind !== "task-boundary")
 	)
 		return;
 	const ids = identity(details);
 	return ids
 		? {
 				protocol: 1,
-				kind: "window",
+				kind: details.kind,
 				identity: ids,
 				trim:
 					"trimPreviousWindow" in details &&
@@ -182,13 +190,18 @@ export class Windows {
 				this.compactedSinceBoundary = false;
 			} else if (
 				details &&
-				(details.kind === "reminder" || details.kind === "urgent")
+				(details.kind === "reminder" ||
+					details.kind === "urgent" ||
+					details.kind === "task-boundary")
 			)
 				this.reminders.add(
 					`${details.identity.currentWindowId}:${details.kind}`,
 				);
 			if (entry.type === "compaction") {
-				this.reminders.clear();
+				// Compaction frees capacity, but does not create a new window identity.
+				this.reminders = new Set(
+					[...this.reminders].filter((key) => key.endsWith(":task-boundary")),
+				);
 				this.compactedSinceBoundary = true;
 			}
 		}
@@ -226,21 +239,47 @@ export class Windows {
 					: Math.round((remainingTokens / contextWindow) * 1000) / 10,
 		};
 	}
-	reminder(ctx: ExtensionContext): CustomMessageEntryDraft | undefined {
+	reminder(
+		ctx: ExtensionContext,
+		taskBoundaryReminder = 0,
+		checkpointReminder = true,
+	): CustomMessageEntryDraft | undefined {
 		const { remainingTokens, contextWindow, remainingPercent } =
 			this.remaining(ctx);
-		if (!this.current || remainingTokens === undefined) return;
-		const used = 100 * (1 - remainingTokens / contextWindow);
-		const kind = used >= 90 ? "urgent" : used >= 85 ? "reminder" : undefined;
-		if (!kind || this.reminders.has(`${this.current.currentWindowId}:${kind}`))
+		if (
+			!this.current ||
+			remainingTokens === undefined ||
+			remainingPercent === undefined
+		)
 			return;
-		this.reminders.add(`${this.current.currentWindowId}:reminder`);
+		const used = 100 * (1 - remainingTokens / contextWindow);
+		let kind: WindowDetails["kind"] | undefined = checkpointReminder
+			? used >= 90
+				? "urgent"
+				: used >= 85
+					? "reminder"
+					: undefined
+			: undefined;
+		if (kind && this.reminders.has(`${this.current.currentWindowId}:${kind}`))
+			kind = undefined;
+		if (
+			!kind &&
+			taskBoundaryReminder &&
+			!this.reminders.has(`${this.current.currentWindowId}:task-boundary`) &&
+			taskBoundaryEligible(ctx, taskBoundaryReminder)
+		)
+			kind = "task-boundary";
+		if (!kind) return;
+		this.reminders.add(`${this.current.currentWindowId}:${kind}`);
 		if (kind === "urgent")
-			this.reminders.add(`${this.current.currentWindowId}:urgent`);
+			this.reminders.add(`${this.current.currentWindowId}:reminder`);
 		return {
 			type: "custom_message",
 			customType: WINDOW_MESSAGE,
-			content: `<context_window_reminder>\n${kind === "urgent" ? "Urgent: " : ""}${remainingPercent}% remaining. Checkpoint the active request, state and known history IDs in notes, then call new_context ${kind === "urgent" ? "now, before other work" : "before continuing work"}.\n</context_window_reminder>`,
+			content:
+				kind === "task-boundary"
+					? renderTaskBoundaryReminder(remainingPercent)
+					: `<context_window_reminder>\n${kind === "urgent" ? "Urgent: " : ""}${remainingPercent}% remaining. Checkpoint the active request, state and known history IDs in notes, then call new_context ${kind === "urgent" ? "now, before other work" : "before continuing work"}.\n</context_window_reminder>`,
 			display: true,
 			details: {
 				protocol: 1,