@astrosheep/pi-context 0.25.0 → 0.25.2

package/src/context/boot.ts

@@ -0,0 +1,68 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { loadNotesSnapshot, type NotesSnapshot } from "../notes/notes-snapshot.js";
+import { agentSlug, modelSlug } from "../notes/paths.js";
+import { BOOT_TYPE } from "../protocol.js";
+import { renderBootBlock } from "./prompts.js";
+import { currentReset, isWindowBoot, rootWindowId } from "./context-window.js";
+import { repairResetTail } from "./reset-artifacts.js";
+
+export type IncompleteNotesNotifier = (ctx: ExtensionContext, windowId: string, snapshot: NotesSnapshot) => void;
+
+/** The boot custom message: identity, notes snapshot, and static protocol; never reset prose. */
+export type BootMessage = {
+	readonly customType: string;
+	readonly content: string;
+	readonly display: false;
+	readonly details: { windowId: string };
+};
+
+/** Render the boot block from the live context; acquisition stays with loadNotesSnapshot. */
+function bootContent(ctx: ExtensionContext, currentId: string, previousId: string | undefined, notes: NotesSnapshot): string {
+	return renderBootBlock({
+		agentName: agentSlug(ctx),
+		modelName: modelSlug(ctx),
+		firstWindowId: rootWindowId(ctx.sessionManager.getSessionId()),
+		currentWindowId: currentId,
+		previousWindowId: previousId,
+		notes,
+	});
+}
+
+/**
+ * Acquire one notes snapshot and build the boot custom message for a window. The caller
+ * supplies `previousId` only when a reset boundary needs the prior window identity.
+ */
+export function buildBootMessage(
+	ctx: ExtensionContext,
+	windowId: string,
+	previousId: string | undefined,
+	notifyIncompleteNotes?: IncompleteNotesNotifier,
+): BootMessage {
+	const notes = loadNotesSnapshot(ctx);
+	notifyIncompleteNotes?.(ctx, windowId, notes);
+	return { customType: BOOT_TYPE, content: bootContent(ctx, windowId, previousId, notes), display: false, details: { windowId } };
+}
+
+/** Persist one hidden boot message without triggering a model turn. */
+export function sendBoot(pi: ExtensionAPI, boot: BootMessage): void {
+	pi.sendMessage(
+		{ customType: boot.customType, content: boot.content, display: boot.display, details: boot.details },
+		{ triggerTurn: false },
+	);
+}
+
+/**
+ * Boot entry point for `session_start` / `session_tree`. Ordinary startup ensures one root
+ * boot; a reset marker instead asks reset-artifact repair to complete its persisted tail.
+ * Boot idempotence lives here: an already-projected root boot or a complete reset tail emits nothing.
+ */
+export function ensureBoot(pi: ExtensionAPI, ctx: ExtensionContext, notifyIncompleteNotes?: IncompleteNotesNotifier): void {
+	const reset = currentReset(ctx);
+	if (reset) {
+		repairResetTail(pi, ctx, reset, notifyIncompleteNotes);
+		return;
+	}
+	const windowId = rootWindowId(ctx.sessionManager.getSessionId());
+	if (ctx.sessionManager.buildSessionProjection().messages.some((message) => isWindowBoot(message, windowId))) return;
+	sendBoot(pi, buildBootMessage(ctx, windowId, undefined, notifyIncompleteNotes));
+}

package/src/context/budget.ts

@@ -38,16 +38,17 @@ export function registerBudget(pi: ExtensionAPI, isEnabled: () => boolean, setti
 		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 formatRemaining = (remaining: number): string => `${Math.max(0, Math.ceil(remaining / 1000))}k`;
+	let pendingGuidance: { windowId: string; content: string; remaining: number } | undefined;
+	let pendingWarning: { windowId: string; content: string; remaining: number } | undefined;
+	let pendingNotices: Array<{ windowId: string; customType: string; remaining: number }> = [];
 	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");
+				? `pi-context: Context almost full — ${formatRemaining(notice.remaining)} remaining`
+				: `pi-context: Context running low — ${formatRemaining(notice.remaining)} remaining`, "warning");
 		}
 		pendingNotices = [];
 	};
@@ -71,7 +72,7 @@ export function registerBudget(pi: ExtensionAPI, isEnabled: () => boolean, setti
 		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 }));
+		pendingNotices = drafts.map(({ windowId, customType, remaining }) => ({ windowId, customType, remaining }));
 		return drafts.map((draft) => ({
 			type: "custom_message" as const,
 			customType: draft.customType,
@@ -88,7 +89,6 @@ export function registerBudget(pi: ExtensionAPI, isEnabled: () => boolean, setti
 	// 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();
@@ -106,7 +106,7 @@ export function registerBudget(pi: ExtensionAPI, isEnabled: () => boolean, setti
 			// 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 };
+			pendingWarning = { windowId, content, remaining };
 			const warningMessage = {
 				role: "custom" as const,
 				customType: WARNING_TYPE,
@@ -121,7 +121,7 @@ export function registerBudget(pi: ExtensionAPI, isEnabled: () => boolean, setti
 			// 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) };
+			pendingGuidance = { windowId, content: tokenBudgetGuidance(left), remaining };
 		}
 		return undefined;
 	});

package/src/context/context-window.ts

@@ -45,6 +45,16 @@ export function currentWindowId(ctx: SessionReader): string {
 	return currentReset(ctx)?.data.windowId ?? rootWindowId(ctx.sessionManager.getSessionId());
 }
 
+/** The durable window active just before the marker: the last earlier marker, else the root window. */
+export function previousWindowId(ctx: SessionReader, markerId: string): string {
+	let previousId = rootWindowId(ctx.sessionManager.getSessionId());
+	for (const entry of ctx.sessionManager.getBranch()) {
+		if (entry.id === markerId) break;
+		if (isWindowMarker(entry)) previousId = entry.data.windowId;
+	}
+	return previousId;
+}
+
 function hasWindowId(details: unknown, windowId: string): boolean {
 	return typeof details === "object" && details !== null &&
 		typeof (details as { windowId?: unknown }).windowId === "string" &&
@@ -56,6 +66,11 @@ export function isWindowBoot(message: AgentMessage, windowId?: string): boolean
 	return message.role === "custom" && message.customType === BOOT_TYPE && (windowId === undefined || hasWindowId(message.details, windowId));
 }
 
+/** Match a persisted boot entry by raw identity, even when a later edit hides it from projection. */
+export function isWindowBootEntry(entry: SessionEntry, windowId: string): boolean {
+	return entry.type === "custom_message" && entry.customType === BOOT_TYPE && hasWindowId(entry.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

package/src/context/prompts.ts

@@ -1,5 +1,5 @@
 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";
+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 {
@@ -27,8 +27,7 @@ function rowsFor(snapshot: NotesSnapshot, scope: NotesHome["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.`;
+	return `Notes index incomplete: index for ${homes} unavailable during boot; notes_list can retry after recovery.`;
 }
 
 /**
@@ -61,7 +60,7 @@ function notesIndex(snapshot: NotesSnapshot): string {
 		...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:`];
+		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)})`);
 		}
@@ -71,7 +70,7 @@ function notesIndex(snapshot: NotesSnapshot): string {
 }
 
 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.";
+	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.";
 }
 
 /**
@@ -84,13 +83,11 @@ export type BootRenderData = {
 	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);

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

@@ -26,23 +26,161 @@ function isOverflowLike(message: AgentMessage, ctx: ExtensionContext): boolean {
 		(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 explicitRequested = false;
-	let overflowPending = false;
-	let overflowRecoveryUsed = false;
-	let active = true;
-
-	const clear = () => {
-		explicitRequested = false;
-		overflowPending = false;
-		overflowRecoveryUsed = false;
-	};
+	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 };
@@ -56,58 +194,48 @@ export function registerResetLifecycle(pi: ExtensionAPI, options: ResetOptions)
 	};
 
 	pi.on("turn_end", (event, ctx) => {
-		if (!active) return undefined;
-		const requested = explicitRequested;
-		explicitRequested = false;
+		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];
-		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);
+		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 (!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;
+		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 (!active) return undefined;
+		if (!sessionActive) return undefined;
 		if (event.signal.aborted) return { cancel: true };
 		const markerExists = currentReset(ctx) !== undefined;
 		if (options.isEnabled() || markerExists) {
@@ -127,18 +255,17 @@ export function registerResetLifecycle(pi: ExtensionAPI, options: ResetOptions)
 	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;
+		control = reduceResetControl(control, { type: "settled" }).state;
 	});
-	pi.on("session_start", () => { clear(); active = true; });
+	pi.on("session_start", () => { clear(); sessionActive = true; });
 	pi.on("session_tree", clear);
-	pi.on("session_shutdown", () => { clear(); options.budget.clear(); active = false; });
+	pi.on("session_shutdown", () => { clear(); options.budget.clear(); sessionActive = false; });
 
 	return {
 		request() {
-			if (explicitRequested) return "rollover_already_pending";
-			explicitRequested = true;
-			return "rollover_requested";
+			const decision = reduceResetControl(control, { type: "request" });
+			control = decision.state;
+			return decision.effect === "already-requested" ? "rollover_already_pending" : "rollover_requested";
 		},
 		clear,
 	};