@astrosheep/pi-context 0.6.1 → 0.8.0

package/README.md

@@ -19,13 +19,41 @@ 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 tool turn to end, compacts with a short deterministic reset message (old conversation is excluded from the new provider context but stays in the session), then sends exactly one hidden continuation turn.
-- **`<context_window>` hint** — persisted as a visible custom message at session start and after each window reset (Codex-style: written once into history instead of re-injected per request). It carries the agent name, first/current/previous window IDs, and the 5 most recently updated notes. Within a window the note list goes stale, exactly like Codex's steady-state world-state diffing.
-- **Low-budget guidance** — when remaining context first drops to 16,000 tokens or below, a `<context_window_guidance>` reminder is **persisted once per window** into history (TUI-visible, no extra turn; `sendMessage` safely defers to end of turn mid-stream). The in-flight request additionally gets one transient tail copy so the model sees it immediately. Text is static and appended, so the provider prefix cache survives. The exact remaining figure is one `get_context_remaining` call away. Note: Pi's built-in auto-compaction fires when remaining context falls below `reserveTokens` (default 16,384), so raise the reminder threshold above your `reserveTokens` or the reminder never precedes compaction.
-- **Auto-compact fallback** — Codex `auto_compact_fallback_prompt` parity, adapted to Pi's trigger points. On the first proactive `threshold` compaction in a window (post-run, agent still streaming), the extension cancels compaction once and steers in a note-taking turn ("write durable state with `notes_write_file` now"); the next threshold trigger performs the real reset and auto-continues, like Codex's mid-turn rollover. The pre-prompt threshold path (idle — cancelling would race the user prompt) and `overflow` recovery (cancelling would abandon Pi's one-shot retry) reset immediately without a fallback turn.
-- **Runtime toggle** — `/pi-context off` disables hint injection, guidance, fallback turns, 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.
+- **`<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 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 count 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.
+- **Direct automatic reset** — every automatic compaction immediately uses the same reset handler. No cancellation to obtain a fallback turn, no input interception or replay, and no special idle/streaming scheduling. The reminder asks the model to write notes early; if it misses that opportunity, old history remains searchable. Pi owns automatic continuation, queued inputs, and overflow retry.
+- **Graceful fallback** — when estimated remaining context reaches the fallback threshold (by default **24,576 tokens**: Pi's default 16,384 `reserveTokens` plus an 8,192 fallback margin; see [Reminder timing](#reminder-timing)), the extension inserts one final note-taking instruction once per window. Before a fresh user turn, it is persisted through `before_agent_start`; after a running tool turn (only while the agent is still streaming), it is sent at the ordinary `turn_end` boundary with `triggerTurn: true`, which Pi routes to `agent.steer()`: the message is drained after the turn end and injected before the next LLM call, extending the current run by one note-taking turn while a queued user prompt (follow-up) waits until the agent would stop. It never copies, handles, or replays user input and never cancels Pi's compaction. Pi's automatic compaction still performs the reset afterward.
+- **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.
 - **Notes tools** — persistent, session-scoped virtual files that survive window resets.
 
+## Reminder timing
+
+Reminder and fallback thresholds derive from Pi's compaction reserve plus margins configured in `settings.json` under the top-level `pi-context` key:
+
+```json
+{
+  "compaction": { "reserveTokens": 16384 },
+  "pi-context": {
+    "reminderMarginTokens": 24576,
+    "fallbackMarginTokens": 8192
+  }
+}
+```
+
+Both margins are measured in **remaining context tokens** added on top of Pi's `compaction.reserveTokens`:
+
+- `fallback = reserveTokens + fallbackMarginTokens` (default margin `8192`)
+- `reminder = reserveTokens + reminderMarginTokens` (default margin `24576`)
+
+Put the key in the global settings (`~/.pi/agent/settings.json`) or the project settings (`<cwd>/.pi/settings.json`); project values win per key, mirroring Pi's own settings merge. With Pi's default `reserveTokens: 16384` the defaults give reminder `40960` and fallback `24576`: the fallback sits one note-taking turn above Pi's reset line, and the reminder leaves another 16,384 tokens of working room above the fallback, no matter how you set `reserveTokens`.
+
+Pi's `reserveTokens` and the `pi-context` margins are re-read from disk at every `session_start` and cached for that session. Invalid values — a margin that is not a positive integer, or a `reminderMarginTokens` that does not clear `fallbackMarginTokens` — are ignored per offending key with one TUI warning naming the key and the default used instead; session handling never throws. If `fallbackMarginTokens` still leaves the reminder below the fallback after the reminder's default is applied, that key degrades too, with its own warning.
+
+This is a file-backed read through Pi's public `SettingsManager`. It sees committed `settings.json` only: SDK-level ephemeral `applyOverrides()` calls and the unreleased `compaction.modelOverrides` are not seen by this extension.
+
+The extension does not change Pi settings or reserve additional context. Large tool outputs or user inputs can jump over one or both reminders; overflow recovery still resets immediately rather than forcing a doomed extra turn. For small context windows, tune the margins (or Pi's reserve) to fit the model.
+
 ## Tools
 
 The nine Codex History/Notes actions are flattened because Pi tools have one global name space:
@@ -42,7 +70,7 @@ The nine Codex History/Notes actions are flattened because Pi tools have one glo
 | `notes.append_to_file` | `notes_append_to_file` |
 | `notes.write_file` | `notes_write_file` |
 
-`history_*` reads the current branch's actual Pi session entries, including entries hidden by earlier compaction. Window IDs are stable `pcw:<session-id>:root` or `pcw:<session-id>:<compaction-entry-id>` identifiers; item IDs are the persisted Pi entry IDs. No transcript copy or volatile archive is maintained.
+`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.
 
 `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. Writes are capped at 1,000,000 UTF-8 bytes.
 
@@ -55,7 +83,9 @@ Two extra controls compose Pi public APIs:
 
 ## Reset behavior and limits
 
-On `session_before_compact`, the extension appends a persistent custom reset marker through public `pi.appendEntry`, reads that real marker ID from the readonly session manager, and returns it as `firstKeptEntryId`. Pi's `buildContextEntries()` then keeps the compaction envelope plus that custom marker; custom markers are excluded from LLM context. Thus the subsequent provider context contains the short reset result and hidden continuation, not old conversation messages. The old entries remain only in the session tree for `history_*`.
+On `session_before_compact`, the extension appends a persistent custom reset marker through public `pi.appendEntry`, reads that real marker ID from the readonly session manager, and returns it as `firstKeptEntryId`. Pi's `buildContextEntries()` then keeps the compaction envelope plus that custom marker; custom markers are excluded from LLM context. Thus the subsequent provider context contains the boot block summary and the marker, not old conversation messages. The boot summary also carries the extension-minted window id in its `details.windowId`, so the fresh window names itself with an id Pi could not have supplied at bake time. Only an explicit `new_context` adds a hidden continuation; automatic resets and user `/compact` keep Pi's native scheduling. The old entries remain only in the session tree for `history_*`.
+
+Pi's built-in “compacted into the following summary” envelope is left intact. Its content explicitly says: “Context window reset. No summary was generated. Retrieve prior details through history_* and notes_*.” 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.
 
@@ -68,4 +98,4 @@ npm run typecheck
 npm test
 ```
 
-The integration harness uses the installed Pi `SessionManager`, including an on-disk JSONL reload. It verifies note persistence/Unicode/path rules, provider context exclusion after the real `firstKeptEntryId` boundary while history remains searchable, completed tool-result boundary placement, one continuation only, and cancellation/failure/no-double-retry behavior. It uses no model or network call.
+The integration harness uses the installed Pi `SessionManager` and `SettingsManager` (global and project settings fixtures in temp directories, so the real `~/.pi` is never touched), including an on-disk JSONL reload. It verifies note persistence/Unicode/path rules, the boot block contents and extension-minted window ids on reset and root paths, that the `context` hook never injects, provider context exclusion after the real `firstKeptEntryId` boundary while history remains searchable, completed tool-result boundary placement, settings-derived threshold resolution and margin validation, one early reminder and one final fallback per window, one continuation only, and cancellation/failure/no-double-retry behavior. It uses no model or network call.

package/package.json

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

package/src/index.ts

@@ -1,26 +1,50 @@
+import { randomUUID } from "node:crypto";
 import { Type, type TextContent } from "@earendil-works/pi-ai";
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
-import { defineTool, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { defineTool, SettingsManager, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 const STATE_TYPE = "pi-context/state";
 const NOTE_TYPE = "pi-context/note";
-const HINT_TYPE = "pi-context/hint";
+const BOOT_TYPE = "pi-context/boot";
 const GUIDANCE_TYPE = "pi-context/guidance";
 const FALLBACK_TYPE = "pi-context/fallback";
 const RESET_MARKER_TYPE = "pi-context/reset-marker";
 const CONTINUATION_TYPE = "pi-context/continuation";
+const RESET_V2 = "reset-v2";
 const MAX_NOTE_BYTES = 1_000_000;
 const CONTEXT_WINDOW_OPEN_TAG = "<context_window>";
 const CONTEXT_WINDOW_CLOSE_TAG = "</context_window>";
+const CONTEXT_WINDOW_PROTOCOL_OPEN_TAG = "<context_window_protocol>";
+const CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG = "</context_window_protocol>";
 const GUIDANCE_OPEN_TAG = "<context_window_guidance>";
 const GUIDANCE_CLOSE_TAG = "</context_window_guidance>";
-const REMINDER_THRESHOLD_TOKENS = 16_000;
-const RESET_SUMMARY = "Context window reset. Prior session entries remain available only through the pi-context history tools.";
+const PI_CONTEXT_SETTINGS_KEY = "pi-context";
+const DEFAULT_RESERVE_TOKENS = 16_384;
+const DEFAULT_REMINDER_MARGIN_TOKENS = 24_576;
+const DEFAULT_FALLBACK_MARGIN_TOKENS = 8_192;
+const RESET_SUMMARY = "Context window reset. No summary was generated. Retrieve prior details through history_* and notes_*.";
 const CONTINUATION = "This is a fresh context window. Recover only the details needed to continue with history_* and notes_*; then continue the task.";
 
-/** Codex auto_compact_fallback_prompt parity: one note-taking chance before an automatic reset. */
+/**
+ * Static protocol teaching adapted from Codex's token_budget.guidance_message to
+ * pi-context's tool names. It lives once per window in the persisted boot block;
+ * it is never re-injected, so it stays cache-stable at the head of the window.
+ */
+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.
+
+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.
+
+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.
+
+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}`;
+
 const FALLBACK_PROMPT =
-	"Context limit reached. This window is about to be reset. Write durable state with notes_write_file now: task state, decisions, open issues, next steps. Do not start new work. After this turn the window resets automatically; old conversation stays searchable through the history_* tools.";
+	"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_*.";
+
+type ResolvedThresholds = { reminder: number; fallback: number };
+type PiContextMargins = { reminderMarginTokens: unknown; fallbackMarginTokens: unknown };
 
 type NoteFile = { text: string; createdAt: number; updatedAt: number };
 type NoteOperation = {
@@ -93,6 +117,19 @@ function toolInfo(message: AgentMessage): Pick<HistoryItem, "toolName" | "toolNa
 	return { toolName: message.toolName, toolNamespace: underscore > 0 ? message.toolName.slice(0, underscore) : undefined };
 }
 
+/** The extension-owned window id baked onto a reset-v2 compaction entry, if present. */
+function resetV2WindowId(details: unknown): string | undefined {
+	if (typeof details !== "object" || details === null) return undefined;
+	const candidate = details as { piContext?: unknown; windowId?: unknown };
+	if (candidate.piContext !== RESET_V2 || typeof candidate.windowId !== "string") return undefined;
+	return candidate.windowId;
+}
+
+/** A compaction entry's window id: the extension-minted id for reset-v2, else Pi's entry id. */
+function windowIdOf(sessionId: string, entry: { id: string; details?: unknown }): string {
+	return resetV2WindowId(entry.details) ?? `pcw:${sessionId}:${entry.id}`;
+}
+
 /** Build durable, on-demand history directly from every entry on the current session branch. */
 export function historyFromSession(ctx: ExtensionContext): HistoryWindow[] {
 	const sessionId = ctx.sessionManager.getSessionId();
@@ -100,7 +137,7 @@ export function historyFromSession(ctx: ExtensionContext): HistoryWindow[] {
 	const windows = [window];
 	for (const entry of ctx.sessionManager.getBranch()) {
 		if (entry.type === "compaction") {
-			window = { windowId: `pcw:${sessionId}:${entry.id}`, createdAt: entry.timestamp, items: [] };
+			window = { windowId: windowIdOf(sessionId, entry), createdAt: entry.timestamp, items: [] };
 			windows.push(window);
 			window.items.push({
 				windowId: window.windowId,
@@ -208,36 +245,54 @@ export function notesFromSession(ctx: ExtensionContext): Map<string, NoteFile> {
 	return files;
 }
 
-/** Codex-equivalent <context_window> hint: window identity plus recent-notes entry points. */
-export function contextWindowHint(ctx: ExtensionContext): string {
-	const windows = historyFromSession(ctx);
-	const first = windows[0];
-	const current = windows[windows.length - 1];
-	const previous = windows.length > 1 ? windows[windows.length - 2] : undefined;
+/** Codex-style <context_window> identity block: agent name and first/current/previous window ids only. */
+function identityBlock(agentName: string, firstWindowId: string, currentWindowId: string, previousWindowId?: string): string {
 	const lines = [
-		`Agent name: ${ctx.sessionManager.getSessionName() ?? "root"}`,
-		`First context window id: ${first?.windowId ?? "unknown"}`,
-		`Current context window id: ${current?.windowId ?? "unknown"}`,
+		`Agent name: ${agentName}`,
+		`First context window id: ${firstWindowId}`,
+		`Current context window id: ${currentWindowId}`,
 	];
-	if (previous) lines.push(`Previous context window id: ${previous.windowId}`);
+	if (previousWindowId) lines.push(`Previous context window id: ${previousWindowId}`);
+	return `${CONTEXT_WINDOW_OPEN_TAG}\n${lines.join("\n")}\n${CONTEXT_WINDOW_CLOSE_TAG}`;
+}
+
+/** Recent-notes index with the existing wording; empty when the session has no notes. */
+function notesIndex(ctx: ExtensionContext): string {
 	const recentNotes = [...notesFromSession(ctx)]
 		.sort((a, b) => b[1].updatedAt - a[1].updatedAt)
 		.slice(0, 5);
-	if (recentNotes.length > 0) {
-		lines.push("Recent notes (up to 5, 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)`);
-		}
+	if (recentNotes.length === 0) return "";
+	const lines = ["Recent notes (up to 5, 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)`);
 	}
-	return `${CONTEXT_WINDOW_OPEN_TAG}\n${lines.join("\n")}\n${CONTEXT_WINDOW_CLOSE_TAG}`;
+	return lines.join("\n");
 }
 
 /**
- * Codex-equivalent low-budget reminder. Static by design: a stale token count in a
- * persisted message would mislead later turns; the exact figure is one tool call away.
+ * Assemble the static, once-per-window boot block: the reset line for resets, the
+ * <context_window> identity block, the recent-notes index at window-open time, and
+ * the <context_window_protocol> teaching block. Nothing here is re-injected, so the
+ * head of the window stays cache-stable.
  */
-function tokenBudgetGuidance(): string {
-	return `${GUIDANCE_OPEN_TAG}\nContext budget is at or below ${REMINDER_THRESHOLD_TOKENS} tokens remaining. Persist durable state with notes_write_file, then call new_context before the window closes. get_context_remaining reports the exact figure.\n${GUIDANCE_CLOSE_TAG}`;
+function bootBlock(ctx: ExtensionContext, currentId: string, previousId: string | undefined, resetLine: boolean): string {
+	const firstId = historyFromSession(ctx)[0]?.windowId ?? currentId;
+	const parts: string[] = [];
+	if (resetLine) parts.push(RESET_SUMMARY);
+	parts.push(identityBlock(ctx.sessionManager.getSessionName() ?? "root", firstId, currentId, previousId));
+	const index = notesIndex(ctx);
+	if (index) parts.push(index);
+	parts.push(PROTOCOL_BLOCK);
+	return parts.join("\n\n");
+}
+
+/**
+ * Codex-equivalent low-budget reminder. The measured remaining count is frozen into
+ * the text at the crossing that fires it, so each persisted copy is a snapshot true
+ * at write time; get_context_remaining remains the live source for the current figure.
+ */
+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}`;
 }
 
 /** Cheap current-window lookup: scan the branch tail for the latest compaction entry. */
@@ -246,7 +301,7 @@ function currentWindowId(ctx: ExtensionContext): string {
 	const branch = ctx.sessionManager.getBranch();
 	for (let i = branch.length - 1; i >= 0; i--) {
 		const entry = branch[i];
-		if (entry?.type === "compaction") return `pcw:${sessionId}:${entry.id}`;
+		if (entry?.type === "compaction") return windowIdOf(sessionId, entry);
 	}
 	return `pcw:${sessionId}:root`;
 }
@@ -269,21 +324,113 @@ const nullableInteger = () => Type.Optional(Type.Union([Type.Integer(), Type.Nul
 const positiveInteger = () => Type.Optional(Type.Integer({ minimum: 1 }));
 const role = Type.Union([Type.Literal("user"), Type.Literal("assistant"), Type.Literal("tool"), Type.Literal("system"), Type.Literal("developer"), Type.Null()]);
 
+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, fallbackMarginTokens: merged.fallbackMarginTokens };
+}
+
+/** 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 effective thresholds from Pi's reserve plus the pi-context
+ * margins. Invalid margins and a reminder that does not clear the fallback degrade
+ * to defaults per offending key and report one warning each.
+ */
+export function deriveThresholds(reserveTokens: number, margins: PiContextMargins): { thresholds: ResolvedThresholds; warnings: string[] } {
+	const warnings: string[] = [];
+	const reminderKey = `${PI_CONTEXT_SETTINGS_KEY}.reminderMarginTokens`;
+	const fallbackKey = `${PI_CONTEXT_SETTINGS_KEY}.fallbackMarginTokens`;
+	const parsedReminder = validMargin(margins.reminderMarginTokens);
+	const parsedFallback = validMargin(margins.fallbackMarginTokens);
+
+	let reminderMargin: number;
+	if (margins.reminderMarginTokens === undefined) reminderMargin = DEFAULT_REMINDER_MARGIN_TOKENS;
+	else if (parsedReminder === undefined) {
+		warnings.push(`pi-context: ${reminderKey} must be a positive integer; using default ${DEFAULT_REMINDER_MARGIN_TOKENS}.`);
+		reminderMargin = DEFAULT_REMINDER_MARGIN_TOKENS;
+	} else reminderMargin = parsedReminder;
+
+	let fallbackMargin: number;
+	if (margins.fallbackMarginTokens === undefined) fallbackMargin = DEFAULT_FALLBACK_MARGIN_TOKENS;
+	else if (parsedFallback === undefined) {
+		warnings.push(`pi-context: ${fallbackKey} must be a positive integer; using default ${DEFAULT_FALLBACK_MARGIN_TOKENS}.`);
+		fallbackMargin = DEFAULT_FALLBACK_MARGIN_TOKENS;
+	} else fallbackMargin = parsedFallback;
+
+	if (reminderMargin <= fallbackMargin) {
+		warnings.push(`pi-context: ${reminderKey} must exceed ${fallbackKey}; using default ${DEFAULT_REMINDER_MARGIN_TOKENS}.`);
+		reminderMargin = DEFAULT_REMINDER_MARGIN_TOKENS;
+		if (reminderMargin <= fallbackMargin) {
+			warnings.push(`pi-context: ${fallbackKey} must be below ${reminderKey}; using default ${DEFAULT_FALLBACK_MARGIN_TOKENS}.`);
+			fallbackMargin = DEFAULT_FALLBACK_MARGIN_TOKENS;
+		}
+	}
+
+	return { thresholds: { reminder: reserveTokens + reminderMargin, fallback: reserveTokens + fallbackMargin }, warnings };
+}
+
 export default function piContext(pi: ExtensionAPI) {
-	let rollover: "idle" | "requested" | "compacting" | "continued" = "idle";
+	let rollover: "idle" | "requested" | "compacting" = "idle";
 	let enabled = true;
 	let guidancePersistedInWindow: string | undefined;
-	let fallbackSentInWindow: string | undefined;
-	let continueAfterFallback = false;
-
-	/** Persist the context_window hint as a visible message (lands in history and the TUI), Codex-style. */
-	const persistHint = (ctx: ExtensionContext) => {
-		pi.sendMessage({ customType: HINT_TYPE, content: contextWindowHint(ctx), display: true }, { triggerTurn: false });
+	let fallbackPersistedInWindow: string | undefined;
+	let handledCompactionId: 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,
+				fallback: DEFAULT_RESERVE_TOKENS + DEFAULT_FALLBACK_MARGIN_TOKENS,
+			};
+		}
+		return thresholds;
 	};
 
 	pi.on("session_start", (_event, ctx) => {
+		// Re-read settings.json on every session start; the resolved values are cached for the session.
+		thresholds = undefined;
+		resolveThresholds(ctx);
 		if (!enabled) return;
-		persistHint(ctx);
+		// 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
+		// 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) return;
+		pi.sendMessage({ customType: BOOT_TYPE, content: bootBlock(ctx, rootId, undefined, false), display: true }, { triggerTurn: false });
 	});
 	const saveNote = (op: NoteOperation) => {
 		// pi.appendEntry writes a custom SessionManager entry. Custom entries are persistent but excluded from LLM context.
@@ -292,7 +439,7 @@ export default function piContext(pi: ExtensionAPI) {
 	};
 
 	pi.registerCommand("pi-context", {
-		description: "Toggle pi-context: context_window hint, low-budget guidance, and reset-style compaction",
+		description: "Toggle pi-context: context_window boot block, low-budget guidance, and reset-style compaction",
 		getArgumentCompletions: (prefix) =>
 			["on", "off"].filter((a) => a.startsWith(prefix)).map((a) => ({ value: a, label: a })),
 		handler: async (args, cmdCtx) => {
@@ -420,28 +567,72 @@ export default function piContext(pi: ExtensionAPI) {
 		}));
 	}
 
-	pi.on("context", (event, ctx) => {
+	const fallbackGuidance = () => `${GUIDANCE_OPEN_TAG}\n${FALLBACK_PROMPT}\n${GUIDANCE_CLOSE_TAG}`;
+
+	pi.on("context", (_event, ctx) => {
+		if (!enabled) 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.
+		const usage = ctx.getContextUsage();
+		if (usage && usage.tokens !== null) {
+			const remaining = Math.max(0, usage.contextWindow - usage.tokens);
+			const windowId = currentWindowId(ctx);
+			if (remaining <= resolveThresholds(ctx).reminder && guidancePersistedInWindow !== windowId) {
+				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.
+				pi.sendMessage({ customType: GUIDANCE_TYPE, content: tokenBudgetGuidance(remaining), display: true }, { triggerTurn: false });
+			}
+		}
+		return undefined;
+	});
+
+	// Graceful fallback without intercepting user input: before a fresh prompt, if
+	// remaining context has entered the buffer between this threshold and Pi's
+	// reserve line, append a persistent user-level final-call instruction. Pi then
+	// runs that turn with the user's queued prompt still present and runs its own
+	// automatic compaction before the following prompt. Overflow is excluded: Pi
+	// already owns its one-shot compact-and-retry recovery.
+	pi.on("before_agent_start", (event, ctx) => {
 		if (!enabled) return undefined;
 		const usage = ctx.getContextUsage();
 		if (!usage || usage.tokens === null) return undefined;
 		const remaining = Math.max(0, usage.contextWindow - usage.tokens);
-		if (remaining > REMINDER_THRESHOLD_TOKENS) return undefined;
+		if (remaining > resolveThresholds(ctx).fallback) return undefined;
+		const windowId = currentWindowId(ctx);
+		if (fallbackPersistedInWindow === windowId) return undefined;
+		fallbackPersistedInWindow = windowId;
+		return { message: { customType: FALLBACK_TYPE, content: FALLBACK_PROMPT, display: true } };
+	});
+
+	pi.on("turn_end", (_event, ctx) => {
+		if (!enabled) return undefined;
+		// Streaming case only: while the agent is streaming, triggerTurn:true routes
+		// to agent.steer() — Pi drains the steering queue after this turn_end and
+		// injects the message before the next LLM call, extending the current run by
+		// one note-taking turn. A queued user prompt (follow-up) drains only when the
+		// agent would stop, so it is processed after the notes turn. (Defensive: in
+		// v0.85.1 turn_end always fires inside an active run, so isIdle is never
+		// true here; the idle pre-prompt case is owned by before_agent_start above.)
+		if (ctx.isIdle()) return undefined;
+		const usage = ctx.getContextUsage();
+		if (!usage || usage.tokens === null) return;
+		const remaining = Math.max(0, usage.contextWindow - usage.tokens);
+		if (remaining > resolveThresholds(ctx).fallback) return;
 		const windowId = currentWindowId(ctx);
-		if (guidancePersistedInWindow === windowId) return undefined;
-		guidancePersistedInWindow = windowId;
-		// Persist once per window, like the hint. sendMessage defers safely to end of
-		// turn while streaming (sendCustomMessage queues instead of splitting a tool
-		// call/result pair), so from the next turn on the guidance lives in history
-		// and the TUI. A transient tail copy covers the in-flight request; it is
-		// appended, static, and one-shot, so the cached prefix survives.
-		const text = tokenBudgetGuidance();
-		pi.sendMessage({ customType: GUIDANCE_TYPE, content: text, display: true }, { triggerTurn: false });
-		const guidance = {
-			role: "user" as const,
-			content: [{ type: "text" as const, text }],
-			timestamp: Date.now(),
-		};
-		return { messages: [...event.messages, guidance] };
+		if (fallbackPersistedInWindow === windowId) return;
+		if (rollover !== "idle") return;
+		fallbackPersistedInWindow = windowId;
+		// The steered message reaches the model before the pending user input and no
+		// input text/images are copied or replayed.
+		pi.sendMessage({ customType: FALLBACK_TYPE, content: fallbackGuidance(), display: true }, { triggerTurn: true });
 	});
 
 	pi.registerTool(defineTool({
@@ -482,27 +673,30 @@ export default function piContext(pi: ExtensionAPI) {
 		if (!enabled) return undefined; // Default Pi compaction applies; keepRecentTokens is honored again.
 		// Never let an aborted or failed custom reset fall through to Pi's default summary.
 		if (event.signal.aborted) return { cancel: true };
-		// Codex auto_compact_fallback_prompt parity, adapted to Pi's trigger points:
-		// - threshold, post-run (agent still streaming): cancel once per window and steer a
-		//   note-taking turn in; _runAutoCompaction then returns hasQueuedMessages() and the
-		//   post-run loop delivers it via agent.continue(). Safe, intended path.
-		// - threshold, pre-prompt (idle): cancelling still sends the user prompt with an
-		//   over-threshold context, and sendMessage would race _runAgentPrompt. Reset instead.
-		// - overflow: never cancel; that would abandon Pi's one-shot compact-and-retry recovery.
-		if (event.reason === "threshold" && !ctx.isIdle()) {
-			const windowId = currentWindowId(ctx);
-			if (fallbackSentInWindow !== windowId) {
-				fallbackSentInWindow = windowId;
-				continueAfterFallback = true;
-				pi.sendMessage({ customType: FALLBACK_TYPE, content: FALLBACK_PROMPT, display: true }, { triggerTurn: true });
-				return { cancel: true };
-			}
-		}
+		// Every compaction uses the same reset path. Never cancel to borrow a
+		// note-taking turn: Pi owns user input, queued work, and overflow recovery.
 		try {
+			const sessionId = ctx.sessionManager.getSessionId();
+			// Pi mints the compaction entry id only after this hook returns, so the
+			// extension mints and owns the window id now, avoiding collisions with any
+			// existing entry id, and bakes it into the summary and details.
+			let minted = randomUUID().slice(0, 8);
+			while (ctx.sessionManager.getEntry(minted)) minted = randomUUID().slice(0, 8);
+			const windowId = `pcw:${sessionId}:${minted}`;
+			const windows = historyFromSession(ctx);
+			const previousId = windows[windows.length - 1]?.windowId ?? `pcw:${sessionId}:root`;
+			// The reset marker stays as firstKeptEntryId; it no longer names the window.
 			pi.appendEntry(RESET_MARKER_TYPE, { version: 1, reason: event.reason, requested: rollover === "compacting" });
 			const markerId = ctx.sessionManager.getLeafId();
 			if (!markerId) return { cancel: true };
-			return { compaction: { summary: RESET_SUMMARY, firstKeptEntryId: markerId, tokensBefore: event.preparation.tokensBefore, details: { piContext: "reset-v1" } } };
+			return {
+				compaction: {
+					summary: bootBlock(ctx, windowId, previousId, true),
+					firstKeptEntryId: markerId,
+					tokensBefore: event.preparation.tokensBefore,
+					details: { piContext: RESET_V2, windowId },
+				},
+			};
 		} catch {
 			return { cancel: true };
 		}
@@ -510,20 +704,21 @@ export default function piContext(pi: ExtensionAPI) {
 
 	pi.on("session_compact", (event, ctx) => {
 		if (!enabled) {
-			continueAfterFallback = false;
+			rollover = "idle";
 			return;
 		}
-		// Overflow retry is already continued once by Pi core. Sending another turn would duplicate it.
-		if (event.willRetry) return;
-		// Continue after our own rollover, and after a fallback reset (Codex rolls over
-		// mid-turn and keeps going). A user's manual /compact gets no continuation.
-		const shouldContinue = rollover === "compacting" || continueAfterFallback;
-		continueAfterFallback = false;
-		if (rollover === "compacting") rollover = "continued";
-		if (!shouldContinue) return;
-		pi.appendEntry(STATE_TYPE, { version: 1, lastResetEntryId: event.compactionEntry.id });
-		persistHint(ctx);
-		pi.sendMessage({ customType: CONTINUATION_TYPE, content: CONTINUATION, display: false }, { triggerTurn: true });
+		const entry = ctx.sessionManager.getEntry(event.compactionEntry.id);
+		if (entry?.type !== "compaction" || resetV2WindowId(entry.details) === undefined) return;
+		if (handledCompactionId === entry.id) return;
+		handledCompactionId = entry.id;
+		// Only explicit new_context needs an extension-owned continuation.
+		// Automatic resets/retries and user /compact keep Pi's native scheduling.
+		const shouldContinue = rollover === "compacting" && !event.willRetry;
+		rollover = "idle";
+		pi.appendEntry(STATE_TYPE, { version: 1, lastResetEntryId: entry.id });
+		if (shouldContinue) {
+			pi.sendMessage({ customType: CONTINUATION_TYPE, content: CONTINUATION, display: false }, { triggerTurn: true });
+		}
 	});
 
 	pi.on("session_compact_failed", () => {
@@ -531,4 +726,4 @@ export default function piContext(pi: ExtensionAPI) {
 	});
 }
 
-export const internal = { MAX_NOTE_BYTES, NOTE_TYPE, HINT_TYPE, GUIDANCE_TYPE, FALLBACK_TYPE, FALLBACK_PROMPT, RESET_MARKER_TYPE, RESET_SUMMARY, CONTINUATION, CONTEXT_WINDOW_OPEN_TAG, GUIDANCE_OPEN_TAG, REMINDER_THRESHOLD_TOKENS, lineRange, assertVirtualPath };
+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, DEFAULT_FALLBACK_MARGIN_TOKENS, deriveThresholds, mergePiContextSettings, lineRange, assertVirtualPath };