@astrosheep/pi-context 0.23.1 → 0.25.0

package/docs/reset-lifecycle.md

@@ -1,24 +1,26 @@
 # Reset lifecycle
 
-`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).
+`src/context/reset-lifecycle.ts` owns reset requests, turn-end batching, recovery, and continuation. It is the sole `turn_end` composer: incoming drafts, budget drafts, and reset drafts are ordered here. `src/context/budget.ts` owns the default-path instance-local policy cache, resolves injected policy live, stages guidance/warning drafts, and keeps the final warning text in the budget/protocol path; `src/context/thresholds.ts` only reads settings and derives values, using the shared merge in `src/settings.ts`. `src/index.ts` is the thin public entrypoint; `src/context/runtime.ts` composes the runtime hooks and constructs marker/boot boundaries. `src/notes/notes-snapshot.ts` acquires the notes snapshot, while `src/context/prompts.ts` only renders the explicit boot data and low-budget reminder. Projections and tools 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. |
-| 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`. The originating handler owns and awaits that attempt through its continuation's settlement. |
-| Matching `session_compact` | Confirm boundary, persist window state. Native compaction retains its own scheduling. |
-| Attempt `onComplete` | Consume attempt; for a confirmed boundary when idle with no queued messages, register continuation ownership before sending it. Its nested `agent_settled` settles that owner; a reset requested by the continuation completes its own handoff before releasing its predecessor. |
-| 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. |
+| `wipe_memory` | Record an explicit reset request. Repeated calls in one tool batch deduplicate; the tool returns terminal output. |
+| `turn_end` | The sole composer drains current-window budget drafts after the event entries, then appends reset drafts: one `pi-context/reset-marker` with `{ windowId }`, one hidden boot message with matching `details.windowId`, and the continuation marker; continue the turn through Pi's public queue. |
+| Abort before the boundary | Drop the pending boundary. Never manufacture a continuation for an aborted turn. |
+| Threshold / provider overflow | Request the same marker/boot boundary for the active provider window. Actual overflow/length recovery retries at most once per failure chain; ordinary retryable provider errors stay Pi-owned. |
+| `/wipe-memory` | Wait for idle, append marker and boot through public session APIs, and do not call a model. |
+| `/compact` while enabled | Cancel with an actionable `/wipe-memory` notice so native compaction cannot summarize erased canonical history back into the active window. |
+| Startup / tree / partial append | Repair only a marker followed by an otherwise empty metadata tail; refuse hidden/absent boots once later work exists, leaving `/wipe-memory` as the explicit recovery path. Do not interpret legacy reset-v2 details. |
+| `/pi-context off` | Stop new automatic resets, but retain the boundary of an existing marker. Marked branches still cancel native compaction; a fresh root may use Pi's native semantics. |
 
-The final checkpoint warning is steered earlier from the context hook (`warning.ts`) once per window at reserve+12288 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 budget owner stages the early guidance and final checkpoint warning from active-window usage. The warning is visible in the current provider request, while both drafts are committed only by the lifecycle composer and are discarded on abort, settlement without a `turn_end`, transition, or window mismatch. After the warning, the model either writes its note and calls `wipe_memory`, or runtime recovery requests the same marker/boot boundary. Guidance and warning drafts precede reset drafts so stale reminders cannot be queued into the new window; durable entries remain the authority for redelivery. Their UI notices are emitted at the next turn start or settlement only after the matching reminder is committed in the active window, so aborted requests and retries cannot repeat an uncommitted reminder's notification.
 
-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.
+The turn-end commit is the scheduling boundary: Pi receives the finished tool batch and then the marker/boot drafts as one append operation. Pi owns queue scheduling and deduplication of the next request; the extension does not run a parallel compaction state machine or use a compaction completion callback.
 
-`sendMessage(..., { triggerTurn: true })` starts its run detached from the extension API. The explicit attempt therefore retains an attempt-owned waiter before sending it, and its originating `agent_settled` handler awaits that waiter. The continuation's `agent_settled` releases the waiter without awaiting itself. If that continuation calls `new_context`, its settled handler starts and awaits the next attempt before it releases the prior waiter, forming a bounded reset chain. Failure, cancellation, shutdown, tree navigation, and toggling off release the relevant waiter exactly once.
+Boot construction reads the five note homes into one closed snapshot before rendering the hidden boot. An absent home is empty; a real read failure removes only that home's MAP/pocket rows. The boot retains its identity, reset line, notes-home instructions, and recovery protocol, and includes a concise `notes_list` retry notice. The human receives one incomplete-index notification per boot. This notes failure isolation does not bypass the marker/boot commit, alter raw history, or turn a partial boot into an empty fallback.
 
-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.
+The hidden boot is selected by its durable `details.windowId`, not by timestamp or content equality. The context hook folds only the dropped system prefix before that boot and preserves later prompt patches and messages in order. If the boot is missing, the hook aborts with a safe head and notice rather than sending raw history. Startup/tree repair is deliberately narrow: it appends a boot only when the marker tail is otherwise incomplete metadata; later conversation or an authoritative raw boot causes safe refusal. `/wipe-memory` is the recovery path for that refused branch. A fork/clone creates a new session ID while copying branch entries, so startup refreshes the root boot identity while retaining copied root messages.
 
-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.
+Public APIs let a mixed tool batch finish before the marker/boot boundary. Queued steering/follow-up messages are delivered exactly once in the new window, neither dropped nor replayed. `/tree` navigation remains available, but when either source or destination branch contains a reset marker, Pi's raw summary generator is bypassed: the summary is empty and a notice explains why, preventing erased history from re-entering through a path outside the context hook. With no marker on either branch, native summaries remain unchanged.
+
+Validation uses a reduced set of persisted-data integration tests, isolated lifecycle event tests, and scripted SDK tests running Pi's actual agent loop. Representative cases check reset-window history retention, resumable reads, native-compaction cancellation, mixed-tool completion, steering/follow-up delivery, bounded overflow recovery, and settings authority. Tree-summary suppression no longer has a dedicated retained test. The separate coherence and pagination property suites have been removed; the retained cases do not cover the previous full matrix of branch, cancellation, malformed-input, and pagination edges.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@astrosheep/pi-context",
-  "version": "0.23.1",
+  "version": "0.25.0",
   "type": "module",
-  "description": "Codex-style context windows for Pi: reset-style compaction, durable session history tools, and persistent notes.",
+  "description": "Codex-style context windows for Pi: durable reset windows, session history tools, and persistent notes.",
   "license": "MIT",
   "keywords": [
     "pi-package",
@@ -15,7 +15,7 @@
   },
   "pi": {
     "extensions": [
-      "./src/index.ts"
+      "./dist/extension.js"
     ]
   },
   "files": [
@@ -30,22 +30,23 @@
     "dream": "dist/src/dream/cli.js"
   },
   "scripts": {
-    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json && node -e \"require('node:fs').chmodSync('dist/src/dream/cli.js', 0o755)\"",
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json && node scripts/build-extension.mjs && node -e \"require('node:fs').chmodSync('dist/src/dream/cli.js', 0o755)\"",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "npm run build && node --test dist/test/*.test.js",
     "prepublishOnly": "npm run typecheck",
     "prepack": "npm run build"
   },
   "peerDependencies": {
-    "@earendil-works/pi-agent-core": "*",
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*"
+    "@earendil-works/pi-agent-core": "^0.87.0",
+    "@earendil-works/pi-ai": "^0.87.0",
+    "@earendil-works/pi-coding-agent": "^0.87.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "^0.86.0",
-    "@earendil-works/pi-ai": "^0.86.0",
-    "@earendil-works/pi-coding-agent": "^0.86.0",
+    "@earendil-works/pi-agent-core": "^0.87.0",
+    "@earendil-works/pi-ai": "^0.87.0",
+    "@earendil-works/pi-coding-agent": "^0.87.0",
     "@types/node": "^22.19.19",
+    "esbuild": "^0.28.2",
     "typescript": "^5.9.3"
   },
   "publishConfig": {

package/src/context/budget.ts

@@ -0,0 +1,148 @@
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool, type ExtensionAPI, type ExtensionContext, type SessionBoundaryDraft, type SettingsManager } from "@earendil-works/pi-coding-agent";
+import { GUIDANCE_CLOSE_TAG, GUIDANCE_OPEN_TAG, GUIDANCE_TYPE, WARNING_PROMPT, WARNING_TYPE } from "../protocol.js";
+import { readThresholdSettings, type ResolvedThresholds, type ThresholdSettingsResolution } from "./thresholds.js";
+import { currentWindowId, hasWindowMessage, windowUsage } from "./context-window.js";
+import { tokenBudgetGuidance } from "./prompts.js";
+import { output } from "../tool-output.js";
+
+/** Remaining tokens in the provider's active window, or null without a usable estimate. */
+export function remainingTokens(ctx: Pick<ExtensionContext, "sessionManager" | "getContextUsage" | "model">): number | null {
+	const usage = windowUsage(ctx);
+	return !usage || usage.tokens === null ? null : Math.max(0, usage.contextWindow - usage.tokens);
+}
+
+export function registerBudget(pi: ExtensionAPI, isEnabled: () => boolean, settingsManager?: SettingsManager) {
+	let cachedPolicy: { thresholds: ResolvedThresholds; automatic: boolean } | undefined;
+	const notifiedWarnings = new Set<string>();
+	const resolvePolicy = (ctx: ExtensionContext): ThresholdSettingsResolution => {
+		if (!settingsManager && cachedPolicy) return { ...cachedPolicy, warnings: [] };
+		const resolution = readThresholdSettings(ctx, settingsManager);
+		for (const warning of resolution.warnings) {
+			if (notifiedWarnings.has(warning)) continue;
+			notifiedWarnings.add(warning);
+			ctx.ui.notify(warning, "warning");
+		}
+		if (!settingsManager) cachedPolicy = { thresholds: resolution.thresholds, automatic: resolution.automatic };
+		return resolution;
+	};
+	const thresholdsFor = (ctx: ExtensionContext): ResolvedThresholds => {
+		return resolvePolicy(ctx).thresholds;
+	};
+	const automaticResetEnabled = (ctx: ExtensionContext): boolean => {
+		return resolvePolicy(ctx).automatic;
+	};
+	const resetDue = (ctx: ExtensionContext): boolean => {
+		if (!automaticResetEnabled(ctx)) return false;
+		const usage = windowUsage(ctx);
+		return usage !== undefined && usage.tokens !== null && usage.contextWindow - usage.tokens <= thresholdsFor(ctx).reserve;
+	};
+	const invalidateThresholds = () => { cachedPolicy = undefined; };
+	let pendingGuidance: { windowId: string; content: string } | undefined;
+	let pendingWarning: { windowId: string; content: string } | undefined;
+	let pendingNotices: Array<{ windowId: string; customType: string }> = [];
+	const notifyCommittedReminders = (ctx: ExtensionContext) => {
+		const windowId = currentWindowId(ctx);
+		for (const notice of pendingNotices) {
+			if (notice.windowId !== windowId || !hasWindowMessage(ctx, notice.customType)) continue;
+			ctx.ui.notify(notice.customType === WARNING_TYPE
+				? "pi-context: context budget critical — final checkpoint warning recorded for the model."
+				: "pi-context: context budget low — checkpoint reminder recorded for the model, kept out of the chat view.", "warning");
+		}
+		pendingNotices = [];
+	};
+
+	const clearStaged = () => {
+		pendingGuidance = undefined;
+		pendingWarning = undefined;
+	};
+	const resetForTransition = () => {
+		clearStaged();
+		pendingNotices = [];
+		invalidateThresholds();
+		notifiedWarnings.clear();
+	};
+
+	const consumeTurnEnd = (ctx: ExtensionContext): SessionBoundaryDraft[] => {
+		const staged = [
+			pendingGuidance ? { ...pendingGuidance, customType: GUIDANCE_TYPE } : undefined,
+			pendingWarning ? { ...pendingWarning, customType: WARNING_TYPE } : undefined,
+		];
+		clearStaged();
+		const windowId = currentWindowId(ctx);
+		const drafts = staged.filter((draft): draft is NonNullable<typeof draft> => draft !== undefined && draft.windowId === windowId);
+		pendingNotices = drafts.map(({ windowId, customType }) => ({ windowId, customType }));
+		return drafts.map((draft) => ({
+			type: "custom_message" as const,
+			customType: draft.customType,
+			content: draft.content,
+			display: false,
+		}));
+	};
+
+	pi.on("session_start", (_event, ctx) => { resetForTransition(); thresholdsFor(ctx); });
+	pi.on("session_tree", resetForTransition);
+	pi.on("model_select", resetForTransition);
+	pi.on("session_shutdown", resetForTransition);
+	// A request can fail before Pi emits turn_end. agent_settled is the public
+	// lifecycle point that must discard an uncommitted draft before the next prompt.
+	// UI notices follow committed reminders. Aborted requests can retry their drafts
+	// without showing the same low-budget notification twice.
+	pi.on("turn_start", (_event, ctx) => notifyCommittedReminders(ctx));
+	pi.on("agent_settled", (_event, ctx) => {
+		notifyCommittedReminders(ctx);
+		clearStaged();
+	});
+	pi.on("context", (_event, ctx) => {
+		if (!isEnabled()) return undefined;
+		// The early reminder persists once per window the first time remaining crosses
+		// reserve+margin. It never edits the outgoing request.
+		const remaining = remainingTokens(ctx);
+		if (remaining === null) return undefined;
+		const windowId = currentWindowId(ctx);
+		const { reminder, warning } = thresholdsFor(ctx);
+		if (hasWindowMessage(ctx, WARNING_TYPE) || pendingWarning?.windowId === windowId) return undefined;
+		if (remaining <= warning) {
+			// A not-yet-committed shallow reminder is superseded by the final warning.
+			pendingGuidance = undefined;
+			const content = `${GUIDANCE_OPEN_TAG}\n${WARNING_PROMPT}\n${GUIDANCE_CLOSE_TAG}`;
+			pendingWarning = { windowId, content };
+			const warningMessage = {
+				role: "custom" as const,
+				customType: WARNING_TYPE,
+				content,
+				display: false,
+				timestamp: Date.now(),
+			};
+			return { messages: [..._event.messages, warningMessage] };
+		}
+		if (hasWindowMessage(ctx, GUIDANCE_TYPE) || pendingGuidance?.windowId === windowId) return undefined;
+		if (remaining <= reminder) {
+			// Persist at turn_end, before any reset drafts. A queued sendMessage could
+			// otherwise cross the marker and leak the old window's reminder forward.
+			const left = Math.max(0, remaining - warning);
+			pendingGuidance = { windowId, content: tokenBudgetGuidance(left) };
+		}
+		return undefined;
+	});
+
+	pi.registerTool(defineTool({
+		name: "get_context_remaining",
+		label: "Get context remaining",
+		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) {
+			// 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 = remainingTokens(ctx);
+			return output({ remaining_tokens: remaining === null ? null : Math.max(0, remaining - thresholdsFor(ctx as ExtensionContext).warning) });
+		},
+	}));
+
+	return {
+		automaticResetEnabled,
+		resetDue,
+		consumeTurnEnd,
+		clear: () => { clearStaged(); pendingNotices = []; },
+	};
+}

package/src/context/context-window.ts

@@ -0,0 +1,103 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { getCurrentSystemMessage } from "@earendil-works/pi-ai";
+import { estimateContextTokens } from "@earendil-works/pi-ai/utils/estimate";
+import { convertToLlm, type CustomEntry, type ExtensionContext, type SessionEntry } from "@earendil-works/pi-coding-agent";
+import { BOOT_TYPE, RESET_MARKER_TYPE } from "../protocol.js";
+import type { SessionReader } from "../session-reader.js";
+
+export type WindowMarker = CustomEntry<{ windowId: string }> & { data: { windowId: string } };
+
+export function isWindowMarker(entry: SessionEntry): entry is WindowMarker {
+	return entry.type === "custom" && entry.customType === RESET_MARKER_TYPE &&
+		typeof entry.data === "object" && entry.data !== null &&
+		typeof (entry.data as { windowId?: unknown }).windowId === "string" &&
+		(entry.data as { windowId: string }).windowId.length > 0;
+}
+
+/** Only the active branch can supply a window boundary. */
+export function currentReset(ctx: SessionReader): WindowMarker | undefined {
+	const branch = ctx.sessionManager.getBranch();
+	for (let i = branch.length - 1; i >= 0; i--) {
+		const entry = branch[i];
+		if (entry && isWindowMarker(entry)) return entry;
+	}
+	return undefined;
+}
+
+/** Mint the durable identity of a session's root history window. */
+export function rootWindowId(sessionId: string): string {
+	return `pcw:${sessionId.slice(0, 8)}:root`;
+}
+
+/** Persisted messages in the active window, excluding earlier windows on this branch. */
+export function hasWindowMessage(ctx: SessionReader, customType: string): boolean {
+	const branch = ctx.sessionManager.getBranch();
+	for (let i = branch.length - 1; i >= 0; i--) {
+		const entry = branch[i];
+		if (isWindowMarker(entry)) break;
+		if (entry.type === "custom_message" && entry.customType === customType) return true;
+	}
+	return false;
+}
+
+/** The root or latest durable marker on the active branch. */
+export function currentWindowId(ctx: SessionReader): string {
+	return currentReset(ctx)?.data.windowId ?? rootWindowId(ctx.sessionManager.getSessionId());
+}
+
+function hasWindowId(details: unknown, windowId: string): boolean {
+	return typeof details === "object" && details !== null &&
+		typeof (details as { windowId?: unknown }).windowId === "string" &&
+		(details as { windowId: string }).windowId === windowId;
+}
+
+/** Match a provider-facing boot message, optionally by window identity. */
+export function isWindowBoot(message: AgentMessage, windowId?: string): boolean {
+	return message.role === "custom" && message.customType === BOOT_TYPE && (windowId === undefined || hasWindowId(message.details, windowId));
+}
+
+/**
+ * The durable marker selects a boot message by identity, never by wall-clock time.
+ * The boot is the first conversation message of the window. Folding only its prefix
+ * preserves later prompt/tool patches in place, including their cacheable ordering.
+ */
+export function projectWindow(messages: AgentMessage[], windowId: string): AgentMessage[] {
+	const cut = messages.findIndex((message) => isWindowBoot(message, windowId));
+	if (cut < 0) throw new Error(`Missing boot for context window ${windowId}`);
+	const head = getCurrentSystemMessage(messages.slice(0, cut));
+	const suffix = messages.slice(cut);
+	return head ? [head, ...suffix] : suffix;
+}
+
+/**
+ * Root windows are not reset boundaries. A forked session can copy a root boot whose
+ * details name the source session; refresh that boot in-place in the provider projection
+ * while retaining every user/assistant/tool message from the copied root transcript.
+ */
+export function projectRootWindow(messages: AgentMessage[], windowId: string): AgentMessage[] {
+	const matching = messages.filter((message) => isWindowBoot(message, windowId));
+	if (matching.length === 0) return messages;
+	const activeBoot = matching[matching.length - 1];
+	const firstBoot = messages.findIndex((message) => isWindowBoot(message));
+	const withoutBoots = messages.filter((message) => !isWindowBoot(message));
+	return [...withoutBoots.slice(0, firstBoot), activeBoot, ...withoutBoots.slice(firstBoot)];
+}
+
+/** Usage for the selected window, excluding provider usage recorded before its marker. */
+export function windowUsage(ctx: Pick<ExtensionContext, "sessionManager" | "getContextUsage" | "model">) {
+	const reset = currentReset(ctx);
+	if (!reset) return ctx.getContextUsage();
+	const contextWindow = ctx.model?.contextWindow ?? ctx.getContextUsage()?.contextWindow;
+	if (!contextWindow) return undefined;
+	const windowId = reset.data.windowId;
+	try {
+		const messages: AgentMessage[] = projectWindow(ctx.sessionManager.buildSessionProjection().messages, windowId);
+		const { tokens } = estimateContextTokens(convertToLlm(messages));
+		return { tokens, contextWindow, percent: tokens / contextWindow * 100 };
+	} catch {
+		// A marker can be durable before its boot when a process stops between the two
+		// public writes. Startup/tree repair will append the missing boot; until then the
+		// budget hook must not turn a recoverable partial append into a swallowed error.
+		return undefined;
+	}
+}

package/src/context/prompts.ts

@@ -0,0 +1,111 @@
+import type { NotesHome, NotesSnapshot } from "../notes/notes-snapshot.js";
+import { CONTEXT_WINDOW_OPEN_TAG, CONTEXT_WINDOW_CLOSE_TAG, POCKET_AGENT_LIMIT, POCKET_HUMAN_LIMIT, POCKET_MODEL_LIMIT, POCKET_PROJECT_LIMIT, POCKET_SESSION_LIMIT, RESET_SUMMARY, PROTOCOL_BLOCK, GUIDANCE_OPEN_TAG, GUIDANCE_CLOSE_TAG } from "../protocol.js";
+
+/** Codex-style <context_window> identity block: the resolved agent and model names plus first/current/previous window ids. */
+function identityBlock(agentName: string, modelName: string, firstWindowId: string, currentWindowId: string, previousWindowId?: string): string {
+	const lines = [
+		`Agent name: ${agentName} (brain: ${modelName})`,
+		`First context window id: ${firstWindowId}`,
+		`Current context window id: ${currentWindowId}`,
+	];
+	if (previousWindowId) lines.push(`Previous context window id: ${previousWindowId}`);
+	return `${CONTEXT_WINDOW_OPEN_TAG}\n${lines.join("\n")}\n${CONTEXT_WINDOW_CLOSE_TAG}`;
+}
+
+function relativeTime(timestamp: number, now: number): string {
+	const seconds = Math.trunc((timestamp - now) / 1000);
+	const [unit, size] = ([["d", 86400], ["h", 3600], ["m", 60], ["s", 1]] as const)
+		.find(([unit, size]) => Math.abs(seconds) >= size || unit === "s")!;
+	const amount = `${Math.abs(Math.trunc(seconds / size))}${unit}`;
+	return seconds > 0 ? `in ${amount}` : `${amount} ago`;
+}
+
+function rowsFor(snapshot: NotesSnapshot, scope: NotesHome["scope"]) {
+	return snapshot.homes.get(scope) ?? [];
+}
+
+function notesUnavailableNotice(snapshot: NotesSnapshot): string | undefined {
+	if (snapshot.unavailable.length === 0) return undefined;
+	const homes = snapshot.unavailable.map((home) => home.label).join(", ");
+	const noun = snapshot.unavailable.length === 1 ? "home's index was" : "home indexes were";
+	return `Notes index incomplete: ${homes} ${noun} unavailable during boot; notes_list can retry after recovery.`;
+}
+
+/**
+ * Boot notes index. Map residency ("地图在场"): fresh MAP.md bodies from the human, project,
+ * own-agent, and current-model homes are all injected, broadest first; stale maps are skipped
+ * per home, and the session home is never peeked — a session MAP.md is an ordinary note. The
+ * pocket then lists recent fresh notes under per-home quotas (POCKET_SESSION_LIMIT /
+ * POCKET_PROJECT_LIMIT / POCKET_HUMAN_LIMIT / POCKET_AGENT_LIMIT / POCKET_MODEL_LIMIT),
+ * most-recently-updated first within each home, one metadata line each: address, line count,
+ * UTF-8 byte count, relative update time at window open. Bodies never render
+ * in the pocket; stale notes are excluded; MAP.md itself never takes a pocket seat.
+ */
+function notesIndex(snapshot: NotesSnapshot): string {
+	const sections: string[] = [];
+	// Map residency ("地图在场"): scope-native maps, fresh ones injected broadest-first.
+	// A session MAP.md is an ordinary note, never resident; stale maps skip independently.
+	for (const scope of ["human", "project", "agent", "model"] as const) {
+		const toc = rowsFor(snapshot, scope).find((row) => row.path === "MAP.md");
+		if (toc && !toc.meta.stale) {
+			if (toc.body.length > 0) sections.push(toc.body);
+		}
+	}
+	// listNotes is most-recently-updated first within each home. Per-home quotas keep session
+	// churn from evicting the durable homes; maps never take pocket seats.
+	const recentNotes = [
+		...rowsFor(snapshot, "session").filter((row) => !row.meta.stale && row.path !== "MAP.md").slice(0, POCKET_SESSION_LIMIT),
+		...rowsFor(snapshot, "project").filter((row) => !row.meta.stale && row.path !== "MAP.md").slice(0, POCKET_PROJECT_LIMIT),
+		...rowsFor(snapshot, "human").filter((row) => !row.meta.stale && row.path !== "MAP.md").slice(0, POCKET_HUMAN_LIMIT),
+		...rowsFor(snapshot, "agent").filter((row) => !row.meta.stale && row.path !== "MAP.md").slice(0, POCKET_AGENT_LIMIT),
+		...rowsFor(snapshot, "model").filter((row) => !row.meta.stale && row.path !== "MAP.md").slice(0, POCKET_MODEL_LIMIT),
+	];
+	if (recentNotes.length > 0) {
+		const lines = [`You find ${recentNotes.length} crumpled note${recentNotes.length === 1 ? "" : "s"} in your pocket (by home, most recent first within each: up to ${POCKET_SESSION_LIMIT} from this session, ${POCKET_PROJECT_LIMIT} from this project, ${POCKET_HUMAN_LIMIT} from @human, ${POCKET_AGENT_LIMIT} from your @self home, ${POCKET_MODEL_LIMIT} from the current @model home). A note's content never appears here, so its name has to say what the note is about:`];
+		for (const row of recentNotes) {
+			lines.push(`- ${row.address} (${row.body.split("\n").length} lines, ${row.sizeBytes} UTF-8 bytes, updated ${relativeTime(row.meta.updated_at, snapshot.openedAt)})`);
+		}
+		sections.push(lines.join("\n"));
+	}
+	return sections.join("\n\n");
+}
+
+function notesHomeBlock(): string {
+	return "Notes_* addresses have five homes: bare <vpath> is this session, @project/<vpath> is this project, @human/<vpath> is the human's cross-project home, @self/<vpath> and @agents/<name>/<vpath> are agent homes (current vs named), and @model/<vpath> and @models/<name>/<vpath> are model homes. @self and @model resolve to who is running now; listings always show resolved names. @ means leaving home; there is no cross-home fallback. Anything else after @ — or @ inside a vpath — is a hard error. Any other note is a plain file — use the file tools.";
+}
+
+/**
+ * Render a static, once-per-window boot block from explicit data. This function does not read
+ * notes or call runtime UI APIs; acquisition belongs to loadNotesSnapshot and its caller.
+ */
+export type BootRenderData = {
+	readonly agentName: string;
+	readonly modelName: string;
+	readonly firstWindowId: string;
+	readonly currentWindowId: string;
+	readonly previousWindowId?: string;
+	readonly resetLine: boolean;
+	readonly notes: NotesSnapshot;
+};
+
+export function renderBootBlock(data: BootRenderData): string {
+	const parts: string[] = [];
+	if (data.resetLine) parts.push(RESET_SUMMARY);
+	parts.push(identityBlock(data.agentName, data.modelName, data.firstWindowId, data.currentWindowId, data.previousWindowId));
+	parts.push(notesHomeBlock());
+	const incomplete = notesUnavailableNotice(data.notes);
+	if (incomplete) parts.push(incomplete);
+	const index = notesIndex(data.notes);
+	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.
+ */
+export function tokenBudgetGuidance(remaining: number): string {
+	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 call wipe_memory yourself — anything you do after the checkpoint isn't in it.\n${GUIDANCE_CLOSE_TAG}`;
+}

package/src/context/reset-lifecycle.ts

@@ -0,0 +1,145 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { isContextOverflow, isRecoverableLength } from "@earendil-works/pi-ai";
+import type { AgentBeforeSettleEvent, ExtensionAPI, ExtensionContext, SessionBoundaryDraft } from "@earendil-works/pi-coding-agent";
+import { currentReset } from "./context-window.js";
+
+type BudgetOwner = {
+	automaticResetEnabled: (ctx: ExtensionContext) => boolean;
+	resetDue: (ctx: ExtensionContext) => boolean;
+	consumeTurnEnd: (ctx: ExtensionContext) => SessionBoundaryDraft[];
+	clear: () => void;
+};
+
+type ResetOptions = {
+	isEnabled: () => boolean;
+	budget: BudgetOwner;
+	buildReset: (ctx: ExtensionContext) => SessionBoundaryDraft[];
+};
+
+function isAbort(message: AgentMessage, outcome: string | undefined, ctx: ExtensionContext): boolean {
+	return outcome === "aborted" || (message.role === "assistant" && message.stopReason === "aborted") || ctx.signal?.aborted === true;
+}
+
+function isOverflowLike(message: AgentMessage, ctx: ExtensionContext): boolean {
+	if (message.role !== "assistant") return false;
+	return isContextOverflow(message, ctx.model?.contextWindow) ||
+		(ctx.model !== undefined && isRecoverableLength(message, ctx.model.maxTokens));
+}
+
+/**
+ * Own reset requests at Pi 0.87 boundaries. Persisted windows are custom entries, not
+ * compaction summaries: turn_end commits explicit/threshold resets after a complete tool
+ * batch, while agent_before_settle commits the one bounded overflow recovery after Pi's
+ * native recovery attempt has been cancelled.
+ */
+export function registerResetLifecycle(pi: ExtensionAPI, options: ResetOptions) {
+	let explicitRequested = false;
+	let overflowPending = false;
+	let overflowRecoveryUsed = false;
+	let active = true;
+
+	const clear = () => {
+		explicitRequested = false;
+		overflowPending = false;
+		overflowRecoveryUsed = false;
+	};
+	const resetBoundaryResult = (entries: SessionBoundaryDraft[], ctx: ExtensionContext) => {
+		try {
+			return { entries: [...entries, ...options.buildReset(ctx)], continue: true as const };
+		} catch (error) {
+			ctx.ui.notify(`pi-context: could not build reset (${String(error)}).`, "warning");
+			// The incoming drafts and budget drafts are already valid work from this
+			// boundary. Preserve them, but do not claim a continuation when reset
+			// construction failed.
+			return entries.length > 0 ? { entries } : undefined;
+		}
+	};
+
+	pi.on("turn_end", (event, ctx) => {
+		if (!active) return undefined;
+		const requested = explicitRequested;
+		explicitRequested = false;
+		const aborted = isAbort(event.message, event.outcome, ctx);
+		const stagedBudgetEntries = options.budget.consumeTurnEnd(ctx);
+		// Lifecycle owns whether drafts are acceptable for this turn. Budget only
+		// drains its instance-local staging, so aborts and disabled mode cannot commit it.
+		const budgetEntries = options.isEnabled() && !aborted ? stagedBudgetEntries : [];
+		const entries = [...(event.entries ?? []), ...budgetEntries];
+		if (aborted) {
+			overflowPending = false;
+			overflowRecoveryUsed = false;
+			return entries.length > 0 ? { entries } : undefined;
+		}
+		// Native overflow/length recovery is handled after turn_end through the bounded
+		// settle path; do not turn that failed response into a threshold reset. If Pi has
+		// already queued the next user message, the successful queued turn owns settlement
+		// and must supersede this stale failure.
+		if (isOverflowLike(event.message, ctx)) {
+			const queued = event.context.pendingMessages.length > 0 || ctx.hasPendingMessages();
+			overflowPending = !queued && options.isEnabled() && options.budget.automaticResetEnabled(ctx);
+			return entries.length > 0 ? { entries } : undefined;
+		}
+		// A successful turn, including one drained from Pi's queue, supersedes any
+		// older overflow failure before the settle boundary gets a chance to recover it.
+		if (event.outcome !== "error") {
+			overflowPending = false;
+			overflowRecoveryUsed = false;
+		}
+		if (!options.isEnabled() || event.outcome === "error") return entries.length > 0 ? { entries } : undefined;
+		// The completed response may be the first event whose persisted usage crosses the
+		// reserve, so a final assistant response does not defer the reset until another prompt.
+		const autoThreshold = options.budget.resetDue(ctx);
+		if (!requested && !autoThreshold) return entries.length > 0 ? { entries } : undefined;
+		return resetBoundaryResult(entries, ctx);
+	});
+
+	pi.on("agent_before_settle", (event: AgentBeforeSettleEvent, ctx) => {
+		if (!active || !overflowPending) return undefined;
+		// Pi invokes this boundary before settlement even when an agent_end handler has
+		// queued user input. Let that turn run first; its successful turn_end clears the
+		// stale failure, while another failure leaves the bounded recovery armed.
+		if (event.context.pendingMessages.length > 0 || ctx.hasPendingMessages()) return undefined;
+		overflowPending = false;
+		if (!options.isEnabled() || !options.budget.automaticResetEnabled(ctx) || event.outcome === "aborted" || ctx.signal?.aborted) return undefined;
+		if (overflowRecoveryUsed) return undefined;
+		overflowRecoveryUsed = true;
+		return resetBoundaryResult(event.entries, ctx);
+	});
+
+	pi.on("session_before_compact", (event, ctx) => {
+		if (!active) return undefined;
+		if (event.signal.aborted) return { cancel: true };
+		const markerExists = currentReset(ctx) !== undefined;
+		if (options.isEnabled() || markerExists) {
+			if (event.reason === "manual") {
+				ctx.ui.notify("pi-context: /compact is disabled while context windows are active; use /wipe-memory to start a fresh window.", "warning");
+			}
+			// Native compaction is cancelled here. Threshold resets are decided solely from
+			// completed-turn usage at turn_end, never from canonical pre-request history.
+			return { cancel: true };
+		}
+		return undefined;
+	});
+
+	pi.on("agent_end", (_event, ctx) => {
+		if (ctx.signal?.aborted) clear();
+	});
+	pi.on("agent_settled", () => {
+		// A failed recovery chain is bounded to one reset/retry. Once Pi settles, a later
+		// user prompt starts a new chain; successful continuations clear this earlier.
+		overflowPending = false;
+		overflowRecoveryUsed = false;
+	});
+	pi.on("session_start", () => { clear(); active = true; });
+	pi.on("session_tree", clear);
+	pi.on("session_shutdown", () => { clear(); options.budget.clear(); active = false; });
+
+	return {
+		request() {
+			if (explicitRequested) return "rollover_already_pending";
+			explicitRequested = true;
+			return "rollover_requested";
+		},
+		clear,
+	};
+}