@astrosheep/pi-context 0.24.0 → 0.25.1

package/src/context/prompts.ts

@@ -0,0 +1,108 @@
+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, 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(", ");
+	return `Notes index incomplete: index for ${homes} 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 prefix, most recent first within each: up to ${POCKET_SESSION_LIMIT} from this session, ${POCKET_PROJECT_LIMIT} from @project, ${POCKET_HUMAN_LIMIT} from @human, ${POCKET_AGENT_LIMIT} from @self, ${POCKET_MODEL_LIMIT} from @model). 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 "Note addresses: bare <vpath> is this session; @project/<vpath> is this project; @human/<vpath> is the human's cross-project notes; @self/<vpath> is your own (current agent); @model/<vpath> is the current model's. @self and @model resolve to who is running now. Any other @ prefix, or @ inside a vpath, is a hard error; there is no fallback across prefixes. Anything not matching these 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 notes: NotesSnapshot;
+};
+
+export function renderBootBlock(data: BootRenderData): string {
+	const parts: string[] = [];
+	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-artifacts.ts

@@ -0,0 +1,101 @@
+import { randomUUID } from "node:crypto";
+import type { ExtensionAPI, ExtensionContext, SessionBoundaryDraft, SessionEntry } from "@earendil-works/pi-coding-agent";
+import { BOOT_TYPE, CONTINUATION, CONTINUATION_TYPE, RESET_MARKER_TYPE } from "../protocol.js";
+import { currentWindowId, isWindowBootEntry, isWindowMarker, previousWindowId, type WindowMarker } from "./context-window.js";
+import { buildBootMessage, sendBoot, type IncompleteNotesNotifier } from "./boot.js";
+
+export type ResetTailState = { readonly boot: boolean; readonly continuation: boolean };
+
+/** Match the hidden continuation entry that carries the one reset message. */
+export function isWindowContinuationEntry(entry: SessionEntry): boolean {
+	return entry.type === "custom_message" && entry.customType === CONTINUATION_TYPE;
+}
+
+/** The single continuation sender: the only reset prose persisted for a window. */
+export function sendContinuation(pi: ExtensionAPI): void {
+	pi.sendMessage(
+		{ customType: CONTINUATION_TYPE, content: CONTINUATION, display: false },
+		{ triggerTurn: false },
+	);
+}
+
+/**
+ * The closed, ordered reset shape: marker, matching boot, continuation. This is the one
+ * source of the reset message and the one place that mints the new window identity.
+ */
+export function buildResetDrafts(ctx: ExtensionContext, notifyIncompleteNotes?: IncompleteNotesNotifier) {
+	const sessionPrefix = ctx.sessionManager.getSessionId().slice(0, 8);
+	const usedWindowIds = new Set(
+		ctx.sessionManager.getBranch().filter(isWindowMarker).map((entry) => entry.data.windowId),
+	);
+	let windowId: string;
+	do {
+		windowId = `pcw:${sessionPrefix}:${randomUUID().slice(0, 8)}`;
+	} while (usedWindowIds.has(windowId));
+	const boot = buildBootMessage(ctx, windowId, currentWindowId(ctx), notifyIncompleteNotes);
+	return [
+		{ type: "custom", customType: RESET_MARKER_TYPE, data: { windowId } },
+		{ type: "custom_message", customType: BOOT_TYPE, content: boot.content, display: false, details: { windowId } },
+		{ type: "custom_message", customType: CONTINUATION_TYPE, content: CONTINUATION, display: false },
+	] satisfies [SessionBoundaryDraft, SessionBoundaryDraft, SessionBoundaryDraft];
+}
+
+/** Persist the marker and send both hidden reset messages; returns the new window id. */
+export function persistManualReset(pi: ExtensionAPI, ctx: ExtensionContext, notifyIncompleteNotes?: IncompleteNotesNotifier): string {
+	const [marker, boot, continuation] = buildResetDrafts(ctx, notifyIncompleteNotes);
+	pi.appendEntry(marker.customType, marker.data);
+	pi.sendMessage(
+		{ customType: boot.customType, content: boot.content, display: boot.display, details: boot.details },
+		{ triggerTurn: false },
+	);
+	pi.sendMessage(
+		{ customType: continuation.customType, content: continuation.content, display: continuation.display },
+		{ triggerTurn: false },
+	);
+	return boot.details.windowId;
+}
+
+/**
+ * Inspect the persisted tail of a reset marker. It reports which reset messages are present
+ * only while the tail stays repairable: metadata may follow the marker, but real conversation,
+ * a foreign message, a later marker, or a misordered/duplicate reset artifact refuses repair.
+ */
+export function inspectResetTail(ctx: ExtensionContext, markerId: string, windowId: string): ResetTailState | undefined {
+	const branch = ctx.sessionManager.getBranch();
+	const markerIndex = branch.findIndex((entry) => entry.id === markerId);
+	if (markerIndex < 0) return undefined;
+	let boot = false;
+	let continuation = false;
+	for (const entry of branch.slice(markerIndex + 1)) {
+		if (isWindowBootEntry(entry, windowId)) {
+			// The boot is unique and must precede the continuation; a repeat or a late
+			// boot would move the provider boundary or misorder the reset shape.
+			if (boot || continuation) return undefined;
+			boot = true;
+			continue;
+		}
+		if (isWindowContinuationEntry(entry)) {
+			if (continuation || !boot) return undefined;
+			continuation = true;
+			continue;
+		}
+		if (isWindowMarker(entry) || entry.type === "message" || entry.type === "custom_message" || entry.type === "compaction" || entry.type === "branch_summary") {
+			return undefined;
+		}
+	}
+	return { boot, continuation };
+}
+
+/** True once the marker's tail already carries its boot and continuation in a valid order. */
+export function resetTailCommitted(ctx: ExtensionContext, markerId: string, windowId: string): boolean {
+	const tail = inspectResetTail(ctx, markerId, windowId);
+	return tail?.boot === true && tail.continuation === true;
+}
+
+/** Emit only the reset artifacts an incomplete tail is missing, in the closed order. */
+export function repairResetTail(pi: ExtensionAPI, ctx: ExtensionContext, marker: WindowMarker, notifyIncompleteNotes?: IncompleteNotesNotifier): void {
+	const tail = inspectResetTail(ctx, marker.id, marker.data.windowId);
+	if (!tail || (tail.boot && tail.continuation)) return;
+	if (!tail.boot) sendBoot(pi, buildBootMessage(ctx, marker.data.windowId, previousWindowId(ctx, marker.id), notifyIncompleteNotes));
+	if (!tail.continuation) sendContinuation(pi);
+}

package/src/context/reset-lifecycle.ts

@@ -0,0 +1,272 @@
+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));
+}
+
+/**
+ * Reset-control state. The concern is split into two independent, explicitly typed axes so
+ * that no combination of independently combinable lifecycle booleans is legal by accident:
+ *
+ * - `request` is the single pending explicit wipe request ("none" or "explicit"). Repeated
+ *   requests deduplicate while one is pending.
+ * - `overflow` is the bounded provider-overflow recovery chain:
+ *   - "idle"          no overflow failure is pending; recovery is available for a later chain.
+ *   - "pending"       an overflow failure is pending; recovery is still available.
+ *   - "pending-spent" an overflow failure is pending, but recovery was already spent this chain.
+ *   - "spent"         recovery was spent and the failure is no longer pending.
+ *
+ * All eight combinations of the two axes are reachable (a request may arrive while an overflow
+ * chain is pending, spent, or settled), and each has a defined transition. There is no state
+ * whose fields silently contradict one another.
+ */
+export type ResetRequestPhase = "none" | "explicit";
+export type ResetOverflowPhase = "idle" | "pending" | "pending-spent" | "spent";
+
+export interface ResetControlState {
+	readonly request: ResetRequestPhase;
+	readonly overflow: ResetOverflowPhase;
+}
+
+export function initialResetControl(): ResetControlState {
+	return { request: "none", overflow: "idle" };
+}
+
+/**
+ * Facts for a completed turn. The three `get`-supplied fields are guards the adapter resolves
+ * lazily: the reducer reads each one only in the branch where the previous adapter consulted it,
+ * so policy resolution and pending-message probes keep their original call ordering.
+ */
+export interface ResetTurnEndFacts {
+	readonly aborted: boolean;
+	readonly overflow: boolean;
+	readonly failed: boolean;
+	readonly enabled: boolean;
+	readonly queued: boolean;
+	readonly automaticResetEnabled: boolean;
+	readonly thresholdDue: boolean;
+}
+
+/** Facts for the pre-settlement boundary; policy guards stay lazy for the same reason. */
+export interface ResetBeforeSettleFacts {
+	readonly queued: boolean;
+	readonly enabled: boolean;
+	readonly automaticResetEnabled: boolean;
+	readonly aborted: boolean;
+}
+
+export type ResetControlEvent =
+	| { readonly type: "request" }
+	| { readonly type: "turn_end"; readonly facts: ResetTurnEndFacts }
+	| { readonly type: "before_settle"; readonly facts: ResetBeforeSettleFacts }
+	| { readonly type: "settled" }
+	| { readonly type: "abort" }
+	| { readonly type: "clear" };
+
+/**
+ * The requested effect of a transition. Effects are named, not performed: marker/boot/
+ * continuation writes, continuation requests, and UI notices stay in the adapter.
+ *
+ * - "none"              keep any return value to the drafts already collected for this event.
+ * - "requested"         a new explicit reset request was recorded.
+ * - "already-requested" a request was already pending and was deduplicated.
+ * - "commit-boundary"   build and commit the reset boundary now (turn_end).
+ * - "recover-overflow"  build and commit the one bounded overflow recovery now (settle).
+ */
+export type ResetControlEffect =
+	| "none"
+	| "requested"
+	| "already-requested"
+	| "commit-boundary"
+	| "recover-overflow";
+
+export interface ResetControlResult {
+	readonly state: ResetControlState;
+	readonly effect: ResetControlEffect;
+}
+
+/**
+ * Pure reset-control transition. It performs no writes, no policy resolution of its own, and
+ * no UI work; every fact it reads is supplied by the caller. Callers can therefore drive the
+ * full transition table without a live Pi session.
+ */
+export function reduceResetControl(state: ResetControlState, event: ResetControlEvent): ResetControlResult {
+	switch (event.type) {
+		case "request": {
+			if (state.request === "explicit") return { state, effect: "already-requested" };
+			return { state: { ...state, request: "explicit" }, effect: "requested" };
+		}
+		case "turn_end": {
+			const facts = event.facts;
+			const requested = state.request === "explicit";
+			// The explicit request is consumed by the turn boundary whether or not it commits.
+			const request: ResetRequestPhase = "none";
+			if (facts.aborted) {
+				// An aborted turn drops the whole boundary: no explicit request, no overflow chain.
+				return { state: { request, overflow: "idle" }, effect: "none" };
+			}
+			if (facts.overflow) {
+				// A failure that Pi may recover natively: arm (or re-arm) the bounded settle path.
+				// A queued message, disabled mode, or disabled automatic reset leaves it disarmed.
+				const pending = !facts.queued && facts.enabled && facts.automaticResetEnabled;
+				const spent = state.overflow === "pending-spent" || state.overflow === "spent";
+				const overflow: ResetOverflowPhase = pending
+					? (spent ? "pending-spent" : "pending")
+					: (spent ? "spent" : "idle");
+				return { state: { request, overflow }, effect: "none" };
+			}
+			// Any non-overflow completed turn supersedes an older overflow failure. A non-overflow
+			// error leaves the armed overflow chain untouched for the settle boundary.
+			const overflow: ResetOverflowPhase = facts.failed ? state.overflow : "idle";
+			if (!facts.enabled || facts.failed) return { state: { request, overflow }, effect: "none" };
+			// Explicit and threshold resets both commit at turn_end, after incoming and budget drafts.
+			const commit = requested || facts.thresholdDue;
+			return { state: { request, overflow }, effect: commit ? "commit-boundary" : "none" };
+		}
+		case "before_settle": {
+			const facts = event.facts;
+			if (state.overflow !== "pending" && state.overflow !== "pending-spent") return { state, effect: "none" };
+			// Let a queued turn run first; its own turn_end settles or clears this chain.
+			if (facts.queued) return { state, effect: "none" };
+			const spent = state.overflow === "pending-spent";
+			if (!facts.enabled || !facts.automaticResetEnabled || facts.aborted) {
+				return { state: { ...state, overflow: spent ? "spent" : "idle" }, effect: "none" };
+			}
+			// The recovery is one-use per failure chain. Committing it spends the attempt.
+			return { state: { ...state, overflow: "spent" }, effect: spent ? "none" : "recover-overflow" };
+		}
+		case "settled":
+			// Settlement ends the failure chain but leaves a pending explicit request armed.
+			return { state: { ...state, overflow: "idle" }, effect: "none" };
+		case "abort":
+		case "clear":
+			return { state: initialResetControl(), effect: "none" };
+	}
+}
+
+/**
+ * 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.
+ *
+ * This function is the effect adapter: it captures Pi events, translates them into pure
+ * reset-control transitions, and performs the resulting marker/boot/continuation writes and
+ * notifications. The decision of what to do lives entirely in `reduceResetControl`.
+ */
+export function registerResetLifecycle(pi: ExtensionAPI, options: ResetOptions) {
+	let sessionActive = true;
+	let control = initialResetControl();
+
+	const clear = () => { control = reduceResetControl(control, { type: "clear" }).state; };
+	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 (!sessionActive) return undefined;
+		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];
+		const decision = reduceResetControl(control, {
+			type: "turn_end",
+			facts: {
+				aborted,
+				overflow: aborted ? false : isOverflowLike(event.message, ctx),
+				failed: event.outcome === "error",
+				enabled: options.isEnabled(),
+				get queued() { return event.context.pendingMessages.length > 0 || ctx.hasPendingMessages(); },
+				get automaticResetEnabled() { return options.budget.automaticResetEnabled(ctx); },
+				get thresholdDue() { return options.budget.resetDue(ctx); },
+			},
+		});
+		control = decision.state;
+		if (decision.effect === "commit-boundary") return resetBoundaryResult(entries, ctx);
+		return entries.length > 0 ? { entries } : undefined;
+	});
+
+	pi.on("agent_before_settle", (event: AgentBeforeSettleEvent, ctx) => {
+		if (!sessionActive) return undefined;
+		const decision = reduceResetControl(control, {
+			type: "before_settle",
+			facts: {
+				get queued() { return event.context.pendingMessages.length > 0 || ctx.hasPendingMessages(); },
+				get enabled() { return options.isEnabled(); },
+				get automaticResetEnabled() { return options.budget.automaticResetEnabled(ctx); },
+				get aborted() { return event.outcome === "aborted" || ctx.signal?.aborted === true; },
+			},
+		});
+		control = decision.state;
+		if (decision.effect !== "recover-overflow") return undefined;
+		return resetBoundaryResult(event.entries, ctx);
+	});
+
+	pi.on("session_before_compact", (event, ctx) => {
+		if (!sessionActive) 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.
+		control = reduceResetControl(control, { type: "settled" }).state;
+	});
+	pi.on("session_start", () => { clear(); sessionActive = true; });
+	pi.on("session_tree", clear);
+	pi.on("session_shutdown", () => { clear(); options.budget.clear(); sessionActive = false; });
+
+	return {
+		request() {
+			const decision = reduceResetControl(control, { type: "request" });
+			control = decision.state;
+			return decision.effect === "already-requested" ? "rollover_already_pending" : "rollover_requested";
+		},
+		clear,
+	};
+}

package/src/context/runtime.ts

@@ -0,0 +1,151 @@
+import { getCurrentSystemMessage, Type } from "@earendil-works/pi-ai";
+import { VERSION, defineTool, type ExtensionAPI, type ExtensionContext, type SettingsManager } from "@earendil-works/pi-coding-agent";
+import { registerBudget } from "./budget.js";
+import { output } from "../tool-output.js";
+import { migrateLegacyHomes } from "../notes/paths.js";
+import { currentReset, isWindowMarker, projectRootWindow, projectWindow, rootWindowId } from "./context-window.js";
+import { registerResetLifecycle } from "./reset-lifecycle.js";
+import { buildResetDrafts, persistManualReset, resetTailCommitted } from "./reset-artifacts.js";
+import { ensureBoot, type IncompleteNotesNotifier } from "./boot.js";
+
+declare const __PI_CONTEXT_BUILD__: { version: string; sourceHash: string };
+
+// The bundle captures its identity; direct source loads must not claim a built hash.
+const buildLabel = typeof __PI_CONTEXT_BUILD__ === "undefined"
+	? "unbundled source (build unknown)"
+	: `${__PI_CONTEXT_BUILD__.version} · build ${__PI_CONTEXT_BUILD__.sourceHash.slice(0, 12)}`;
+
+function branchHasWindowMarker(ctx: ExtensionContext, fromId?: string): boolean {
+	return ctx.sessionManager.getBranch(fromId).some((entry) => isWindowMarker(entry));
+}
+
+/** Register the context-window runtime and its context-owned commands/tools. */
+export function registerContext(pi: ExtensionAPI, settingsManager?: SettingsManager): void {
+	let enabled = true;
+	let missingBootNotice: string | undefined;
+	const incompleteNotesNotified = new Set<string>();
+	const pendingResetNotices = new Set<string>();
+	// Announce only a fully committed reset (marker + matching boot + continuation), not a
+	// reset request or a partial boot repair.
+	const notifyCommittedResets = (ctx: ExtensionContext, addedWindowId?: string) => {
+		if (addedWindowId) pendingResetNotices.add(addedWindowId);
+		if (pendingResetNotices.size === 0) return;
+		const branch = ctx.sessionManager.getBranch();
+		for (const windowId of pendingResetNotices) {
+			const marker = branch.find((entry) => isWindowMarker(entry) && entry.data.windowId === windowId);
+			if (!marker || !resetTailCommitted(ctx, marker.id, windowId)) continue;
+			pendingResetNotices.delete(windowId);
+			ctx.ui.notify(`pi-context: memory cleared · ${windowId}`, "info");
+		}
+	};
+	pi.on("turn_start", (_event, ctx) => notifyCommittedResets(ctx));
+	pi.on("agent_settled", (_event, ctx) => {
+		notifyCommittedResets(ctx);
+		pendingResetNotices.clear();
+	});
+	const notifyIncompleteNotes: IncompleteNotesNotifier = (ctx, windowId, snapshot) => {
+		if (snapshot.unavailable.length === 0 || incompleteNotesNotified.has(windowId)) return;
+		incompleteNotesNotified.add(windowId);
+		const homes = snapshot.unavailable.map((home) => home.label).join(", ");
+		ctx.ui.notify(`pi-context: notes index incomplete for ${homes}; notes_list can retry after recovery.`, "warning");
+	};
+	const migrationWarning = migrateLegacyHomes();
+	if (migrationWarning) console.warn(`pi-context: ${migrationWarning}`);
+
+	const budget = registerBudget(pi, () => enabled, settingsManager);
+
+	pi.on("session_start", (_event, ctx) => {
+		if (!enabled) return;
+		missingBootNotice = undefined;
+		pendingResetNotices.clear();
+		ensureBoot(pi, ctx, notifyIncompleteNotes);
+	});
+	pi.on("session_tree", (_event, ctx) => {
+		missingBootNotice = undefined;
+		pendingResetNotices.clear();
+		if (enabled) ensureBoot(pi, ctx, notifyIncompleteNotes);
+	});
+
+	// Pi's branch summarizer receives raw entries and bypasses context_with_system. Do not
+	// let a summary of a reset branch smuggle erased history back into the destination.
+	pi.on("session_before_tree", (event, ctx) => {
+		if (!event.preparation.userWantsSummary) return undefined;
+		if (!branchHasWindowMarker(ctx) && !branchHasWindowMarker(ctx, event.preparation.targetId)) return undefined;
+		ctx.ui.notify("pi-context: skipped branch summary across a reset window; navigation continues without erased history.", "info");
+		return { summary: { summary: "" } };
+	});
+
+	// This is the final provider-facing projection. Reset windows cut at their matching boot;
+	// root windows only refresh a forked boot identity and retain the copied root transcript.
+	pi.on("context_with_system", (event, ctx) => {
+		const reset = currentReset(ctx);
+		const windowId = reset?.data.windowId ?? rootWindowId(ctx.sessionManager.getSessionId());
+		try {
+			return { messages: reset ? projectWindow(event.messages, windowId) : projectRootWindow(event.messages, windowId) };
+		} catch (error) {
+			if (missingBootNotice !== windowId) {
+				missingBootNotice = windowId;
+				ctx.ui.notify(`pi-context: active context window ${windowId} has no visible boot; request cancelled safely. Use /wipe-memory to start another window.`, "error");
+			}
+			ctx.abort();
+			const safeHead = getCurrentSystemMessage(event.messages);
+			return { messages: safeHead ? [safeHead] : [] };
+		}
+	});
+
+	pi.registerCommand("pi-context", {
+		description: "Show loaded version/build and toggle pi-context context windows",
+		getArgumentCompletions: (prefix) =>
+			["on", "off"].filter((a) => a.startsWith(prefix)).map((a) => ({ value: a, label: a })),
+		handler: async (args, cmdCtx) => {
+			const arg = args.trim().toLowerCase();
+			if (arg === "on") {
+				enabled = true;
+				ensureBoot(pi, cmdCtx, notifyIncompleteNotes);
+			} else if (arg === "off") {
+				enabled = false;
+				budget.clear();
+				resets.clear();
+			} else if (arg !== "") {
+				cmdCtx.ui.notify("Usage: /pi-context [on|off]", "error");
+				return;
+			}
+			cmdCtx.ui.notify(`pi-context: ${enabled ? "on" : "off"} · ${buildLabel} · Pi ${VERSION}`, "info");
+		},
+	});
+
+	pi.registerCommand("wipe-memory", {
+		description: "Persist a fresh context window without calling the model",
+		handler: async (_args, cmdCtx) => {
+			if (!enabled) {
+				cmdCtx.ui.notify("pi-context: /wipe-memory requires /pi-context on.", "error");
+				return;
+			}
+			await cmdCtx.waitForIdle();
+			if (!enabled) return;
+			resets.clear();
+			notifyCommittedResets(cmdCtx, persistManualReset(pi, cmdCtx, notifyIncompleteNotes));
+		},
+	});
+
+	pi.registerTool(defineTool({
+		name: "wipe_memory",
+		label: "Wipe memory",
+		description: "Wipe your in-context memory and start a fresh context window. Your session, notes, and history survive.",
+		parameters: Type.Object({}, { additionalProperties: false }),
+		async execute() {
+			if (!enabled) return output({ error: "pi-context is off (/pi-context on to enable)" });
+			return output({ status: resets.request() }, undefined, true);
+		},
+	}));
+
+	const resets = registerResetLifecycle(pi, {
+		isEnabled: () => enabled,
+		buildReset: (ctx) => {
+			const drafts = buildResetDrafts(ctx, notifyIncompleteNotes);
+			pendingResetNotices.add(drafts[1].details.windowId);
+			return drafts;
+		},
+		budget,
+	});
+}