@astrosheep/pi-context 0.10.1 → 0.12.0

package/README.md

@@ -19,8 +19,8 @@ pi -e npm:@astrosheep/pi-context
 The extension composes Pi's public `session_before_compact` / `session_compact` hooks, custom session entries, and the `context` hook to approximate Codex's experimental context management:
 
 - **`new_context` tool** — the model requests a fresh context window. The extension waits for the current run to settle, compacts with a short deterministic reset message (old conversation is excluded from the new provider context but stays in the session), then sends one hidden continuation turn once compaction has fully completed, unless another prompt is already queued or running.
-- **`<context_window>` boot block** — the head of every fresh window. For a reset it IS the summary returned from `session_before_compact` (position 0, persisted, no extra message); for the root window `session_start` persists it once as a visible custom message. It carries the agent name and first/current/previous window IDs, the recent-notes index, and a `<context_window_protocol>` teaching block. The notes index lists up to three most-recent notes, each with its `X lines, Y UTF-8 bytes` metadata plus a local-time ISO 8601 `updated` timestamp (explicit UTC offset, never `Z`) and an inline preview. A note of 200 Unicode characters or fewer is shown whole; a longer one shows its first 120 and last 80 Unicode characters joined by an ellipsis, so the two ends never overlap and no text is repeated. The notes index is a window-open snapshot with the same frozen-at-write semantics as the reminder count. Nothing is injected transiently per request: the boot block is static once-per-window content, so the head of the window stays cache-stable. Codex diverges here — its `<context_window>` block carries only the agent path and window IDs, while the notes index is our own addition.
-- **Low-budget guidance** — when estimated remaining context first drops to the reminder threshold (by default **40,960 tokens**: Pi's default 16,384 `reserveTokens` plus a 24,576 reminder margin; see [Reminder timing](#reminder-timing)), a `<context_window_guidance>` reminder is **persisted once per window** into history (TUI-visible, no extra turn; `sendMessage` safely defers mid-stream). There is deliberately no transient copy: a bridge would make the model meet the same text twice at shifted positions, because history records the persisted copy after the crossing request's assistant reply. The reminder is an early warning, so arriving from the next request on costs nothing and keeps the model's view identical to recorded history. The measured remaining budget excludes `reserveTokens` and is frozen into the text at the threshold crossing, so the persisted reminder is a snapshot true at write time; `get_context_remaining` remains the live source for the current figure. The text is appended rather than prepended; existing history is not rewritten.
+- **`<context_window>` boot block** — the head of every fresh window. For a reset it IS the summary returned from `session_before_compact` (position 0, persisted, no extra message); for the root window `session_start` persists it once as a hidden custom message (`display: false`, kept out of the TUI). It carries the agent name and first/current/previous window IDs, the recent-notes index, and a `<context_window_protocol>` teaching block. The notes index lists up to three most-recent notes, each with its `X lines, Y UTF-8 bytes` metadata plus a local-time ISO 8601 `updated` timestamp (explicit UTC offset, never `Z`) and an inline preview. A note of 320 Unicode characters or fewer is shown whole; a longer one shows its first 80 and last 240 Unicode characters joined by an ellipsis, so the two ends never overlap and no text is repeated. The notes index is a window-open snapshot with the same frozen-at-write semantics as the reminder count. Nothing is injected transiently per request: the boot block is static once-per-window content, so the head of the window stays cache-stable. Codex diverges here — its `<context_window>` block carries only the agent path and window IDs, while the notes index is our own addition.
+- **Low-budget guidance** — when estimated remaining context first drops to the reminder threshold (by default **40,960 tokens**: Pi's default 16,384 `reserveTokens` plus a 24,576 reminder margin; see [Reminder timing](#reminder-timing)), a `<context_window_guidance>` reminder is **persisted once per window** into history (hidden from the TUI transcript — one ephemeral `ui.notify` warning tells the user instead, and the model never sees it; no extra turn; `sendMessage` safely defers mid-stream). There is deliberately no transient copy: a bridge would make the model meet the same text twice at shifted positions, because history records the persisted copy after the crossing request's assistant reply. The reminder is an early warning, so arriving from the next request on costs nothing and keeps the model's view identical to recorded history. The measured remaining budget excludes `reserveTokens` and is frozen into the text at the threshold crossing, so the persisted reminder is a snapshot true at write time; `get_context_remaining` remains the live source for the current figure. The text is appended rather than prepended; existing history is not rewritten.
 - **Two-phase automatic fallback** — while Pi is streaming, the first automatic `threshold`/`overflow` crossing of the reserve line does not reset immediately. `session_before_compact` queues the final note-taking instruction with `pi.sendMessage(..., { triggerTurn: true })` — which Pi routes to `agent.steer()` while streaming, so the message is queued synchronously and reaches the model before any pending user input — and returns `{ cancel: true }`. Pi records that as an aborted compaction, spends no summary, and continues the same run with the borrowed turn; no user text or images are copied, intercepted, or replayed, and no `input` handler is registered. Once the borrowed run has finished, `agent_end` arms the real reset and `agent_settled` requests it through `ctx.compact()` for both `threshold` and `overflow`, unless another compaction has already completed. Pi can perform another automatic check after a run, and overflow recovery has a one-shot guard. The settled scheduler ensures the borrowed turn has one reset owner even when no native check resets it. Requesting the reset after the run settles avoids issuing it from `agent_end` while Pi is still finishing the run. A phase flag makes the cancel happen at most once per window — it re-arms only after a completed reset starts a fresh window. A failed reset clears the pending request, warns the user, and leaves history intact; another prompt can retry without borrowing another turn. Extension-requested fallback resets send a continuation after the compaction completion callback. The borrow is skipped when the crossing arrives while Pi is idle (the pre-prompt check in `AgentSession.prompt()`, where `triggerTurn` would start a nested run and make the pending `Agent.prompt()` reject); that crossing resets directly. `manual` `/compact` and `new_context` never take the borrowed-turn path. The reminder asks the model to write notes early; if it misses that opportunity, old history remains searchable.
 - **Runtime toggle** — `/pi-context off` disables the boot block, guidance, and reset-style compaction (Pi's default compaction, including `keepRecentTokens`, applies again). `/pi-context on` re-enables; a bare `/pi-context` reports the current state.
 - **History tools** — the model searches pre-reset conversation with case-sensitive literal substring search, exactly like Codex's `history.*` namespace.
@@ -69,7 +69,9 @@ The nine Codex History/Notes actions are flattened because Pi tools have one glo
 
 `history_*` reads the current branch's actual Pi session entries, including entries hidden by earlier compaction. Window IDs are extension-owned: the root window is `pcw:<session-id>:root`, and each reset mints an 8-hex id baked into the compaction entry's `details.windowId` as `pcw:<session-id>:<minted>`. Pi-native compactions (extension toggled off) fall back to `pcw:<session-id>:<compaction-entry-id>`. Item IDs are the persisted Pi entry IDs. No transcript copy or volatile archive is maintained. Ordering is newest-first by default: `recent_first` omitted or `true` returns newest-first, and only an explicit `false` returns oldest-first; `history_list_windows`, `history_list_items`, and `history_search_contents` share that switch.
 
-`notes_*` stores operation entries in the same append-only Pi session under `pi-context/note`. They are session-scoped, survive JSONL reload, never enter provider context, and use safe relative virtual paths only (no absolute paths, `..`, `.`, empty components, or backslashes). Searches are literal and case-sensitive. `notes_read_file` accepts inclusive 1-based line ranges; negative line numbers count from the last line. `notes_read_file` success results and every matched file object from `notes_search_contents` also carry `created_at` and `updated_at`, the same fields `notes_list_files_by_prefix` returns. All note timestamps are local-time ISO 8601 strings with an explicit UTC offset (for example `2026-09-15T17:31:45.392+08:00`; a UTC host renders `+00:00`, never `Z`), while the persisted `NoteFile`/`NoteOperation` metadata keeps plain epoch milliseconds. Error results carry no timestamps. Writes are capped at 1,000,000 UTF-8 bytes.
+`history_*` and paged `notes_*` read/search results share a **32 KiB (32 * 1024 UTF-8 bytes) per-result budget**. List/search tools return whole items only and include `next_offset` (an integer cursor, or `null` when exhausted); pass that cursor back with the same parameters to continue. `history_read_item` defaults to `limit_chars: 12000`, accepts at most 50000, and returns `total_chars` plus `next_offset_chars` when more content remains. `notes_read_file` returns whole lines only, includes `total_lines`, and uses `next_start_line` for a bounded continuation. When one indivisible unit is larger than the whole budget (a single note line, search match, or history item), it is returned middle-truncated — head and tail joined by a `…[truncated N chars]…` marker, mirroring Codex's `truncate_middle` — instead of being dropped, so a page is never empty and its cursor always advances. `max_chars_per_item` limits Unicode code points including the truncation ellipsis (`…`). The 32 KiB choice matches Aider's default and Claude Code's roughly 30k-character limit while keeping worst-case CJK output (about 11k tokens) below Pi's default `reserveTokens` of 16384.
+
+`notes_*` stores operation entries in the same append-only Pi session under `pi-context/note`. They are session-scoped, survive JSONL reload, never enter provider context, and use safe relative virtual paths only (no absolute paths, `..`, `.`, empty components, or backslashes). Searches are literal and case-sensitive. `notes_read_file` accepts inclusive 1-based line ranges; negative line numbers count from the last line. Staleness is explicit and never inferred from timestamps. `notes_write_file` and `notes_append_to_file` accept an optional `mark_stale` boolean, and `notes_list_files_by_prefix` reports each file's `stale` flag. Stale notes leave the boot notes index — which omits itself once no fresh note remains — but stay listed, readable, and searchable. Each call must carry `text`, `mark_stale`, or both: `mark_stale: true` alone flags a note without touching its content, `mark_stale: false` alone clears the flag without touching content, and either call may carry `text` too — so final content can be written and marked stale in one call, and a closing log line can be appended and marked stale in one call. Carrying `text` without `mark_stale` revives a stale note, and marking a path that does not exist is an error. `notes_read_file` success results and every matched file object from `notes_search_contents` also carry `created_at` and `updated_at`, the same fields `notes_list_files_by_prefix` returns. All note timestamps are local-time ISO 8601 strings with an explicit UTC offset (for example `2026-09-15T17:31:45.392+08:00`; a UTC host renders `+00:00`, never `Z`), while the persisted `NoteFile`/`NoteOperation` metadata keeps plain epoch milliseconds. Error results carry no timestamps. Writes are capped at 1,000,000 UTF-8 bytes. `notes_write_file` and `notes_append_to_file` declare `executionMode: "sequential"` (the Pi equivalent of Codex's `supports_parallel_tool_calls = false`), so a tool batch containing either runs its calls one at a time and note read-modify-write cannot race with itself.
 
 Unlike Codex, the history tools do not advertise `agent_name`: Pi has no cross-agent session routing, so the parameter is omitted from the schemas entirely (strict `additionalProperties: false` still rejects it) instead of costing schema tokens on every request.
 
@@ -84,7 +86,7 @@ On `session_before_compact`, the extension appends a persistent custom reset mar
 
 The scheduler lives in [`src/reset-lifecycle.ts`](src/reset-lifecycle.ts); `src/index.ts` composes the features and builds reset boundaries. History and notes projections, tool adapters, budget policy, and prompt rendering have separate ownership described in [Architecture](docs/architecture.md). See the [lifecycle event table](docs/reset-lifecycle.md) for ownership and cancellation rules. Shutdown, tree navigation, and toggling off invalidate outstanding callbacks. An aborted run clears pending rollover work. Queued steering/follow-up messages may continue before the run settles; the extension does not clear or replay that queue.
 
-Pi's built-in “compacted into the following summary” envelope is left intact. Its content explicitly says: “Context window reset: this is a fresh window. The previous conversation is not included and no summary was generated. Notes and durable session history persist across windows.” No context filtering or TUI override is used to hide that envelope.
+Pi's built-in “compacted into the following summary” envelope is left intact. Its content says, in the extension's wake-up voice: “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.” No context filtering or TUI override is used to hide that envelope.
 
 The same handler is used for native automatic compaction. When Pi marks an overflow compaction `willRetry`, Pi core performs its single retry itself and this extension deliberately sends no second continuation. While the extension is enabled, its custom reset keeps nothing after the boundary marker, so Pi's `keepRecentTokens` setting has no effect; with `/pi-context off`, Pi's default compaction (and `keepRecentTokens`) applies again.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/pi-context",
-  "version": "0.10.1",
+  "version": "0.12.0",
   "type": "module",
   "description": "Codex-style context windows for Pi: reset-style compaction, durable session history tools, and persistent notes.",
   "license": "MIT",

package/src/budget.ts

@@ -101,7 +101,12 @@ export function registerBudget(pi: ExtensionAPI, isEnabled: () => boolean) {
 				// on (sendMessage defers safely to end of turn while streaming, queueing
 				// instead of splitting a tool call/result pair) costs nothing, and the
 				// model's view stays identical to recorded history, Codex-style.
-				pi.sendMessage({ customType: GUIDANCE_TYPE, content: tokenBudgetGuidance(Math.max(0, remaining - reserve)), display: true }, { triggerTurn: false });
+				// The persisted copy stays out of the TUI (display: false); one ephemeral
+				// notify tells the user instead — visible to the human, invisible to the
+				// model, and never recorded, so history and the model's view don't diverge.
+				const left = Math.max(0, remaining - reserve);
+				pi.sendMessage({ customType: GUIDANCE_TYPE, content: tokenBudgetGuidance(left), display: false }, { triggerTurn: false });
+				ctx.ui.notify(`pi-context: context budget low (${left} tokens before reserve) — checkpoint reminder recorded for the model, kept out of the chat view.`, "warning");
 			}
 		}
 		return undefined;

package/src/history-tools.ts

@@ -1,6 +1,6 @@
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { output } from "./tool-output.js";
+import { output, page, middleTruncate, withinBudget } from "./tool-output.js";
 import { positiveInteger, recentFirst, nullableString, role } from "./tool-schema.js";
 import { historyFromSession, filteredItems, visibleItem, allItems } from "./history.js";
 
@@ -22,10 +22,10 @@ export function registerHistoryTools(pi: ExtensionAPI) {
 		name: "history_list_items",
 		label: "History list items",
 		description: "List durable session items, including items before compaction, using opaque item and window IDs.",
-		parameters: Type.Object({ limit: positiveInteger(), recent_first: recentFirst(), tool_namespace: nullableString(), role: Type.Optional(role), tool_name: nullableString(), window_id: nullableString(), max_chars_per_item: positiveInteger() }, { additionalProperties: false }),
+		parameters: Type.Object({ limit: positiveInteger(), offset: Type.Optional(Type.Integer({ minimum: 0 })), recent_first: recentFirst(), tool_namespace: nullableString(), role: Type.Optional(role), tool_name: nullableString(), window_id: nullableString(), max_chars_per_item: positiveInteger() }, { additionalProperties: false }),
 		async execute(_id, params, _signal, _update, ctx) {
-			const items = filteredItems(ctx, params);
-			return output({ items: items.slice(0, params.limit ?? items.length).map((item) => visibleItem(item, params.max_chars_per_item ?? 1200)) });
+			const items = filteredItems(ctx, params).slice(0, params.limit ?? Number.POSITIVE_INFINITY).map((item) => visibleItem(item, params.max_chars_per_item ?? 1200));
+			return output(page(items, params.offset ?? 0, "items", undefined, (item, fits) => ({ ...item, truncated_content: middleTruncate(item.truncated_content, (candidate) => fits({ ...item, truncated_content: candidate })) })));
 		},
 	}));
 
@@ -33,14 +33,18 @@ export function registerHistoryTools(pi: ExtensionAPI) {
 		name: "history_read_item",
 		label: "History read item",
 		description: "Read a bounded character range from one durable session item.",
-		parameters: Type.Object({ item_id: Type.String(), offset_chars: Type.Optional(Type.Integer({ minimum: 0 })), limit_chars: positiveInteger(), window_id: Type.String() }, { additionalProperties: false }),
+		parameters: Type.Object({ item_id: Type.String(), offset_chars: Type.Optional(Type.Integer({ minimum: 0 })), limit_chars: Type.Optional(Type.Integer({ minimum: 1, maximum: 50000 })), window_id: Type.String() }, { additionalProperties: false }),
 		async execute(_id, params, _signal, _update, ctx) {
 			const item = allItems(ctx).find((candidate) => candidate.windowId === params.window_id && candidate.itemId === params.item_id);
 			if (!item) return output({ error: "unknown item_id or window_id" });
 			const chars = Array.from(item.content);
 			const offset = params.offset_chars ?? 0;
-			const limit = params.limit_chars ?? chars.length;
-			return output({ window_id: item.windowId, item_id: item.itemId, offset_chars: offset, content: chars.slice(offset, offset + limit).join("") });
+			const limit = Math.min(params.limit_chars ?? 12000, 50000);
+			const result = (content: string) => ({ window_id: item.windowId, item_id: item.itemId, offset_chars: offset, content, total_chars: chars.length, next_offset_chars: offset + limit < chars.length ? offset + limit : null });
+			// One clean middle-truncation replaces the old 0.9 shrink loop: a requested window larger
+			// than the budget comes back with its middle elided, never empty, and the cursor advances.
+			const content = middleTruncate(chars.slice(offset, offset + limit).join(""), (candidate) => withinBudget(result(candidate)));
+			return output(result(content));
 		},
 	}));
 
@@ -48,11 +52,10 @@ export function registerHistoryTools(pi: ExtensionAPI) {
 		name: "history_search_contents",
 		label: "History search",
 		description: "Case-sensitive literal substring search over durable Pi session history; no semantic search.",
-		parameters: Type.Object({ limit: positiveInteger(), query: Type.String(), recent_first: recentFirst(), tool_namespace: nullableString(), role: Type.Optional(role), tool_name: nullableString(), window_id: nullableString() }, { additionalProperties: false }),
+		parameters: Type.Object({ limit: positiveInteger(), offset: Type.Optional(Type.Integer({ minimum: 0 })), query: Type.String(), recent_first: recentFirst(), tool_namespace: nullableString(), role: Type.Optional(role), tool_name: nullableString(), window_id: nullableString(), max_chars_per_item: positiveInteger() }, { additionalProperties: false }),
 		async execute(_id, params, _signal, _update, ctx) {
-			const items = filteredItems(ctx, params);
-			const matching = items.filter((item) => item.content.includes(params.query));
-			return output({ items: matching.slice(0, params.limit ?? matching.length).map((item) => visibleItem(item)) });
+			const matching = filteredItems(ctx, params).filter((item) => item.content.includes(params.query)).slice(0, params.limit ?? Number.POSITIVE_INFINITY).map((item) => visibleItem(item, params.max_chars_per_item ?? 1200));
+			return output(page(matching, params.offset ?? 0, "items", undefined, (item, fits) => ({ ...item, truncated_content: middleTruncate(item.truncated_content, (candidate) => fits({ ...item, truncated_content: candidate })) })));
 		},
 	}));
 

package/src/history.ts

@@ -123,7 +123,7 @@ export function visibleItem(item: HistoryItem, maxChars = 1200) {
 		role: item.role,
 		tool_namespace: item.toolNamespace ?? null,
 		tool_name: item.toolName ?? null,
-		truncated_content: characters.length > maxChars ? `${characters.slice(0, maxChars).join("")}…` : item.content,
+		truncated_content: characters.length > maxChars ? `${characters.slice(0, Math.max(0, maxChars - 1)).join("")}…` : item.content,
 	};
 }
 
@@ -131,7 +131,7 @@ export function allItems(ctx: SessionReader) {
 	return historyFromSession(ctx).flatMap((window) => window.items);
 }
 
-export function filteredItems(ctx: SessionReader, params: HistoryFilter): HistoryItem[] {
+	export function filteredItems(ctx: SessionReader, params: HistoryFilter): HistoryItem[] {
 	let items = allItems(ctx);
 	if (typeof params.window_id === "string") items = items.filter((item) => item.windowId === params.window_id);
 	if (typeof params.role === "string") items = items.filter((item) => item.role === params.role);

package/src/index.ts

@@ -21,12 +21,12 @@ export default function piContext(pi: ExtensionAPI) {
 	pi.on("session_start", (_event, ctx) => {
 		if (!enabled) return;
 		// The root window has no compaction entry to carry the boot block, so persist
-		// it once as a visible custom message. Reset windows already carry theirs at
+		// it once as a hidden custom message. Reset windows already carry theirs at
 		// position 0 in the compaction summary, so a resumed session adds nothing.
 		const sessionId = ctx.sessionManager.getSessionId();
 		const rootId = `pcw:${sessionId}:root`;
 		if (currentWindowId(ctx) !== rootId || hasWindowMessage(ctx, BOOT_TYPE)) return;
-		pi.sendMessage({ customType: BOOT_TYPE, content: bootBlock(ctx, rootId, undefined, false), display: true }, { triggerTurn: false });
+		pi.sendMessage({ customType: BOOT_TYPE, content: bootBlock(ctx, rootId, undefined, false), display: false }, { triggerTurn: false });
 	});
 
 	pi.registerCommand("pi-context", {

package/src/note-tools.ts

@@ -1,6 +1,6 @@
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { output } from "./tool-output.js";
+import { output, page, middleTruncate, withinBudget } from "./tool-output.js";
 import { nullableString, nullableInteger, positiveInteger } from "./tool-schema.js";
 import { notesFromSession, assertVirtualPath, assertVirtualPrefix, lineRange, localIso, type NoteOperation } from "./notes.js";
 import { NOTE_TYPE, MAX_NOTE_BYTES } from "./protocol.js";
@@ -16,14 +16,15 @@ export function registerNoteTools(pi: ExtensionAPI) {
 		name: "notes_list_files_by_prefix",
 		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(), 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 }),
+		parameters: Type.Object({ prefix: nullableString(), max_results: positiveInteger(), offset: Type.Optional(Type.Integer({ minimum: 0 })), 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();
-			return output({ files: files.slice(0, params.max_results ?? files.length).map(([path, file]) => ({ path, size_bytes: Buffer.byteLength(file.text, "utf8"), created_at: localIso(file.createdAt), updated_at: localIso(file.updatedAt) })) });
+			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.offset ?? 0, "files", params.max_results, (file, fits) => ({ ...file, path: middleTruncate(file.path, (candidate) => fits({ ...file, path: candidate })) })));
 		},
 	}));
 
@@ -36,7 +37,18 @@ export function registerNoteTools(pi: ExtensionAPI) {
 			const path = assertVirtualPath(params.path);
 			const file = notesFromSession(ctx).get(path);
 			if (!file) return output({ error: "note file not found", path });
-			return output({ path, ...lineRange(file.text, params.start_line, params.stop_line), created_at: localIso(file.createdAt), updated_at: localIso(file.updatedAt) });
+			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));
 		},
 	}));
 
@@ -44,14 +56,24 @@ export function registerNoteTools(pi: ExtensionAPI) {
 		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(), query: Type.String(), recent_file_first: Type.Optional(Type.Boolean()), max_files: positiveInteger(), path_prefix: nullableString() }, { additionalProperties: false }),
+		parameters: Type.Object({ max_matches_per_file: positiveInteger(), offset: Type.Optional(Type.Integer({ minimum: 0 })), query: Type.String(), recent_file_first: Type.Optional(Type.Boolean()), max_files: positiveInteger(), path_prefix: nullableString() }, { additionalProperties: false }),
 		async execute(_id, params, _signal, _update, ctx) {
 			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);
-			return output({ files: result.slice(0, params.max_files ?? result.length) });
+			// 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 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)] };
+			};
+			return output(page(result.slice(0, params.max_files ?? result.length), params.offset ?? 0, "files", undefined, fitFile));
 		},
 	}));
 
@@ -59,17 +81,30 @@ export function registerNoteTools(pi: ExtensionAPI) {
 		pi.registerTool(defineTool({
 			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." : "Create or replace a persistent virtual note file.",
-			parameters: Type.Object({ text: Type.String(), path: Type.String() }, { additionalProperties: false }),
+			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.",
+			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
+			// tool runs its calls one at a time, so note read-modify-write cannot race.
+			executionMode: "sequential",
 			async execute(_id, params, _signal, _update, ctx) {
 				const path = assertVirtualPath(params.path);
+				const hasText = params.text !== undefined;
+				const hasStale = params.mark_stale !== undefined;
+				if (!hasText && !hasStale) return output({ error: "provide text, mark_stale, or both", path });
 				const old = notesFromSession(ctx).get(path);
-				const next = op === "append" ? `${old?.text ?? ""}${params.text}` : params.text;
+				if (!hasText && !old) return output({ error: "note file not found", path });
+				const next = hasText ? (op === "append" ? `${old?.text ?? ""}${params.text}` : params.text as string) : old!.text;
 				const bytes = Buffer.byteLength(next, "utf8");
-				if (bytes > MAX_NOTE_BYTES) return output({ error: `note exceeds ${MAX_NOTE_BYTES} UTF-8 bytes`, path, size_bytes: bytes });
+				if (hasText && bytes > MAX_NOTE_BYTES) return output({ error: `note exceeds ${MAX_NOTE_BYTES} UTF-8 bytes`, path, size_bytes: bytes });
 				const now = Date.now();
-				saveNote({ op, path, text: params.text, createdAt: old?.createdAt ?? now, updatedAt: now });
-				return output({ path, size_bytes: bytes, operation: op });
+				const operation: NoteOperation = { op, path, createdAt: old?.createdAt ?? now, updatedAt: now };
+				if (hasText) operation.text = params.text;
+				if (hasStale) operation.stale = params.mark_stale;
+				saveNote(operation);
+				return output({ path, size_bytes: bytes, operation: op, stale: hasStale ? params.mark_stale : false });
 			},
 		}));
 	}

package/src/notes.ts

@@ -1,11 +1,14 @@
 import type { SessionReader } from "./session-reader.js";
 import { MAX_NOTE_BYTES, NOTE_TYPE } from "./protocol.js";
 
-export type NoteFile = { text: string; createdAt: number; updatedAt: number };
+export type NoteFile = { text: string; stale: boolean; createdAt: number; updatedAt: number };
 export type NoteOperation = {
 	op: "write" | "append";
 	path: string;
-	text: string;
+	// Both are optional on the wire so mark-only and explicit-revive operations replay:
+	// at least one of text/stale is present, enforced by the note tools and isNoteOperation.
+	text?: string;
+	stale?: boolean;
 	createdAt: number;
 	updatedAt: number;
 };
@@ -29,7 +32,9 @@ function isNoteOperation(data: unknown): data is NoteOperation {
 	return (
 		(op.op === "write" || op.op === "append") &&
 		typeof op.path === "string" &&
-		typeof op.text === "string" &&
+		(op.text === undefined || typeof op.text === "string") &&
+		(op.stale === undefined || typeof op.stale === "boolean") &&
+		(op.text !== undefined || op.stale !== undefined) &&
 		typeof op.createdAt === "number" && Number.isFinite(new Date(op.createdAt).getTime()) &&
 		typeof op.updatedAt === "number" && Number.isFinite(new Date(op.updatedAt).getTime())
 	);
@@ -46,10 +51,14 @@ export function notesFromSession(ctx: SessionReader): Map<string, NoteFile> {
 			continue;
 		}
 		const previous = files.get(op.path);
-		const text = op.op === "append" ? `${previous?.text ?? ""}${op.text}` : op.text;
-		if (Buffer.byteLength(text, "utf8") <= MAX_NOTE_BYTES) {
-			files.set(op.path, { text, createdAt: previous?.createdAt ?? op.createdAt, updatedAt: op.updatedAt });
-		}
+		const hasText = op.text !== undefined;
+		// A mark-only operation needs an existing note to change; without one it is a no-op.
+		if (!hasText && !previous) continue;
+		const text = hasText ? (op.op === "append" ? `${previous?.text ?? ""}${op.text}` : op.text as string) : previous!.text;
+		if (Buffer.byteLength(text, "utf8") > MAX_NOTE_BYTES) continue;
+		// Carrying text revives unless the call also marks stale; a mark-only op keeps its flag.
+		const stale = hasText ? op.stale ?? false : op.stale ?? previous!.stale;
+		files.set(op.path, { text, stale, createdAt: previous?.createdAt ?? op.createdAt, updatedAt: op.updatedAt });
 	}
 	return files;
 }

package/src/prompts.ts

@@ -15,19 +15,20 @@ function identityBlock(agentName: string, firstWindowId: string, currentWindowId
 }
 
 /**
- * Recent-notes index: up to three most-recent notes. Each note shows its path, line count,
- * UTF-8 byte count and local ISO update time, followed by an indented inline preview: the
- * whole text when it fits in NOTE_PREVIEW_CHARS, otherwise its first NOTE_PREVIEW_HEAD_CHARS
- * and last NOTE_PREVIEW_TAIL_CHARS Unicode characters joined by an explicit ellipsis. The
- * two slices never overlap, so the preview never duplicates head content as tail content.
- * Empty when the session has no notes.
+ * Recent-notes index: up to three most-recent fresh (non-stale) notes. Each note shows its
+ * path, line count, UTF-8 byte count and local ISO update time, followed by an indented inline
+ * preview: the whole text when it fits in NOTE_PREVIEW_CHARS, otherwise its first
+ * NOTE_PREVIEW_HEAD_CHARS and last NOTE_PREVIEW_TAIL_CHARS Unicode characters joined by an
+ * explicit ellipsis. The two slices never overlap, so the preview never duplicates head content
+ * as tail content. Stale notes are excluded entirely; empty when no fresh notes remain.
  */
 function notesIndex(ctx: ExtensionContext): string {
 	const recentNotes = [...notesFromSession(ctx)]
+		.filter(([, file]) => !file.stale)
 		.sort((a, b) => b[1].updatedAt - a[1].updatedAt)
 		.slice(0, 3);
 	if (recentNotes.length === 0) return "";
-	const lines = ["Recent notes at window open (up to 3, most-recent first):"];
+	const lines = [`You find ${recentNotes.length} crumpled note${recentNotes.length === 1 ? "" : "s"} in your pocket (up to 3, most recent first):`];
 	for (const [path, file] of recentNotes) {
 		lines.push(`- ${path} (${file.text.split("\n").length} lines, ${Buffer.byteLength(file.text, "utf8")} UTF-8 bytes, updated ${localIso(file.updatedAt)})`);
 		const chars = Array.from(file.text);
@@ -64,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}\nContext budget is running low: only ${remaining} tokens remained when this reminder was recorded. Persist task state, decisions, open issues, and next steps with notes_write_file, including the window ID and item ID of relevant user requests for history_* lookups; call new_context when ready to continue in a fresh window. Automatic reset does not guarantee another note-taking turn. get_context_remaining reports the current remaining tokens.\n${GUIDANCE_CLOSE_TAG}`;
+	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}`;
 }
 

package/src/protocol.ts

@@ -17,11 +17,11 @@ export const PI_CONTEXT_SETTINGS_KEY = "pi-context";
 export const DEFAULT_RESERVE_TOKENS = 16_384;
 export const DEFAULT_REMINDER_MARGIN_TOKENS = 24_576;
 export const RESET_SUMMARY =
-	"Context window reset: this is a fresh window. The previous conversation is not included and no summary was generated. Notes and durable session history persist across windows.";
-export const NOTE_PREVIEW_HEAD_CHARS = 120;
-export const NOTE_PREVIEW_TAIL_CHARS = 80;
+	"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;
+export const NOTE_PREVIEW_TAIL_CHARS = 240;
 export const NOTE_PREVIEW_CHARS = NOTE_PREVIEW_HEAD_CHARS + NOTE_PREVIEW_TAIL_CHARS;
-export const CONTINUATION = "This is a fresh context window. Recover only the details needed to continue with history_* and notes_*; then continue the task.";
+export const CONTINUATION = "Your memory was just erased. Pull only the details you need from history_* and notes_*, then get back to work.";
 
 /**
  * Static protocol teaching adapted from Codex's token_budget.guidance_message to
@@ -29,15 +29,17 @@ export const CONTINUATION = "This is a fresh context window. Recover only the de
  * it is never re-injected, so it stays cache-stable at the head of the window.
  */
 export const PROTOCOL_BLOCK = `${CONTEXT_WINDOW_PROTOCOL_OPEN_TAG}
-For tasks that may span context windows, use notes_write_file and notes_append_to_file to maintain a concise checkpoint of the goal, decisions, progress, learnings, and next steps. Include the window ID and item ID of every relevant user request you are currently solving, plus important actions and tool calls. The read-only history_* tools can look up details from those references later. Every non-assistant item (user, tool result) has an item ID returned by history_list_items.
+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.
 
-Take incremental notes while you work so you do not lose important information. Use get_context_remaining to check the live remaining token budget for planning. Once the token budget is exhausted you lose access to the current window and continue in a fresh context window; you can recover only through notes_* and history_*. Do not over-run the context window without documentation.
+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.
 
-If a Previous context window id is present in <context_window>, a context reset occurred and this is a fresh window. The old conversation is not automatically included. After a reset, read your note checkpoint and use the read-only history_* tools to recover missing details. When a window ID and item ID are known, prefer history_read_item directly; when they are missing or uncertain, use history_list_items, or history_search_contents to locate the item first.
+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.
+
+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 =
-	"Context budget is almost exhausted. This is the final fallback turn before the window resets automatically. Write task state, decisions, open issues, and next steps with notes_write_file now. Do not start new work; old conversation remains searchable through history_*.";
+	"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_*.";;;;
 

package/src/tool-output.ts

@@ -1,8 +1,79 @@
+export const TOOL_OUTPUT_MAX_BYTES = 32 * 1024;
+
 function json(value: unknown): string {
 	return JSON.stringify(value, null, 2);
 }
 
+/** True when `value` serializes within the same wire budget `output()` enforces. */
+export function withinBudget(value: unknown, budget = TOOL_OUTPUT_MAX_BYTES): boolean {
+	return Buffer.byteLength(json(value), "utf8") <= budget;
+}
+
+/** Marker standing in for characters elided from the middle of an oversized single unit. */
+export function truncationMarker(removedChars: number): string {
+	return `…[truncated ${removedChars} chars]…`;
+}
+
+/**
+ * Middle-truncate `text` until `fits` accepts it, keeping a head and a tail joined by
+ * `truncationMarker`. Codex's `truncate_middle` semantics: when one indivisible unit
+ * (a note line, a single match, a history item) exceeds the wire budget on its own, it is
+ * still returned — visibly truncated — so cursors advance and no page comes back empty.
+ * Returns `text` unchanged when it already fits.
+ */
+export function middleTruncate(text: string, fits: (content: string) => boolean): string {
+	if (fits(text)) return text;
+	const chars = Array.from(text);
+	const build = (kept: number) => {
+		const head = Math.ceil(kept / 2);
+		return chars.slice(0, head).join("") + truncationMarker(chars.length - kept) + chars.slice(chars.length - (kept - head)).join("");
+	};
+	// The serialized size is non-decreasing in `kept` (each kept character adds at least one
+	// byte while the marker loses at most one digit), so a binary search finds the largest
+	// keep count that still fits.
+	let low = 0;
+	let high = chars.length;
+	while (low < high) {
+		const mid = Math.ceil((low + high) / 2);
+		if (fits(build(mid))) low = mid;
+		else high = mid - 1;
+	}
+	return build(low);
+}
+
+/** 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;
+
+/**
+ * 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_offset` advanced past it. Without that fallback
+ * an oversized item would yield an empty page forever: the cursor would keep pointing back
+ * at the same index.
+ */
+export function page<T>(items: T[], offset: number, key: string, limit?: number, truncate?: ItemTruncator<T>) {
+	const end = Math.min(items.length, offset + (limit ?? items.length));
+	const selected: T[] = [];
+	let next = end < items.length ? end : null;
+	for (let index = offset; index < end; index++) {
+		const candidateNext = index + 1 < end || end < items.length ? index + 1 : null;
+		const fits = (list: T[]) => withinBudget({ [key]: list, next_offset: candidateNext });
+		if (!fits([...selected, items[index]])) {
+			if (selected.length === 0 && truncate) {
+				selected.push(truncate(items[index], (candidate) => fits([candidate])));
+				next = candidateNext;
+			} else {
+				next = index;
+			}
+			break;
+		}
+		selected.push(items[index]);
+	}
+	return { [key]: selected, next_offset: next };
+}
+
+/** Encode a result through the common tool result boundary. */
 export function output(value: unknown, details: unknown = value, terminate = false) {
 	return { content: [{ type: "text" as const, text: json(value) }], details, terminate };
 }
-