@astrosheep/pi-context 0.14.0 → 0.15.1

package/docs/architecture.md

@@ -11,7 +11,9 @@ pi-context uses Pi's session branch as the durable source of truth. It does not
 | `notes.ts` | Replay note operations, validate paths/timestamps | `SessionReader`; no scheduling or writes |
 | `history-tools.ts`, `note-tools.ts` | Public schemas and tool results; append validated note operations | Pi tool API plus read projections |
 | `budget.ts` | Resolve settings, report usable budget, persist guidance once | Pi settings/context hooks |
-| `prompts.ts` | Render static boot block, note index and reminder | Read projections and protocol text |
+| `thresholds.ts` | Derive the reminder/reserve/warning lines from Pi's reserve plus the pi-context margins | Pi `SettingsManager`, read-only; session-scoped cache |
+| `warning.ts` | Steer the final checkpoint warning once per window | Pi context hook |
+| `prompts.ts` | Render static boot block, note index, reminder and warning | Read projections and protocol text |
 | `reset-lifecycle.ts` | Own reset requests, completion and continuation | Pi lifecycle hooks and injected boundary builder |
 | `protocol.ts` | Persisted entry tags, protocol text and defaults | No imports or effects |
 | `tool-schema.ts`, `tool-output.ts` | Shared wire-schema primitives and JSON result encoding | No session state |
@@ -22,7 +24,7 @@ Dependencies flow from the composition root and tool adapters to projections and
 
 Reset requests are a discriminated union: `idle`, `requested`, or `compacting` with an identified attempt. A request cannot simultaneously be pending and in flight. Each attempt records its originating session, whether it was explicit, and whether a matching boundary completed. Callback identity prevents an old attempt from consuming a newer one. See [reset lifecycle](reset-lifecycle.md).
 
-Fallback allowance is a separate per-window state: `available`, `borrowed`, `ready`, `spent`. It answers whether another note-taking turn may be borrowed, independently of whether an explicit request exists. Success re-arms the allowance; failure does not create a retry loop. Runtime shutdown and tree navigation invalidate outstanding requests.
+Manual, threshold and overflow compactions all build the reset boundary on the spot, idle or streaming: `session_before_compact` returns the reset immediately, never cancels and never takes a model turn, and only an aborted signal cancels. The final checkpoint warning was already steered from the context hook (see [reset lifecycle](reset-lifecycle.md)), so the model had its chance to write a note; what crosses the line now is the wipe itself. `agent_settled` services only explicit `new_context` requests, whose `ctx.compact` route needs the completion callback.
 
 Boot and reminder deduplication inspect messages in the current persisted window. Reloading the extension or the JSONL file therefore does not duplicate either message. Reminder reservation in memory covers Pi's deferred message write; navigation clears that reservation, while persisted branch-local messages remain authoritative. A sibling branch cannot suppress a reminder it never received.
 
@@ -34,6 +36,6 @@ Reset IDs are opaque strings tagged with `reset-v2`; newly minted IDs use `pcw:<
 
 The integration suite uses real SessionManager and SettingsManager instances, including JSONL restoration, branch navigation, Unicode content, malformed note operations and settings precedence. Lifecycle event tests cover duplicate/stale callbacks, native scheduling, disabled state, abort and failed compaction.
 
-Scripted SDK tests execute the real Pi agent loop with no model network request. They cover explicit and fallback reset, rejected compaction, steering and follow-up delivery before reset without replay, consecutive distinct windows, and cancellation followed by a new user prompt. They inspect actual provider contexts and durable entries. They do not establish reliability of an external provider or every possible interleaving between unrelated extensions.
+Scripted SDK tests execute the real Pi agent loop with no model network request. They cover explicit reset, instant automatic reset, rejected compaction, steering and follow-up delivery before reset without replay, consecutive distinct windows, and cancellation followed by a new user prompt. They inspect actual provider contexts and durable entries. They do not establish reliability of an external provider or every possible interleaving between unrelated extensions.
 
 Pi decides compaction eligibility before the boundary hook. A short uncompactable session therefore cannot be force-reset with the public API. Mixed tool batches and queued messages may finish before `agent_settled`; the extension preserves their delivery rather than clearing the queue. Native compaction owns its subsequent scheduling, while extension-requested compaction resumes from `onComplete` after Pi clears compaction state.

package/docs/reset-lifecycle.md

@@ -1,21 +1,22 @@
 # Reset lifecycle
 
-`src/reset-lifecycle.ts` owns requests, fallback allowance, compaction attempts, and continuation. `src/index.ts` composes the features and constructs reset boundaries; projections, tools, budget policy, and prompt rendering have separate modules described in [Architecture](architecture.md).
+`src/reset-lifecycle.ts` owns reset requests, compaction attempts, and continuation. `src/index.ts` composes the features and constructs reset boundaries; projections, tools, budget policy, and prompt rendering have separate modules described in [Architecture](architecture.md).
 
 | Event | Transition / owner |
 | --- | --- |
 | `new_context` | Mark explicit request; repeated calls report already pending. Tool returns terminal output. |
-| Streaming automatic `session_before_compact` | Available → borrowed; send one note-taking steer and cancel this compaction. |
-| Idle automatic or manual compaction | Build reset directly; no borrowed turn. |
-| `agent_end` | Borrowed → ready. Aborted run clears explicit request and spends borrowed allowance. |
-| `agent_settled` | If idle and explicit/ready, create one identified attempt and request `ctx.compact`. |
-| Matching `session_compact` | Confirm boundary, persist window state, re-arm allowance. Native compaction retains its own scheduling. |
+| Manual, threshold or overflow `session_before_compact`, idle or streaming | Build the reset boundary immediately and return it. Never cancel and never take a model turn; an aborted signal returns `{ cancel: true }`. |
+| `agent_end` | No-op for an instant reset. |
+| `agent_settled` | If idle and an explicit request is pending, create one identified attempt and request `ctx.compact`. |
+| Matching `session_compact` | Confirm boundary, persist window state. Native compaction retains its own scheduling. |
 | Attempt `onComplete` | Consume attempt; send continuation only for a confirmed boundary when idle with no queued messages. |
 | Attempt `onError` or synchronous throw | Clear attempt/request, warn, retain history. No automatic retry loop. |
 | Shutdown / start / tree / toggle off | Invalidate outstanding attempt. Identity checks reject callbacks from older attempts. |
 
-The completion callback is the scheduling boundary: `session_compact` fires before Pi clears manual compaction state. Sending a prompt inside that hook is too early. Both explicit and borrowed-fallback resets use the manual `ctx.compact` route and therefore need the same completion logic. Native compaction/retry already has a caller responsible for subsequent work.
+The final checkpoint warning is steered earlier from the context hook (`warning.ts`) once per window at reserve+8192 tokens remaining. After it, the model either ends the window itself with `new_context` or rides into Pi's automatic compaction, which resets on the spot with no turn.
+
+The completion callback is the scheduling boundary: `session_compact` fires before Pi clears manual compaction state. Sending a prompt inside that hook is too early. An explicit reset uses the manual `ctx.compact` route and therefore needs this completion logic; an automatic compaction is already the reset and resumes through Pi's own caller.
 
 Public APIs cannot guarantee immediate reset inside mixed tool batches or before queued steering/follow-up messages finish. `terminate` ends the tool-followup path; `agent_settled` remains the safe point to request compaction. The scheduler does not manipulate user queues. Pi also determines compaction eligibility before the extension hook; an uncompactable session produces a warning and waits for a new prompt.
 
-Validation is split into persisted-data integration tests, isolated lifecycle event tests, and scripted SDK tests running Pi's actual agent loop. The SDK tests cover explicit success, fallback success, and core compaction rejection followed by a user prompt. Lifecycle tests cover callback races and queue guards without pretending to exercise provider/network behavior.
+Validation is split into persisted-data integration tests, isolated lifecycle event tests, and scripted SDK tests running Pi's actual agent loop. The SDK tests cover explicit success, instant automatic reset, and core compaction rejection followed by a user prompt. Lifecycle tests cover callback races and queue guards without pretending to exercise provider/network behavior.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/pi-context",
-  "version": "0.14.0",
+  "version": "0.15.1",
   "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

@@ -1,113 +1,49 @@
 import { Type } from "@earendil-works/pi-ai";
-import { defineTool, SettingsManager, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { PI_CONTEXT_SETTINGS_KEY, DEFAULT_RESERVE_TOKENS, DEFAULT_REMINDER_MARGIN_TOKENS, GUIDANCE_TYPE, FALLBACK_TYPE } from "./protocol.js";
+import { defineTool, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { GUIDANCE_TYPE, WARNING_TYPE } from "./protocol.js";
+import { thresholdsFor, resetThresholds, deriveThresholds, mergePiContextSettings } from "./thresholds.js";
 import { currentWindowId, hasWindowMessage } from "./history.js";
 import { tokenBudgetGuidance } from "./prompts.js";
 import { output } from "./tool-output.js";
 
-type ResolvedThresholds = { reminder: number; reserve: 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 reminder threshold from Pi's reserve plus the pi-context
- * reminder margin. An invalid margin degrades to the default and reports one warning.
- * The borrowed fallback turn has no token threshold of its own: it is driven by Pi's
- * automatic threshold/overflow compaction request (see session_before_compact).
- */
-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 }, warnings };
-}
+export { deriveThresholds, mergePiContextSettings } from "./thresholds.js";
 
 export function registerBudget(pi: ExtensionAPI, isEnabled: () => boolean) {
 	let guidancePersistedInWindow: string | undefined;
-	let thresholds: ResolvedThresholds | undefined;
-
-	/**
-	 * Resolve the thresholds for this session from Pi's compaction reserve plus the
-	 * settings.json "pi-context" margins. The file-backed read is cached until the next
-	 * session_start; invalid configuration degrades per offending key with one warning
-	 * and never throws during session operation.
-	 */
-	const resolveThresholds = (ctx: ExtensionContext): ResolvedThresholds => {
-		if (thresholds) return thresholds;
-		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");
-			thresholds = derived.thresholds;
-		} catch (error) {
-			ctx.ui.notify(`pi-context: could not read settings; using defaults (${String(error)}).`, "warning");
-			thresholds = { reminder: DEFAULT_RESERVE_TOKENS + DEFAULT_REMINDER_MARGIN_TOKENS, reserve: DEFAULT_RESERVE_TOKENS };
-		}
-		return thresholds;
-	};
 
-	pi.on("session_start", (_event, ctx) => { thresholds = undefined; guidancePersistedInWindow = undefined; resolveThresholds(ctx); });
-	pi.on("session_tree", () => { guidancePersistedInWindow = undefined; });
+	pi.on("session_start", (_event, ctx) => { guidancePersistedInWindow = undefined; resetThresholds(); thresholdsFor(ctx); });
+	pi.on("session_tree", () => { guidancePersistedInWindow = undefined; resetThresholds(); });
 	pi.on("context", (_event, ctx) => {
-		if (!isEnabled() || hasWindowMessage(ctx, FALLBACK_TYPE)) return undefined;
-		// This hook does exactly one thing: persist the once-per-window low-budget
-		// reminder the first time remaining context crosses the reminder threshold.
-		// It never injects messages into the request.
+		if (!isEnabled() || hasWindowMessage(ctx, GUIDANCE_TYPE)) return undefined;
+		// The early reminder persists once per window the first time remaining crosses
+		// reserve+margin. It never edits the outgoing request.
 		const usage = ctx.getContextUsage();
-		if (usage && usage.tokens !== null) {
-			const remaining = Math.max(0, usage.contextWindow - usage.tokens);
-			const windowId = currentWindowId(ctx);
-			const { reminder, reserve } = resolveThresholds(ctx);
-			if (remaining <= reminder && guidancePersistedInWindow !== windowId && !hasWindowMessage(ctx, GUIDANCE_TYPE)) {
-				guidancePersistedInWindow = windowId;
-				// Persist once per window — no transient copy. A transient bridge would
-				// cover the crossing request, but history would record the reminder after
-				// that request's assistant reply, so across the boundary the model would
-				// meet the same text twice at shifted positions. The reminder is an early
-				// warning, not a per-request instruction: arriving from the next request
-				// 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.
-				// 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");
-			}
+		if (!usage || usage.tokens === null) return undefined;
+		const remaining = Math.max(0, usage.contextWindow - usage.tokens);
+		const windowId = currentWindowId(ctx);
+		const { reminder, reserve, warning } = thresholdsFor(ctx);
+		// The final warning owns the deep band: when it has fired (or is due now),
+		// the shallow reminder would only repeat the same instruction closer to
+		// the wipe, at a worse position. See warning.ts.
+		if (remaining <= warning || hasWindowMessage(ctx, WARNING_TYPE)) return undefined;
+		if (remaining <= reminder && guidancePersistedInWindow !== windowId && !hasWindowMessage(ctx, GUIDANCE_TYPE)) {
+			guidancePersistedInWindow = windowId;
+			// Persist once per window — no transient copy. A transient bridge would
+			// cover the crossing request, but history would record the reminder after
+			// that request's assistant reply, so across the boundary the model would
+			// meet the same text twice at shifted positions. The reminder is an early
+			// warning, not a per-request instruction: arriving from the next request
+			// 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.
+			// 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.
+			// The model-facing count ends at the warning line: what lies below is the
+			// runway, invisible by design. The human's notify keeps the honest count.
+			const left = Math.max(0, remaining - warning);
+			pi.sendMessage({ customType: GUIDANCE_TYPE, content: tokenBudgetGuidance(left), display: false }, { triggerTurn: false });
+			ctx.ui.notify(`pi-context: context budget low (${Math.max(0, remaining - reserve)} tokens before reserve) — checkpoint reminder recorded for the model, kept out of the chat view.`, "warning");
 		}
 		return undefined;
 	});
@@ -115,11 +51,13 @@ export function registerBudget(pi: ExtensionAPI, isEnabled: () => boolean) {
 	pi.registerTool(defineTool({
 		name: "get_context_remaining",
 		label: "Get context remaining",
-		description: "Return estimated context tokens available before the compaction reserve, clamped to zero; null when Pi cannot estimate usage.",
+		description: "Return estimated context tokens left before your memory is wiped; null when Pi cannot estimate usage.",
 		parameters: Type.Object({}, { additionalProperties: false }),
 		async execute(_id, _params, _signal, _update, ctx) {
 			const usage = ctx.getContextUsage();
-			const remaining = usage?.tokens === null || usage === undefined ? null : Math.max(0, usage.contextWindow - usage.tokens - resolveThresholds(ctx).reserve);
+			// The countdown the model sees ends at the warning line (reserve + runway);
+			// the runway below it is overdraft the model never sees. See protocol.ts.
+			const remaining = usage?.tokens === null || usage === undefined ? null : Math.max(0, usage.contextWindow - usage.tokens - thresholdsFor(ctx as ExtensionContext).warning);
 			return output({ remaining_tokens: remaining });
 		},
 	}));

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, page, middleTruncate, prefixFit, earliestMatchOffsetChars, readCharacterWindow } from "./tool-output.js";
+import { output, outputRaw, page, middleTruncate, prefixFit, earliestMatchOffsetChars, readCharacterWindow, characterWindowHeader, withinTextBudget } from "./tool-output.js";
 import { positiveInteger, recentFirst, nullableString, role, cursor, searchQuery, searchQueries } from "./tool-schema.js";
 import { historyFromSession, filteredItems, visibleItem, allItems } from "./history.js";
 
@@ -57,12 +57,16 @@ export function registerHistoryTools(pi: ExtensionAPI) {
 	pi.registerTool(defineTool({
 		name: "history_read_item",
 		label: "History read item",
-		description: "Read a bounded character range from one session item. Each response delivers the longest contiguous prefix of the requested window that fits the wire budget. next_offset_chars is exactly offset_chars plus the delivered code-point count and is null only once the item ends: follow it to reconstruct the item exactly. A negative offset_chars counts back from the item's end, and the response always echoes the resolved absolute offset. Offsets and counts are code points (an emoji or CJK character counts as one).",
+		description: "Read a bounded character range from one session item. Each response delivers the longest contiguous prefix of the requested window that fits the wire budget: follow the resume cursor to reconstruct the item exactly. A negative offset_chars counts back from the item's end. Offsets and counts are code points (an emoji or CJK character counts as one). The response is the raw item text behind a one-line [bracketed] header naming the item, the resolved offset, the delivered char range, and the resume cursor (continue at offset_chars=N, or end).",
 		parameters: Type.Object({ item_id: Type.String(), offset_chars: Type.Optional(Type.Integer({ description: "Code-point offset to start from. 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." })), 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" });
-			return output(readCharacterWindow(item.content, params.offset_chars, params.limit_chars, (window) => ({ window_id: item.windowId, item_id: item.itemId, ...window })));
+			const limit_chars = Math.min(params.limit_chars ?? 12000, 50000);
+			return readCharacterWindow(item.content, params.offset_chars, params.limit_chars, (window) => {
+				const { content, ...cursor } = window;
+				return outputRaw(characterWindowHeader(`${item.windowId} · item ${item.itemId}`, window), content, { window_id: item.windowId, item_id: item.itemId, ...cursor, limit_chars });
+			}, (result) => withinTextBudget(result.content[0].text));
 		},
 	}));
 

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 } 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, 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,6 +1,6 @@
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { output, page, middleTruncate, prefixFit, earliestMatchOffsetChars, readCharacterWindow } from "./tool-output.js";
+import { output, outputRaw, page, middleTruncate, prefixFit, earliestMatchOffsetChars, readCharacterWindow, characterWindowHeader, withinTextBudget } 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";
@@ -48,7 +48,7 @@ export function registerNoteTools(pi: ExtensionAPI) {
 	pi.registerTool(defineTool({
 		name: "notes_read_file",
 		label: "Notes read file",
-		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.",
+		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 limit_chars caps the window (default 12000, max 50000). Each response delivers the longest fitting prefix of that window: concatenate pages in order to reconstruct the note. The response is the raw note text behind a one-line [bracketed] header naming the file, the resolved offset, the delivered char range, and the resume cursor (continue at offset_chars=N, or 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);
@@ -56,7 +56,11 @@ export function registerNoteTools(pi: ExtensionAPI) {
 			if (!file) return output({ error: "note file not found", path });
 			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 })));
+			const limit_chars = Math.min(params.limit_chars ?? 12000, 50000);
+			return readCharacterWindow(file.text, params.offset_chars, params.limit_chars, (window) => {
+				const { content, ...cursor } = window;
+				return outputRaw(characterWindowHeader(path, window, ` · created ${created_at} · updated ${updated_at}`), content, { path, ...cursor, limit_chars, created_at, updated_at });
+			}, (result) => withinTextBudget(result.content[0].text));
 		},
 	}));
 

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. If this checkpoint replaces an older note, close it in the same sitting with mark_stale: true — stale notes leave the boot index but stay readable and searchable. 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,7 +2,7 @@ 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";
@@ -20,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;
@@ -35,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 =
+	"Your memory is about to be erased. Write the note. NOW. If it already exists, append instead: 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. Do not continue any task. Then call new_context IMMEDIATELY — anything not in the note dies with the window.";
 

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

@@ -9,6 +9,11 @@ export function withinBudget(value: unknown, budget = TOOL_OUTPUT_MAX_BYTES): bo
 	return Buffer.byteLength(json(value), "utf8") <= budget;
 }
 
+/** True when `text` fits the wire budget verbatim, for raw payloads with no JSON encoding. */
+export function withinTextBudget(text: string, budget = TOOL_OUTPUT_MAX_BYTES): boolean {
+	return Buffer.byteLength(text, "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]…`;
@@ -89,9 +94,11 @@ export type CharacterWindow = {
  * `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.
+ * a candidate window, and `measure` decides whether that response fits the wire budget (JSON
+ * serialization by default; raw-text renders pass a verbatim byte measure), so the budget is
+ * always 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 {
+export function readCharacterWindow<T>(text: string, offsetChars: number | undefined, limitChars: number | undefined, render: (window: CharacterWindow) => T, measure: (rendered: T) => boolean = withinBudget): T {
 	const chars = Array.from(text);
 	const requested = offsetChars ?? 0;
 	const resolved = requested < 0 ? Math.max(0, chars.length + requested) : Math.max(0, requested);
@@ -100,10 +107,23 @@ export function readCharacterWindow<T>(text: string, offsetChars: number | undef
 		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))));
+	const content = prefixFit(windowChars.join(""), (candidate) => measure(render(build(candidate))));
 	return render(build(content));
 }
 
+/**
+ * One-line bracketed header preceding a raw character-window payload: the identity, the
+ * delivered char range, and either the resume cursor or `end`. `tail` appends extra
+ * metadata (notes add their timestamps) inside the same brackets.
+ */
+export function characterWindowHeader(identity: string, window: CharacterWindow, tail = ""): string {
+	// The range end is offset + delivered count, never `total_chars`: a read resolved past the
+	// end delivers zero characters there, and the header must not render an inverted range.
+	const end = window.offset_chars + Array.from(window.content).length;
+	const resume = window.next_offset_chars === null ? "end" : `continue at offset_chars=${window.next_offset_chars}`;
+	return `[${identity} · chars ${window.offset_chars}-${end} of ${window.total_chars} · ${resume}${tail}]`;
+}
+
 /**
  * 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.
@@ -125,7 +145,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.
  */
@@ -150,7 +170,20 @@ export function page<T>(items: T[], cursor: number, key: string, limit?: number,
 	return { [key]: selected, next_cursor: next };
 }
 
-/** Encode a result through the common tool result boundary. */
-export function output(value: unknown, details: unknown = value, terminate = false) {
+/**
+ * Encode a structured result through the common tool result boundary. `details` is slim
+ * metadata for logs/UI (pi convention: never a second copy of the payload) and stays
+ * undefined unless the tool has metadata worth persisting.
+ */
+export function output(value: unknown, details?: unknown, terminate = false) {
 	return { content: [{ type: "text" as const, text: json(value) }], details, terminate };
 }
+
+/**
+ * Encode a prose payload as raw text: a one-line bracketed metadata header, then the payload
+ * verbatim. The model reads the note or history item itself instead of a JSON envelope;
+ * `details` carries the slim metadata object and never duplicates the payload.
+ */
+export function outputRaw(header: string, content: string, details: unknown, terminate = false) {
+	return { content: [{ type: "text" as const, text: `${header}\n${content}` }], details, terminate };
+}

package/src/tool-schema.ts

@@ -4,7 +4,7 @@ export const positiveInteger = () => Type.Optional(Type.Integer({ minimum: 1 }))
 export const cursor = () => Type.Optional(Type.Integer({ minimum: 0, description: "Continuation cursor: pass the previous next_cursor back unchanged, with the same filters and ordering. Omit to start. next_cursor is null only when the set is exhausted." }));
 export const recentFirst = () => Type.Optional(Type.Boolean({ description: "Return newest-first. Only an explicit false returns oldest-first. Defaults to true." }));
 /** Role filter. `developer` is the known author for this extension's own custom entries. */
-export const role = Type.Union([Type.Literal("user"), Type.Literal("assistant"), Type.Literal("tool"), Type.Literal("system"), Type.Literal("developer"), Type.Null()], { description: "Filter by the entry's known author: user/assistant/tool from the conversation, system for native Pi compaction summaries, developer for entries this extension authored (its boot, guidance, fallback, and continuation messages, its reset-window compaction summaries, and any other pi-context/* entry)." });
+export const role = Type.Union([Type.Literal("user"), Type.Literal("assistant"), Type.Literal("tool"), Type.Literal("system"), Type.Literal("developer"), Type.Null()], { description: "Filter by the entry's known author: user/assistant/tool from the conversation, system for native Pi compaction summaries, developer for entries this extension authored (its boot, guidance, warning, and continuation messages, its reset-window compaction summaries, and any other pi-context/* entry)." });
 
 /** Search query parameter: one literal, or several literals combined with OR. */
 export const searchQuery = () => Type.Union([Type.String(), Type.Array(Type.String(), { minItems: 1 })]);

package/src/warning.ts

@@ -0,0 +1,46 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { WARNING_TYPE, GUIDANCE_OPEN_TAG, GUIDANCE_CLOSE_TAG, WARNING_PROMPT } from "./protocol.js";
+import { thresholdsFor, resetThresholds, type ResolvedThresholds } from "./thresholds.js";
+import { hasWindowMessage, currentWindowId } from "./history.js";
+
+/**
+ * The final checkpoint warning, steered to the model once per window. Like the early
+ * reminder, the steer text is model-facing only (display: false); the human learns
+ * about it from the warning-level notify, not from a chat-visible message.
+ */
+
+/** Trigger: does the steer fire at this remaining-token count? Pure. */
+export function warningDue(remaining: number, thresholds: ResolvedThresholds): boolean {
+	return remaining <= thresholds.warning;
+}
+
+/** Delivery: what happens when it fires. */
+export function steerWarning(pi: ExtensionAPI, ctx: ExtensionContext, thresholds: ResolvedThresholds, remaining: number): void {
+	pi.sendMessage({ customType: WARNING_TYPE, content: `${GUIDANCE_OPEN_TAG}\n${WARNING_PROMPT}\n${GUIDANCE_CLOSE_TAG}`, display: false }, { triggerTurn: true });
+	ctx.ui.notify(`pi-context: context budget critical (${Math.max(0, remaining - thresholds.reserve)} tokens before reserve) — final checkpoint warning steered to the model.`, "warning");
+}
+
+/** Registration: once-per-window guard plus trigger+delivery on the context hook. */
+export function registerWarning(pi: ExtensionAPI, isEnabled: () => boolean): void {
+	let firedInWindow: string | undefined;
+	// Threshold resolution is owned by budget.ts; this module only consumes the shared
+	// cache (lazily on the context hook) so session_start never warns twice.
+	pi.on("session_start", () => { firedInWindow = undefined; });
+	pi.on("session_tree", () => { firedInWindow = undefined; resetThresholds(); });
+	pi.on("context", (_event, ctx) => {
+		const windowId = currentWindowId(ctx);
+		if (!isEnabled() || firedInWindow === windowId || hasWindowMessage(ctx, WARNING_TYPE)) return undefined;
+		const usage = ctx.getContextUsage();
+		if (!usage || usage.tokens === null) return undefined;
+		const remaining = Math.max(0, usage.contextWindow - usage.tokens);
+		const thresholds = thresholdsFor(ctx);
+		if (!warningDue(remaining, thresholds)) return undefined;
+		firedInWindow = windowId;
+		// The steer reaches the model at the next sampling step with at most the runway
+		// of invisible budget left. After it, the model decides for itself: end the
+		// window, or ride it into Pi's automatic compaction, which resets on the spot
+		// with no turn (see reset-lifecycle).
+		steerWarning(pi, ctx, thresholds, remaining);
+		return undefined;
+	});
+}