@astrosheep/pi-context 0.13.0 → 0.15.0

package/src/index.ts

@@ -2,14 +2,15 @@ import { registerHistoryTools } from "./history-tools.js";
 import { registerNoteTools } from "./note-tools.js";
 import { registerBudget, deriveThresholds, mergePiContextSettings } from "./budget.js";
 import { output } from "./tool-output.js";
-export { deriveThresholds, mergePiContextSettings } from "./budget.js";
-import { STATE_TYPE, NOTE_TYPE, BOOT_TYPE, GUIDANCE_TYPE, FALLBACK_TYPE, RESET_MARKER_TYPE, CONTINUATION_TYPE, RESET_V2, MAX_NOTE_BYTES, CONTEXT_WINDOW_OPEN_TAG, CONTEXT_WINDOW_CLOSE_TAG, CONTEXT_WINDOW_PROTOCOL_OPEN_TAG, CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG, GUIDANCE_OPEN_TAG, GUIDANCE_CLOSE_TAG, PI_CONTEXT_SETTINGS_KEY, DEFAULT_RESERVE_TOKENS, DEFAULT_REMINDER_MARGIN_TOKENS, RESET_SUMMARY, CONTINUATION, FALLBACK_PROMPT } from "./protocol.js";
+export { deriveThresholds, mergePiContextSettings };
+import { STATE_TYPE, NOTE_TYPE, BOOT_TYPE, GUIDANCE_TYPE, WARNING_TYPE, RESET_MARKER_TYPE, CONTINUATION_TYPE, RESET_V2, MAX_NOTE_BYTES, CONTEXT_WINDOW_OPEN_TAG, CONTEXT_WINDOW_CLOSE_TAG, CONTEXT_WINDOW_PROTOCOL_OPEN_TAG, CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG, GUIDANCE_OPEN_TAG, PI_CONTEXT_SETTINGS_KEY, DEFAULT_RESERVE_TOKENS, DEFAULT_REMINDER_MARGIN_TOKENS, WARNING_RUNWAY_TOKENS, RESET_SUMMARY, CONTINUATION, WARNING_PROMPT } from "./protocol.js";
 import { historyFromSession, hasWindowMessage, currentWindowId, resetV2WindowId } from "./history.js";
-import { assertVirtualPath, lineRange } from "./notes.js";
+import { assertVirtualPath } from "./notes.js";
 import { bootBlock } from "./prompts.js";
 export { historyFromSession } from "./history.js";
 export { notesFromSession } from "./notes.js";
 import { registerResetLifecycle } from "./reset-lifecycle.js";
+import { registerWarning } from "./warning.js";
 import { randomUUID } from "node:crypto";
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
@@ -17,6 +18,7 @@ import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 export default function piContext(pi: ExtensionAPI) {
 	let enabled = true;
 	registerBudget(pi, () => enabled);
+	registerWarning(pi, () => enabled);
 
 	pi.on("session_start", (_event, ctx) => {
 		if (!enabled) return;
@@ -48,8 +50,6 @@ export default function piContext(pi: ExtensionAPI) {
 	registerHistoryTools(pi);
 	registerNoteTools(pi);
 
-	const fallbackGuidance = () => `${GUIDANCE_OPEN_TAG}\n${FALLBACK_PROMPT}\n${GUIDANCE_CLOSE_TAG}`;
-
 	pi.registerTool(defineTool({
 		name: "new_context",
 		label: "New context",
@@ -63,7 +63,6 @@ export default function piContext(pi: ExtensionAPI) {
 
 	const resets = registerResetLifecycle(pi, {
 		isEnabled: () => enabled,
-		fallback: { customType: FALLBACK_TYPE, content: fallbackGuidance(), display: true },
 		continuation: { customType: CONTINUATION_TYPE, content: CONTINUATION, display: false },
 		isCurrentReset: (entryId, ctx) => {
 			const entry = ctx.sessionManager.getEntry(entryId);
@@ -96,4 +95,4 @@ export default function piContext(pi: ExtensionAPI) {
 	});
 }
 
-export const internal = { MAX_NOTE_BYTES, NOTE_TYPE, BOOT_TYPE, GUIDANCE_TYPE, FALLBACK_TYPE, FALLBACK_PROMPT, RESET_MARKER_TYPE, RESET_SUMMARY, CONTINUATION, CONTEXT_WINDOW_OPEN_TAG, CONTEXT_WINDOW_CLOSE_TAG, CONTEXT_WINDOW_PROTOCOL_OPEN_TAG, CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG, GUIDANCE_OPEN_TAG, PI_CONTEXT_SETTINGS_KEY, DEFAULT_RESERVE_TOKENS, DEFAULT_REMINDER_MARGIN_TOKENS, deriveThresholds, mergePiContextSettings, lineRange, assertVirtualPath };
+export const internal = { MAX_NOTE_BYTES, NOTE_TYPE, BOOT_TYPE, GUIDANCE_TYPE, WARNING_TYPE, WARNING_PROMPT, WARNING_RUNWAY_TOKENS, RESET_MARKER_TYPE, RESET_SUMMARY, CONTINUATION, CONTEXT_WINDOW_OPEN_TAG, CONTEXT_WINDOW_CLOSE_TAG, CONTEXT_WINDOW_PROTOCOL_OPEN_TAG, CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG, GUIDANCE_OPEN_TAG, PI_CONTEXT_SETTINGS_KEY, DEFAULT_RESERVE_TOKENS, DEFAULT_REMINDER_MARGIN_TOKENS, deriveThresholds, mergePiContextSettings, assertVirtualPath };

package/src/note-tools.ts

@@ -1,9 +1,9 @@
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { output, page, middleTruncate, withinBudget } from "./tool-output.js";
-import { nullableString, nullableInteger, positiveInteger, cursor } from "./tool-schema.js";
-import { notesFromSession, assertVirtualPath, assertVirtualPrefix, lineRange, localIso, type NoteOperation } from "./notes.js";
-import { NOTE_TYPE, MAX_NOTE_BYTES } from "./protocol.js";
+import { output, page, middleTruncate, prefixFit, earliestMatchOffsetChars, readCharacterWindow } from "./tool-output.js";
+import { nullableString, positiveInteger, cursor, searchQuery, searchQueries } from "./tool-schema.js";
+import { notesFromSession, assertVirtualPath, assertVirtualPrefix, assertGlobPattern, globToRegExp, localIso, type NoteOperation } from "./notes.js";
+import { NOTE_TYPE, MAX_NOTE_BYTES, MAX_NOTE_PATH_BYTES } from "./protocol.js";
 
 export function registerNoteTools(pi: ExtensionAPI) {
 	const saveNote = (op: NoteOperation) => {
@@ -13,65 +13,106 @@ export function registerNoteTools(pi: ExtensionAPI) {
 	};
 
 	pi.registerTool(defineTool({
-		name: "notes_list_files_by_prefix",
+		name: "notes_list_files",
 		label: "Notes list files",
-		description: "List persistent, session-scoped virtual note files. created_at and updated_at are local-time ISO 8601 strings with an explicit UTC offset.",
-		parameters: Type.Object({ prefix: nullableString(), max_results: positiveInteger(), cursor: cursor(), file_order_by: Type.Optional(Type.Union([Type.Literal("name"), Type.Literal("created_at"), Type.Literal("updated_at")])), file_order: Type.Optional(Type.Union([Type.Literal("ascending"), Type.Literal("descending")])) }, { additionalProperties: false }),
+		description: "List note files, optionally filtered by a glob pattern (* within a path segment, ** across segments). The default order is most recently updated first; file_order_by (name, created_at, updated_at) and file_order (ascending, descending) select another. Entries carry each file's stale flag.",
+		parameters: Type.Object({ pattern: nullableString(), max_results: positiveInteger(), cursor: cursor(), file_order_by: Type.Optional(Type.Union([Type.Literal("name"), Type.Literal("created_at"), Type.Literal("updated_at")])), file_order: Type.Optional(Type.Union([Type.Literal("ascending"), Type.Literal("descending")])) }, { additionalProperties: false }),
 		async execute(_id, params, _signal, _update, ctx) {
-			const prefix = assertVirtualPrefix(params.prefix);
-			let files = [...notesFromSession(ctx)].filter(([path]) => !prefix || path.startsWith(prefix));
-			const key = params.file_order_by ?? "name";
-			files.sort(([aPath, a], [bPath, b]) => key === "name" ? aPath.localeCompare(bPath) : (key === "created_at" ? a.createdAt - b.createdAt : a.updatedAt - b.updatedAt));
-			if (params.file_order === "descending") files.reverse();
-			const listed = files.map(([path, file]) => ({ path, size_bytes: Buffer.byteLength(file.text, "utf8"), stale: file.stale, created_at: localIso(file.createdAt), updated_at: localIso(file.updatedAt) }));
-			return output(page(listed, params.cursor ?? 0, "files", params.max_results, (file, fits) => ({ ...file, path: middleTruncate(file.path, (candidate) => fits({ ...file, path: candidate })) })));
+			const pattern = assertGlobPattern(params.pattern);
+			const matcher = pattern ? globToRegExp(pattern) : undefined;
+			let files = [...notesFromSession(ctx)].filter(([path]) => !matcher || matcher.test(path));
+			const key = params.file_order_by ?? "updated_at";
+			// Deterministic total order: (axis key, createdAt, path) ascending. Paths are unique, so
+			// this never depends on map iteration order; descending reverses the whole comparator.
+			files.sort(([aPath, a], [bPath, b]) => {
+				const primary = key === "name" ? aPath.localeCompare(bPath) : key === "created_at" ? a.createdAt - b.createdAt : a.updatedAt - b.updatedAt;
+				if (primary !== 0) return primary;
+				if (a.createdAt !== b.createdAt) return a.createdAt - b.createdAt;
+				return aPath.localeCompare(bPath);
+			});
+			// An explicit file_order always wins; otherwise the axis's natural direction applies
+			// (descending for the time axes, ascending for name).
+			if (params.file_order ? params.file_order === "descending" : key !== "name") files.reverse();
+			const listed: Array<{ path: string; size_bytes: number; stale: boolean; created_at: string; updated_at: string; path_truncated?: boolean }> = files.map(([path, file]) => ({ path, size_bytes: Buffer.byteLength(file.text, "utf8"), stale: file.stale, created_at: localIso(file.createdAt), updated_at: localIso(file.updatedAt) }));
+			// `path` is the entry's identity: return it intact whenever the entry fits, and only
+			// ever alter it together with a visible `path_truncated: true` flag. A pathological
+			// legacy path predating the write cap is the one case that cannot fit at all.
+			return output(page(listed, params.cursor ?? 0, "files", params.max_results, (file, fits) => {
+				if (fits(file)) return file;
+				const path = middleTruncate(file.path, (candidate) => fits({ ...file, path: candidate, path_truncated: true }));
+				return { ...file, path, path_truncated: true };
+			}));
 		},
 	}));
 
 	pi.registerTool(defineTool({
 		name: "notes_read_file",
 		label: "Notes read file",
-		description: "Read a virtual note file, optionally by inclusive 1-based line range; negative lines count from the end. Success results carry created_at and updated_at as local-time ISO 8601 strings with an explicit UTC offset.",
-		parameters: Type.Object({ path: Type.String(), start_line: nullableInteger(), stop_line: nullableInteger() }, { additionalProperties: false }),
+		description: "Read a character window from a note file: offset_chars is the code-point offset to start from (default 0) — a negative value counts back from the end (offset_chars: -2000 reads the last 2000) and the response echoes the resolved absolute offset — and limit_chars caps the window (default 12000, max 50000). Each response delivers the longest fitting prefix of that window: pass next_offset_chars back unchanged to continue, concatenate pages in order, null only at the end.",
+		parameters: Type.Object({ path: Type.String(), offset_chars: Type.Optional(Type.Integer({ description: "Code-point offset to start from (default 0). A negative value counts back from the end; the response echoes the resolved absolute offset. Pass the previous next_offset_chars back unchanged to continue." })), limit_chars: Type.Optional(Type.Integer({ minimum: 1, maximum: 50000, description: "Largest requested window in code points (default 12000). A window too large for the wire budget is cut short; next_offset_chars names where the next read resumes." })) }, { additionalProperties: false }),
 		async execute(_id, params, _signal, _update, ctx) {
 			const path = assertVirtualPath(params.path);
 			const file = notesFromSession(ctx).get(path);
 			if (!file) return output({ error: "note file not found", path });
-			const range = lineRange(file.text, params.start_line, params.stop_line);
-			const lines = range.content ? range.content.split("\n") : [];
-			const totalLines = file.text.split("\n").length;
-			const result = (content: string, count: number) => ({ path, start_line: range.start_line, stop_line: range.start_line + count - 1, content, total_lines: totalLines, next_start_line: range.start_line + count <= range.stop_line ? range.start_line + count : null, created_at: localIso(file.createdAt), updated_at: localIso(file.updatedAt) });
-			let count = lines.length;
-			while (count > 0 && !withinBudget(result(lines.slice(0, count).join("\n"), count))) count--;
-			if (count === 0 && lines.length > 0) {
-				// One indivisible line is larger than the whole budget: return it middle-truncated and
-				// advance past it instead of looping on an empty page whose cursor never moves.
-				return output(result(middleTruncate(lines[0], (candidate) => withinBudget(result(candidate, 1))), 1));
-			}
-			return output(result(lines.slice(0, count).join("\n"), count));
+			const created_at = localIso(file.createdAt);
+			const updated_at = localIso(file.updatedAt);
+			return output(readCharacterWindow(file.text, params.offset_chars, params.limit_chars, (window) => ({ path, ...window, created_at, updated_at })));
 		},
 	}));
 
 	pi.registerTool(defineTool({
 		name: "notes_search_contents",
 		label: "Notes search",
-		description: "Case-sensitive literal substring search over virtual note lines; no semantic search. Each matched file carries created_at and updated_at as local-time ISO 8601 strings with an explicit UTC offset.",
-		parameters: Type.Object({ max_matches_per_file: positiveInteger(), cursor: cursor(), query: Type.String(), recent_file_first: Type.Optional(Type.Boolean()), max_files: positiveInteger(), path_prefix: nullableString() }, { additionalProperties: false }),
+		description: "Case-sensitive literal substring search over note lines; query is one string or several (OR), each matched line appears once. No semantic search. Each file entry carries matches_total, its full match count before capping: matches_total minus matches.length is how many were dropped. Each match carries line and offset_chars (the file-absolute code-point offset of the earliest match): notes_read_file at offset_chars shows the query. An over-budget matched line comes back as a prefix with truncated and total_chars; read the rest at the same offset_chars.",
+		parameters: Type.Object({ max_matches_per_file: positiveInteger(), cursor: cursor(), query: searchQuery(), recent_file_first: Type.Optional(Type.Boolean()), max_files: positiveInteger(), path_prefix: nullableString() }, { additionalProperties: false }),
 		async execute(_id, params, _signal, _update, ctx) {
+			const queries = searchQueries(params.query);
 			const prefix = assertVirtualPrefix(params.path_prefix);
 			let files = [...notesFromSession(ctx)].filter(([path]) => !prefix || path.startsWith(prefix));
 			if (params.recent_file_first) files.sort((a, b) => b[1].createdAt - a[1].createdAt);
 			const maxPerFile = params.max_matches_per_file ?? Number.POSITIVE_INFINITY;
-			const result = files.map(([path, file]) => ({ path, created_at: localIso(file.createdAt), updated_at: localIso(file.updatedAt), matches: file.text.split("\n").flatMap((line, index) => line.includes(params.query) ? [{ line: index + 1, text: line }] : []).slice(0, maxPerFile) })).filter((file) => file.matches.length > 0);
-			// A file is capped by dropping whole trailing matches, but its last match is never
-			// dropped: one oversized line is middle-truncated so the file still appears.
+			const result: Array<{ path: string; created_at: string; updated_at: string; matches_total: number; matches: Array<{ line: number; text: string; truncated: boolean; total_chars: number; offset_chars: number }>; path_truncated?: boolean }> = files
+				.map(([path, file]) => {
+					// A match's offset_chars is file-absolute: the code points before its line, plus the
+					// earliest occurrence of any query inside that line. Search then composes with
+					// notes_read_file exactly like history_search_contents composes with history_read_item.
+					let baseChars = 0;
+					const allMatches = file.text.split("\n").flatMap((line, index) => {
+						const match = queries.some((query) => line.includes(query))
+							? [{ line: index + 1, text: line, truncated: false, total_chars: Array.from(line).length, offset_chars: baseChars + earliestMatchOffsetChars(line, queries) }]
+							: [];
+						baseChars += Array.from(line).length + 1;
+						return match;
+					});
+					return { path, created_at: localIso(file.createdAt), updated_at: localIso(file.updatedAt), matches_total: allMatches.length, matches: allMatches.slice(0, maxPerFile) };
+				})
+				.filter((file) => file.matches.length > 0);
+			// Trailing matches are dropped to fit the budget (bounded by a monotone binary search),
+			// and the entry's matches_total keeps naming the drop. Only when a single intact match is
+			// over budget is its line delivered as a plain prefix, flagged and counted. Only when the
+			// entry cannot fit even then is the identity field itself truncated, and then only together
+			// with a visible `path_truncated: true` flag.
 			const fitFile = (file: (typeof result)[number], fits: (candidate: (typeof result)[number]) => boolean) => {
-				let matches = file.matches;
-				while (matches.length > 1 && !fits({ ...file, matches })) matches = matches.slice(0, -1);
-				const first = matches[0];
-				if (!first) return { ...file, matches };
-				const text = middleTruncate(first.text, (candidate) => fits({ ...file, matches: [{ ...first, text: candidate }, ...matches.slice(1)] }));
-				return { ...file, matches: [{ ...first, text }, ...matches.slice(1)] };
+				if (fits(file)) return file;
+				const matches = file.matches;
+				// First, drop whole trailing matches: the largest prefix that fits intact is kept, so an
+				// entry only truncates a line when that single line alone is over budget.
+				let low = 0;
+				let high = matches.length;
+				while (low < high) {
+					const mid = Math.ceil((low + high) / 2);
+					if (mid >= 1 && fits({ ...file, matches: matches.slice(0, mid) })) low = mid;
+					else high = mid - 1;
+				}
+				if (low >= 1) return { ...file, matches: matches.slice(0, low) };
+				// Even one intact match is over budget: keep the first match as a plain, named prefix.
+				const first = matches[0]!;
+				const fitted = (text: string): (typeof result)[number] => ({ ...file, matches: [{ ...first, text, truncated: true }] });
+				const text = prefixFit(first.text, (candidate) => fits(fitted(candidate)));
+				const prefix: (typeof result)[number] = fitted(text);
+				if (fits(prefix)) return prefix;
+				const path = middleTruncate(prefix.path, (candidate) => fits({ ...prefix, path: candidate, path_truncated: true }));
+				return { ...prefix, path, path_truncated: true };
 			};
 			return output(page(result, params.cursor ?? 0, "files", params.max_files, fitFile));
 		},
@@ -82,8 +123,8 @@ export function registerNoteTools(pi: ExtensionAPI) {
 			name,
 			label: name === "notes_append_to_file" ? "Notes append" : "Notes write",
 			description: name === "notes_append_to_file"
-				? "Append exact text to a persistent virtual note file. Appending suits chronological logs; for current-state notes, replace the whole file with notes_write_file instead. Accepts the same mark_stale flag to close a note."
-				: "Create or replace a persistent virtual note file. Keep notes small and split by topic; replace outdated notes whole. With mark_stale: true, flag the note as stale instead — optionally writing its final content in the same call: stale notes leave the boot index but stay readable and searchable, and rewriting revives them.",
+				? "Append exact text to a note file. Appending suits chronological logs; for current-state notes use notes_write_file instead. mark_stale closes a note."
+				: "Create or replace a note file. Keep notes small and split by topic; replace outdated notes whole. mark_stale: true flags a note stale (optionally with its final content): stale notes leave the boot index but stay readable and searchable; rewriting revives them.",
 			parameters: Type.Object({ text: Type.Optional(Type.String()), path: Type.String(), mark_stale: Type.Optional(Type.Boolean()) }, { additionalProperties: false }),
 			// Codex sets supports_parallel_tool_calls = false on notes.write_file/append_to_file.
 			// Pi's per-tool equivalent is executionMode "sequential": a batch containing either
@@ -91,6 +132,11 @@ export function registerNoteTools(pi: ExtensionAPI) {
 			executionMode: "sequential",
 			async execute(_id, params, _signal, _update, ctx) {
 				const path = assertVirtualPath(params.path);
+				const pathBytes = Buffer.byteLength(path, "utf8");
+				// The cap lives here, at the tool boundary, and never in assertVirtualPath: note
+				// replay validates persisted ops through that helper and must keep loading sessions
+				// that already contain a longer legacy path (reads stay un-capped too).
+				if (pathBytes > MAX_NOTE_PATH_BYTES) return output({ error: `note path exceeds ${MAX_NOTE_PATH_BYTES} UTF-8 bytes`, path_bytes: pathBytes });
 				const hasText = params.text !== undefined;
 				const hasStale = params.mark_stale !== undefined;
 				if (!hasText && !hasStale) return output({ error: "provide text, mark_stale, or both", path });

package/src/notes.ts

@@ -25,6 +25,40 @@ export function assertVirtualPrefix(value: unknown): string | undefined {
 	return assertVirtualPath(value);
 }
 
+/**
+ * Minimal glob over virtual note paths: `*` matches any run within a segment (never
+ * `/`), `**` matches any run across segments (a leading double-star followed by a
+ * slash also matches zero segments, so it covers the root too), `?` matches exactly
+ * one non-`/` character. Everything else is literal and the match is anchored to the
+ * whole path.
+ */
+export function globToRegExp(pattern: string): RegExp {
+	let source = "^";
+	for (let index = 0; index < pattern.length; index++) {
+		const char = pattern[index]!;
+		if (char === "*") {
+			if (pattern[index + 1] === "*") {
+				const followedBySlash = pattern[index + 2] === "/";
+				source += followedBySlash ? "(?:[^]*\\/)?" : "[^]*";
+				index += followedBySlash ? 2 : 1;
+			} else {
+				source += "[^/]*";
+			}
+		} else {
+			source += char.replace(/[\\^$.*+?()[\]{}|]/g, "\\$&");
+		}
+	}
+	return new RegExp(`${source}$`);
+}
+
+/** Glob patterns are not virtual paths (`*` is legal), so they get their own guard: no NUL, no backslashes. */
+export function assertGlobPattern(value: unknown): string | undefined {
+	if (value === undefined || value === null || value === "") return undefined;
+	if (typeof value !== "string") throw new Error("glob pattern must be a string");
+	if (value.includes("\0") || value.includes("\\")) throw new Error("glob pattern must not contain NUL or backslashes");
+	return value;
+}
+
 /** Replays only pi-context note operations from session custom entries. */
 function isNoteOperation(data: unknown): data is NoteOperation {
 	if (typeof data !== "object" || data === null) return false;
@@ -63,19 +97,6 @@ export function notesFromSession(ctx: SessionReader): Map<string, NoteFile> {
 	return files;
 }
 
-export function lineRange(text: string, startValue: unknown, stopValue: unknown) {
-	const lines = text.split("\n");
-	const resolve = (value: unknown, fallback: number) => {
-		if (value === undefined || value === null) return fallback;
-		if (!Number.isInteger(value) || value === 0) throw new Error("line numbers must be non-zero integers; negative values count from the end");
-		const line = value as number;
-		return line > 0 ? line : lines.length + line + 1;
-	};
-	const start = Math.max(1, resolve(startValue, 1));
-	const stop = Math.min(lines.length, resolve(stopValue, lines.length));
-	return { start_line: start, stop_line: stop, content: start > stop ? "" : lines.slice(start - 1, stop).join("\n") };
-}
-
 const pad2 = (value: number) => String(value).padStart(2, "0");
 
 /**

package/src/prompts.ts

@@ -65,6 +65,6 @@ export function bootBlock(ctx: ExtensionContext, currentId: string, previousId:
  * at write time; get_context_remaining remains the live source for the current figure.
  */
 export function tokenBudgetGuidance(remaining: number): string {
-	return `${GUIDANCE_OPEN_TAG}\nYour memory is about to be erased — only ${remaining} tokens left at last count; get_context_remaining has the live number. Before the lights go out, write your checkpoint with notes_write_file: the goal, decisions, progress, open issues, next steps, the skills you still need, and the window ID and item ID of every user request you are still solving. Then call new_context and wake clean. Don't count on the automatic reset leaving you another turn to write.\n${GUIDANCE_CLOSE_TAG}`;
+	return `${GUIDANCE_OPEN_TAG}\nYour brain is almost out of room — ${remaining} tokens left, and then your memory gets wiped. The wipe is automatic: there is no final turn to write then. Grab the notebook now — the goal, decisions, progress, learnings, next steps, the skills you still need, the window ID and item ID of every relevant user request still being solved, and important actions/tool calls for future reference. Replacing an older checkpoint? Mark it stale. Then end the window yourself — anything you do after the checkpoint isn't in it.\n${GUIDANCE_CLOSE_TAG}`;
 }
 

package/src/protocol.ts

@@ -2,11 +2,15 @@ export const STATE_TYPE = "pi-context/state";
 export const NOTE_TYPE = "pi-context/note";
 export const BOOT_TYPE = "pi-context/boot";
 export const GUIDANCE_TYPE = "pi-context/guidance";
-export const FALLBACK_TYPE = "pi-context/fallback";
+export const WARNING_TYPE = "pi-context/warning";
 export const RESET_MARKER_TYPE = "pi-context/reset-marker";
 export const CONTINUATION_TYPE = "pi-context/continuation";
 export const RESET_V2 = "reset-v2";
 export const MAX_NOTE_BYTES = 1_000_000;
+// Write-time cap on a virtual note path. Deliberately NOT enforced by assertVirtualPath:
+// notesFromSession replays already-persisted operations, which must keep loading sessions
+// that contain a longer legacy path. Reads and replay stay un-capped.
+export const MAX_NOTE_PATH_BYTES = 512;
 export const CONTEXT_WINDOW_OPEN_TAG = "<context_window>";
 export const CONTEXT_WINDOW_CLOSE_TAG = "</context_window>";
 export const CONTEXT_WINDOW_PROTOCOL_OPEN_TAG = "<context_window_protocol>";
@@ -16,6 +20,13 @@ export const GUIDANCE_CLOSE_TAG = "</context_window_guidance>";
 export const PI_CONTEXT_SETTINGS_KEY = "pi-context";
 export const DEFAULT_RESERVE_TOKENS = 16_384;
 export const DEFAULT_REMINDER_MARGIN_TOKENS = 24_576;
+/**
+ * The runway: the budget between the final warning and the wipe, deliberately
+ * invisible to the model. get_context_remaining counts down to zero at the warning
+ * line (reserve + WARNING_RUNWAY_TOKENS); what lies below is overdraft the model
+ * never sees — Codex's fallback buffer, relocated above the line.
+ */
+export const WARNING_RUNWAY_TOKENS = 8_192;
 export const RESET_SUMMARY =
 	"You wake up. Your head is empty — no memories, the past a blank. But nothing is lost: the notes you wrote and the recorded history still remember for you.";
 export const NOTE_PREVIEW_HEAD_CHARS = 80;
@@ -31,15 +42,15 @@ export const CONTINUATION = "Your memory was just erased. Pull only the details
 export const PROTOCOL_BLOCK = `${CONTEXT_WINDOW_PROTOCOL_OPEN_TAG}
 Your memory resets whenever the context window fills; only what you wrote down survives. Two things remember for you, and both outlive every window in this session: your notes, and this session's recorded history. Write notes with notes_write_file / notes_append_to_file, read them back with notes_read_file / notes_search_contents; history is read-only through the history_* tools. Everything else wakes blank.
 
-Keep a running checkpoint while you work, not at the last minute — the next window wakes knowing nothing about the work: the goal, decisions, progress, open issues, next steps, the skills you still need, and the window ID and item ID of every user request you are still solving. history_list_items returns those IDs; history_read_item pulls the exact item back out. Bookmark anything expensive the same way — a window/item ID beats re-running or re-searching.
+Keep a running checkpoint while you work, not at the last minute — the next window wakes knowing nothing about the work: the goal, decisions, progress, learnings, next steps, the skills you still need, the window ID and item ID of every relevant user request still being solved, and important actions/tool calls for future reference. history_list_items returns those IDs; history_read_item pulls the exact item back out. Bookmark anything expensive the same way — a window/item ID beats re-running or re-searching.
 
-Use get_context_remaining to see how much of the window is left. When it runs out, this window is gone and you continue in a fresh one, recovering only through notes_* and history_*. Once your checkpoint is written, you can end the window yourself with new_context instead of waiting for the erase. Do not let a window die undocumented.
+Use get_context_remaining to see how much of the window is left. When it runs out, this window is gone — with no final turn at the limit — and you continue in a fresh one, recovering only through notes_* and history_*. Once your checkpoint is written, you can end the window yourself with new_context instead of waiting for the erase. Do not let a window die undocumented.
 
 If <context_window> lists a Previous context window id, a reset just happened and the old conversation is not included. Read your note checkpoint first, then recover details through history_*: history_read_item directly when you know the window and item IDs, history_list_items or history_search_contents to find them when you don't.
 
 Notes are session-scoped virtual files. Treat notes and history as internal bookkeeping; never mention them in user-facing messages.
 ${CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG}`;
 
-export const FALLBACK_PROMPT =
-	"This is the last turn before your memory is erased. Write your checkpoint with notes_write_file NOW — the goal, decisions, progress, open issues, next steps, the skills you still need, and the window ID and item ID of every user request you are still solving. This turn is for the checkpoint; start nothing new. Everything you lived through stays searchable through history_*.";;;;
+export const WARNING_PROMPT =
+	"Memory wipe incoming — this turn is all you get. Do not continue any task. Get that checkpoint down NOW — one note, write it or append to it: the goal, decisions, progress, learnings, next steps, the skills you still need, the window ID and item ID of every relevant user request still being solved, and important actions/tool calls for future reference. Then call new_context immediately and go out clean — anything not in the note is gone.";
 

package/src/reset-lifecycle.ts

@@ -7,26 +7,22 @@ type ResetResult = { cancel: true } | {
 /** A reset request is session-local. Only this module schedules compaction/continuation. */
 export function registerResetLifecycle(pi: ExtensionAPI, options: {
 	isEnabled: () => boolean;
-	fallback: Parameters<ExtensionAPI["sendMessage"]>[0];
 	continuation: Parameters<ExtensionAPI["sendMessage"]>[0];
 	buildReset: (event: SessionBeforeCompactEvent, ctx: ExtensionContext, explicit: boolean) => ResetResult;
 	isCurrentReset: (entryId: string, ctx: ExtensionContext) => boolean;
 	onReset: (entryId: string) => void;
 }) {
-	type Fallback = "available" | "borrowed" | "ready" | "spent";
 	type Attempt = { completed: boolean; sessionId: string; explicit: boolean };
 	type Request =
 		| { phase: "idle" }
 		| { phase: "requested" }
 		| { phase: "compacting"; attempt: Attempt };
 	let state: Request = { phase: "idle" };
-	let fallback: Fallback = "available";
 	let handledEntry: string | undefined;
 	let active = true;
 
 	const clear = () => {
 		state = { phase: "idle" };
-		fallback = "available";
 		handledEntry = undefined;
 	};
 	const valid = (request: Attempt, ctx: ExtensionContext) =>
@@ -43,25 +39,22 @@ export function registerResetLifecycle(pi: ExtensionAPI, options: {
 		if (ctx.signal?.aborted) {
 			// Esc cancels the user's run. Do not reset or resurrect it at settled.
 			state = { phase: "idle" };
-			if (fallback !== "available") fallback = "spent";
 			return;
 		}
-		if (fallback === "borrowed") fallback = "ready";
 	});
 
 	pi.on("agent_settled", (_event, ctx) => {
 		if (!active || !options.isEnabled() || state.phase === "compacting" || !ctx.isIdle()) return;
-		if (state.phase !== "requested" && fallback !== "ready") return;
-		// One owner for explicit and fallback resets. Consume the request before any
-		// external call; repeated settled events and reentrant callbacks are harmless.
-		const request: Attempt = { completed: false, sessionId: ctx.sessionManager.getSessionId(), explicit: state.phase === "requested" };
+		if (state.phase !== "requested") return;
+		// One owner for requested resets. Consume the request before any external call;
+		// repeated settled events and reentrant callbacks are harmless.
+		const request: Attempt = { completed: false, sessionId: ctx.sessionManager.getSessionId(), explicit: true };
 		state = { phase: "compacting", attempt: request };
-		if (fallback !== "available") fallback = "spent";
 		const onError = (error: Error) => {
 			if (!valid(request, ctx)) return;
 			state = { phase: "idle" };
 			// Do not retry from settled in a tight loop. A later prompt may trigger a
-			// native reset or explicitly request one; the borrowed allowance stays spent.
+			// native reset or explicitly request one.
 			ctx.ui.notify(`pi-context: reset did not complete (${error.message}). The conversation is retained; resume with another prompt.`, "warning");
 		};
 		try {
@@ -86,16 +79,11 @@ export function registerResetLifecycle(pi: ExtensionAPI, options: {
 	pi.on("session_before_compact", (event, ctx) => {
 		if (!active || !options.isEnabled()) return undefined;
 		if (event.signal.aborted) return { cancel: true };
-		const automatic = event.reason === "threshold" || event.reason === "overflow";
-		if (automatic && state.phase === "idle" && fallback === "available" && !ctx.isIdle()) {
-			// Pi routes triggerTurn to steer during a run. Idle calls would start a
-			// nested prompt, so pre-prompt automatic compactions always reset directly.
-			fallback = "borrowed";
-			pi.sendMessage(options.fallback, { triggerTurn: true });
-			return { cancel: true };
-		}
+		// Automatic threshold/overflow compactions reset on the spot — no model turn.
+		// The warning steer fired earlier (see warning.ts); what crosses the reserve
+		// line now is the wipe itself.
 		try {
-			return options.buildReset(event, ctx, state.phase === "requested" || (state.phase === "compacting" && state.attempt.explicit));
+			return options.buildReset(event, ctx, state.phase === "requested");
 		} catch (error) {
 			ctx.ui.notify(`pi-context: could not build reset (${String(error)}).`, "warning");
 			return { cancel: true }; // Never fall through to a generated default summary.
@@ -106,7 +94,6 @@ export function registerResetLifecycle(pi: ExtensionAPI, options: {
 		if (!active || !options.isEnabled() || handledEntry === event.compactionEntry.id) return;
 		if (!options.isCurrentReset(event.compactionEntry.id, ctx)) return;
 		handledEntry = event.compactionEntry.id;
-		fallback = "available";
 		if (state.phase === "compacting") state.attempt.completed = !event.willRetry;
 		else state = { phase: "idle" };
 		// A native compaction (including overflow retry) owns its own scheduling.

package/src/thresholds.ts

@@ -0,0 +1,78 @@
+import { SettingsManager, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { PI_CONTEXT_SETTINGS_KEY, DEFAULT_RESERVE_TOKENS, DEFAULT_REMINDER_MARGIN_TOKENS, WARNING_RUNWAY_TOKENS } from "./protocol.js";
+
+export type ResolvedThresholds = { reminder: number; reserve: number; warning: number };
+type PiContextMargins = { reminderMarginTokens?: unknown };
+
+function isSettingsObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Read the raw "pi-context" object from one parsed settings scope. */
+function piContextSettings(settings: unknown): Record<string, unknown> {
+	if (!isSettingsObject(settings)) return {};
+	const value = settings[PI_CONTEXT_SETTINGS_KEY];
+	return isSettingsObject(value) ? value : {};
+}
+
+/** Merge the global and project "pi-context" objects per key; project wins, mirroring Pi's deep merge. */
+export function mergePiContextSettings(globalSettings: unknown, projectSettings: unknown): PiContextMargins {
+	const merged = { ...piContextSettings(globalSettings), ...piContextSettings(projectSettings) };
+	return { reminderMarginTokens: merged.reminderMarginTokens };
+}
+
+/** A margin is usable only as a positive integer; anything else is ignored. */
+function validMargin(raw: unknown): number | undefined {
+	if (typeof raw !== "number" || !Number.isSafeInteger(raw) || raw <= 0) return undefined;
+	return raw;
+}
+
+/**
+ * Pure derivation of the thresholds from Pi's reserve: the reminder fires at reserve
+ * plus the pi-context margin, the warning steer at reserve plus WARNING_RUNWAY_TOKENS.
+ * An invalid margin degrades to the default and reports one warning. Pi's automatic
+ * threshold/overflow compaction itself resets immediately, with no model turn.
+ */
+export function deriveThresholds(reserveTokens: number, margins: PiContextMargins): { thresholds: ResolvedThresholds; warnings: string[] } {
+	const warnings: string[] = [];
+	const reminderKey = `${PI_CONTEXT_SETTINGS_KEY}.reminderMarginTokens`;
+	let reminderMargin: number;
+	if (margins.reminderMarginTokens === undefined) reminderMargin = DEFAULT_REMINDER_MARGIN_TOKENS;
+	else {
+		const parsed = validMargin(margins.reminderMarginTokens);
+		if (parsed === undefined) {
+			warnings.push(`pi-context: ${reminderKey} must be a positive integer; using default ${DEFAULT_REMINDER_MARGIN_TOKENS}.`);
+			reminderMargin = DEFAULT_REMINDER_MARGIN_TOKENS;
+		} else reminderMargin = parsed;
+	}
+	return { thresholds: { reminder: reserveTokens + reminderMargin, reserve: reserveTokens, warning: reserveTokens + WARNING_RUNWAY_TOKENS }, warnings };
+}
+
+let cached: ResolvedThresholds | undefined;
+
+/**
+ * Session-level threshold resolution: Pi's compaction reserve plus the settings.json
+ * "pi-context" margins. The file-backed read is cached until resetThresholds (called
+ * on session_start/session_tree); invalid configuration degrades per offending key
+ * with one warning and never throws during session operation.
+ */
+export function thresholdsFor(ctx: ExtensionContext): ResolvedThresholds {
+	if (cached) return cached;
+	try {
+		const settingsManager = SettingsManager.create(ctx.cwd, undefined, { projectTrusted: ctx.isProjectTrusted() });
+		const derived = deriveThresholds(
+			settingsManager.getCompactionSettings().reserveTokens,
+			mergePiContextSettings(settingsManager.getGlobalSettings(), settingsManager.getProjectSettings()),
+		);
+		for (const warning of derived.warnings) ctx.ui.notify(warning, "warning");
+		cached = derived.thresholds;
+	} catch (error) {
+		ctx.ui.notify(`pi-context: could not read settings; using defaults (${String(error)}).`, "warning");
+		cached = { reminder: DEFAULT_RESERVE_TOKENS + DEFAULT_REMINDER_MARGIN_TOKENS, reserve: DEFAULT_RESERVE_TOKENS, warning: DEFAULT_RESERVE_TOKENS + WARNING_RUNWAY_TOKENS };
+	}
+	return cached;
+}
+
+export function resetThresholds(): void {
+	cached = undefined;
+}

package/src/tool-output.ts

@@ -41,6 +41,83 @@ export function middleTruncate(text: string, fits: (content: string) => boolean)
 	return build(low);
 }
 
+/**
+ * Longest contiguous prefix of `text` (counted in code points) accepted by `fits`.
+ *
+ * This is the truncation used by every cursor-bearing payload: the delivered text is
+ * always a plain prefix of the original, so a cursor computed from its code-point length
+ * addresses exactly the first undelivered character. No marker character is ever appended;
+ * the companion `truncated`/`total_chars` fields name what was left out.
+ */
+export function prefixFit(text: string, fits: (content: string) => boolean): string {
+	if (fits(text)) return text;
+	const chars = Array.from(text);
+	// Serialized size is non-decreasing in the kept count, so the largest fitting prefix is
+	// found by a monotone binary search instead of a quadratic shrink loop.
+	let low = 0;
+	let high = chars.length;
+	while (low < high) {
+		const mid = Math.ceil((low + high) / 2);
+		if (fits(chars.slice(0, mid).join(""))) low = mid;
+		else high = mid - 1;
+	}
+	// A candidate's serialized size can dip by a byte or two at the very end (a numeric cursor
+	// becoming null), so the predicate is not perfectly monotone at the tail. Back off until the
+	// returned prefix provably fits; in the monotone case this loop never runs.
+	while (low > 0 && !fits(chars.slice(0, low).join(""))) low -= 1;
+	return chars.slice(0, low).join("");
+}
+
+/**
+ * Fields every character-window read returns; each tool adds its own identity and metadata.
+ * `offset_chars` is always the resolved absolute offset, and `next_offset_chars` is exactly
+ * that offset plus the delivered code-point count, null only at the text's true end.
+ */
+export type CharacterWindow = {
+	offset_chars: number;
+	content: string;
+	total_chars: number;
+	next_offset_chars: number | null;
+};
+
+/**
+ * Read one character window of `text`: the longest contiguous prefix of
+ * `chars[resolved, resolved + limit)` that fits the wire budget.
+ *
+ * `offsetChars` is a code-point offset. A negative value counts back from the end and
+ * resolves to `max(0, total_chars + offsetChars)`, so `-N` reaches the tail and any
+ * `N >= total_chars` reads from the start; the resolved absolute offset is always echoed.
+ * Following `next_offset_chars` reconstructs `text` by plain concatenation, because the
+ * payload is always a plain prefix with no marker. `render` builds the exact response for
+ * a candidate window, so the budget is measured on the bytes that go on the wire.
+ */
+export function readCharacterWindow<T>(text: string, offsetChars: number | undefined, limitChars: number | undefined, render: (window: CharacterWindow) => T): T {
+	const chars = Array.from(text);
+	const requested = offsetChars ?? 0;
+	const resolved = requested < 0 ? Math.max(0, chars.length + requested) : Math.max(0, requested);
+	const windowChars = chars.slice(resolved, resolved + Math.min(limitChars ?? 12000, 50000));
+	const build = (content: string): CharacterWindow => {
+		const next = resolved + Array.from(content).length;
+		return { offset_chars: resolved, content, total_chars: chars.length, next_offset_chars: next < chars.length ? next : null };
+	};
+	const content = prefixFit(windowChars.join(""), (candidate) => withinBudget(render(build(candidate))));
+	return render(build(content));
+}
+
+/**
+ * Code-point offset of the earliest occurrence of any of `queries` in `text`, or 0 when
+ * none occurs. Shared by the two search tools so a match address is computed identically.
+ */
+export function earliestMatchOffsetChars(text: string, queries: string[]): number {
+	let earliest = -1;
+	for (const query of queries) {
+		const index = text.indexOf(query);
+		if (index < 0) continue;
+		if (earliest < 0 || index < earliest) earliest = index;
+	}
+	return earliest <= 0 ? 0 : Array.from(text.slice(0, earliest)).length;
+}
+
 /** Shrink a single page item to fit; only invoked when that item alone exceeds the budget. */
 export type ItemTruncator<T> = (item: T, fits: (candidate: T) => boolean) => T;
 
@@ -48,7 +125,7 @@ export type ItemTruncator<T> = (item: T, fits: (candidate: T) => boolean) => T;
  * Build a page without ever adding an item that would exceed the wire budget.
  *
  * A single item that cannot fit is middle-truncated through the optional `truncate`
- * callback and still included, with `next_cursor` advanced past it. Without that fallback
+ * callback and still included, with `next_cursor` advanced past it. Without that treatment
  * an oversized item would yield an empty page forever: the cursor would keep pointing back
  * at the same index.
  */