@astrosheep/pi-context 0.25.0 → 0.25.2

package/dist/src/context/boot.js

@@ -0,0 +1,46 @@
+import { loadNotesSnapshot } 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";
+/** Render the boot block from the live context; acquisition stays with loadNotesSnapshot. */
+function bootContent(ctx, currentId, previousId, notes) {
+    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, windowId, previousId, notifyIncompleteNotes) {
+    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, boot) {
+    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, ctx, notifyIncompleteNotes) {
+    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/dist/src/context/budget.js

@@ -40,6 +40,7 @@ export function registerBudget(pi, isEnabled, settingsManager) {
         return usage !== undefined && usage.tokens !== null && usage.contextWindow - usage.tokens <= thresholdsFor(ctx).reserve;
     };
     const invalidateThresholds = () => { cachedPolicy = undefined; };
+    const formatRemaining = (remaining) => `${Math.max(0, Math.ceil(remaining / 1000))}k`;
     let pendingGuidance;
     let pendingWarning;
     let pendingNotices = [];
@@ -49,8 +50,8 @@ export function registerBudget(pi, isEnabled, settingsManager) {
             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 = [];
     };
@@ -72,7 +73,7 @@ export function registerBudget(pi, isEnabled, settingsManager) {
         clearStaged();
         const windowId = currentWindowId(ctx);
         const drafts = staged.filter((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",
             customType: draft.customType,
@@ -88,7 +89,6 @@ export function registerBudget(pi, isEnabled, settingsManager) {
     // 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();
@@ -109,7 +109,7 @@ export function registerBudget(pi, isEnabled, settingsManager) {
             // 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",
                 customType: WARNING_TYPE,
@@ -125,7 +125,7 @@ export function registerBudget(pi, isEnabled, settingsManager) {
             // 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/dist/src/context/context-window.js

@@ -38,6 +38,17 @@ export function hasWindowMessage(ctx, customType) {
 export function currentWindowId(ctx) {
     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, markerId) {
+    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, windowId) {
     return typeof details === "object" && details !== null &&
         typeof details.windowId === "string" &&
@@ -47,6 +58,10 @@ function hasWindowId(details, windowId) {
 export function isWindowBoot(message, windowId) {
     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, windowId) {
+    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/dist/src/context/prompts.js

@@ -1,4 +1,4 @@
-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, modelName, firstWindowId, currentWindowId, previousWindowId) {
     const lines = [
@@ -24,8 +24,7 @@ function notesUnavailableNotice(snapshot) {
     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.`;
 }
 /**
  * Boot notes index. Map residency ("地图在场"): fresh MAP.md bodies from the human, project,
@@ -58,7 +57,7 @@ function notesIndex(snapshot) {
         ...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)})`);
         }
@@ -67,12 +66,10 @@ function notesIndex(snapshot) {
     return sections.join("\n\n");
 }
 function notesHomeBlock() {
-    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.";
 }
 export function renderBootBlock(data) {
     const parts = [];
-    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/dist/src/context/reset-artifacts.js

@@ -0,0 +1,86 @@
+import { randomUUID } from "node:crypto";
+import { BOOT_TYPE, CONTINUATION, CONTINUATION_TYPE, RESET_MARKER_TYPE } from "../protocol.js";
+import { currentWindowId, isWindowBootEntry, isWindowMarker, previousWindowId } from "./context-window.js";
+import { buildBootMessage, sendBoot } from "./boot.js";
+/** Match the hidden continuation entry that carries the one reset message. */
+export function isWindowContinuationEntry(entry) {
+    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) {
+    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, notifyIncompleteNotes) {
+    const sessionPrefix = ctx.sessionManager.getSessionId().slice(0, 8);
+    const usedWindowIds = new Set(ctx.sessionManager.getBranch().filter(isWindowMarker).map((entry) => entry.data.windowId));
+    let windowId;
+    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 },
+    ];
+}
+/** Persist the marker and send both hidden reset messages; returns the new window id. */
+export function persistManualReset(pi, ctx, notifyIncompleteNotes) {
+    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, markerId, windowId) {
+    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, markerId, windowId) {
+    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, ctx, marker, notifyIncompleteNotes) {
+    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/dist/src/context/reset-lifecycle.js

@@ -9,22 +9,85 @@ function isOverflowLike(message, ctx) {
     return isContextOverflow(message, ctx.model?.contextWindow) ||
         (ctx.model !== undefined && isRecoverableLength(message, ctx.model.maxTokens));
 }
+export function initialResetControl() {
+    return { request: "none", overflow: "idle" };
+}
+/**
+ * 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, event) {
+    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 = "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 = 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 = 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, options) {
-    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, ctx) => {
         try {
             return { entries: [...entries, ...options.buildReset(ctx)], continue: true };
@@ -38,63 +101,50 @@ export function registerResetLifecycle(pi, options) {
         }
     };
     pi.on("turn_end", (event, ctx) => {
-        if (!active)
+        if (!sessionActive)
             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);
+        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, 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)
+        if (!sessionActive)
             return undefined;
-        if (overflowRecoveryUsed)
+        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;
-        overflowRecoveryUsed = true;
         return resetBoundaryResult(event.entries, ctx);
     });
     pi.on("session_before_compact", (event, ctx) => {
-        if (!active)
+        if (!sessionActive)
             return undefined;
         if (event.signal.aborted)
             return { cancel: true };
@@ -116,18 +166,16 @@ export function registerResetLifecycle(pi, options) {
     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,
     };

package/dist/src/context/runtime.js

@@ -1,102 +1,16 @@
 import { getCurrentSystemMessage, Type } from "@earendil-works/pi-ai";
 import { VERSION, defineTool } from "@earendil-works/pi-coding-agent";
-import { randomUUID } from "node:crypto";
 import { registerBudget } from "./budget.js";
 import { output } from "../tool-output.js";
-import { BOOT_TYPE, RESET_MARKER_TYPE, CONTINUATION_TYPE, CONTINUATION } from "../protocol.js";
-import { agentSlug, migrateLegacyHomes, modelSlug } from "../notes/paths.js";
-import { loadNotesSnapshot } from "../notes/notes-snapshot.js";
-import { renderBootBlock } from "./prompts.js";
-import { currentReset, currentWindowId, isWindowBoot, isWindowMarker, projectRootWindow, projectWindow, rootWindowId } from "./context-window.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 } from "./boot.js";
 // 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 bootContent(ctx, currentId, previousId, resetLine, notes) {
-    return renderBootBlock({
-        agentName: agentSlug(ctx),
-        modelName: modelSlug(ctx),
-        firstWindowId: rootWindowId(ctx.sessionManager.getSessionId()),
-        currentWindowId: currentId,
-        previousWindowId: previousId,
-        resetLine,
-        notes,
-    });
-}
-function buildResetDrafts(ctx, notifyIncompleteNotes) {
-    const sessionPrefix = ctx.sessionManager.getSessionId().slice(0, 8);
-    const usedWindowIds = new Set(ctx.sessionManager.getBranch().filter(isWindowMarker).map((entry) => entry.data.windowId));
-    let windowId;
-    do {
-        windowId = `pcw:${sessionPrefix}:${randomUUID().slice(0, 8)}`;
-    } while (usedWindowIds.has(windowId));
-    const notes = loadNotesSnapshot(ctx);
-    notifyIncompleteNotes?.(ctx, windowId, notes);
-    return [
-        { type: "custom", customType: RESET_MARKER_TYPE, data: { windowId } },
-        {
-            type: "custom_message",
-            customType: BOOT_TYPE,
-            content: bootContent(ctx, windowId, currentWindowId(ctx), true, notes),
-            display: false,
-            details: { windowId },
-        },
-        {
-            type: "custom_message",
-            customType: CONTINUATION_TYPE,
-            content: CONTINUATION,
-            display: false,
-        },
-    ];
-}
-function ensureBoot(pi, ctx, notifyIncompleteNotes) {
-    const reset = currentReset(ctx);
-    const sessionId = ctx.sessionManager.getSessionId();
-    const windowId = reset?.data?.windowId ?? rootWindowId(sessionId);
-    if (ctx.sessionManager.buildSessionProjection().messages.some((message) => isWindowBoot(message, windowId)))
-        return;
-    if (reset && !resetBootMayBeRepaired(ctx, reset.id, windowId))
-        return;
-    let previousId = reset ? rootWindowId(sessionId) : undefined;
-    if (reset) {
-        for (const entry of ctx.sessionManager.getBranch()) {
-            if (entry.id === reset.id)
-                break;
-            if (isWindowMarker(entry))
-                previousId = entry.data.windowId;
-        }
-    }
-    const notes = loadNotesSnapshot(ctx);
-    notifyIncompleteNotes?.(ctx, windowId, notes);
-    pi.sendMessage({ customType: BOOT_TYPE, content: bootContent(ctx, windowId, previousId, reset !== undefined, notes), display: false, details: { windowId } }, { triggerTurn: false });
-}
-function persistManualReset(pi, ctx, notifyIncompleteNotes) {
-    const [marker, boot] = 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 });
-    return boot.details.windowId;
-}
-function resetBootMayBeRepaired(ctx, markerId, windowId) {
-    const branch = ctx.sessionManager.getBranch();
-    const markerIndex = branch.findIndex((entry) => entry.id === markerId);
-    if (markerIndex < 0)
-        return false;
-    const afterMarker = branch.slice(markerIndex + 1);
-    // A raw boot is authoritative even when a later context_edit hides it from the
-    // projection. Appending another boot at the tail would move the boundary.
-    if (afterMarker.some((entry) => isWindowBootEntry(entry, windowId)))
-        return false;
-    // Only a genuinely incomplete marker tail can be repaired. Once conversation or
-    // a context-bearing custom message follows it, refusing is safer than guessing.
-    return !afterMarker.some((entry) => entry.type === "message" || entry.type === "custom_message" || entry.type === "compaction" || entry.type === "branch_summary");
-}
-function isWindowBootEntry(entry, windowId) {
-    return entry.type === "custom_message" && entry.customType === BOOT_TYPE &&
-        typeof entry.details === "object" && entry.details !== null &&
-        typeof entry.details.windowId === "string" &&
-        entry.details.windowId === windowId;
-}
 function branchHasWindowMarker(ctx, fromId) {
     return ctx.sessionManager.getBranch(fromId).some((entry) => isWindowMarker(entry));
 }
@@ -106,6 +20,8 @@ export function registerContext(pi, settingsManager) {
     let missingBootNotice;
     const incompleteNotesNotified = new Set();
     const pendingResetNotices = new Set();
+    // Announce only a fully committed reset (marker + matching boot + continuation), not a
+    // reset request or a partial boot repair.
     const notifyCommittedResets = (ctx, addedWindowId) => {
         if (addedWindowId)
             pendingResetNotices.add(addedWindowId);
@@ -113,14 +29,13 @@ export function registerContext(pi, settingsManager) {
             return;
         const branch = ctx.sessionManager.getBranch();
         for (const windowId of pendingResetNotices) {
-            if (!branch.some((entry) => isWindowMarker(entry) && entry.data.windowId === windowId) ||
-                !branch.some((entry) => isWindowBootEntry(entry, windowId)))
+            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");
         }
     };
-    // Announce only a committed reset (marker + boot), not a reset request or boot repair.
     pi.on("turn_start", (_event, ctx) => notifyCommittedResets(ctx));
     pi.on("agent_settled", (_event, ctx) => {
         notifyCommittedResets(ctx);

package/dist/src/index.js

@@ -4,7 +4,7 @@ import { registerNotesTools } from "./notes/tools.js";
 import { deriveThresholds } from "./context/thresholds.js";
 import { registerContext } from "./context/runtime.js";
 import { mergePiContextSettings } from "./settings.js";
-import { NOTE_TYPE, BOOT_TYPE, GUIDANCE_TYPE, WARNING_TYPE, RESET_MARKER_TYPE, CONTINUATION_TYPE, MAX_NOTE_BYTES, CONTEXT_WINDOW_OPEN_TAG, CONTEXT_WINDOW_CLOSE_TAG, CONTEXT_WINDOW_PROTOCOL_OPEN_TAG, CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG, GUIDANCE_OPEN_TAG, PI_CONTEXT_SETTINGS_KEY, DEFAULT_RESERVE_TOKENS, DEFAULT_REMINDER_MARGIN_TOKENS, WARNING_RUNWAY_TOKENS, RESET_SUMMARY, CONTINUATION, WARNING_PROMPT } from "./protocol.js";
+import { NOTE_TYPE, BOOT_TYPE, GUIDANCE_TYPE, WARNING_TYPE, RESET_MARKER_TYPE, CONTINUATION_TYPE, MAX_NOTE_BYTES, CONTEXT_WINDOW_OPEN_TAG, CONTEXT_WINDOW_CLOSE_TAG, CONTEXT_WINDOW_PROTOCOL_OPEN_TAG, CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG, GUIDANCE_OPEN_TAG, PI_CONTEXT_SETTINGS_KEY, DEFAULT_RESERVE_TOKENS, DEFAULT_REMINDER_MARGIN_TOKENS, WARNING_RUNWAY_TOKENS, CONTINUATION, WARNING_PROMPT } from "./protocol.js";
 import { assertVirtualPath } from "./notes/address.js";
 export { historyFromSession } from "./history/history.js";
 export { notesFromSession } from "./notes/session-replay.js";
@@ -28,4 +28,4 @@ export function createPiContext(options = {}) {
 export default function piContext(pi) {
     registerPiContext(pi);
 }
-export const internal = { MAX_NOTE_BYTES, NOTE_TYPE, BOOT_TYPE, GUIDANCE_TYPE, WARNING_TYPE, CONTINUATION_TYPE, WARNING_PROMPT, WARNING_RUNWAY_TOKENS, RESET_MARKER_TYPE, RESET_SUMMARY, CONTINUATION, CONTEXT_WINDOW_OPEN_TAG, CONTEXT_WINDOW_CLOSE_TAG, CONTEXT_WINDOW_PROTOCOL_OPEN_TAG, CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG, GUIDANCE_OPEN_TAG, PI_CONTEXT_SETTINGS_KEY, DEFAULT_RESERVE_TOKENS, DEFAULT_REMINDER_MARGIN_TOKENS, deriveThresholds, mergePiContextSettings, assertVirtualPath };
+export const internal = { MAX_NOTE_BYTES, NOTE_TYPE, BOOT_TYPE, GUIDANCE_TYPE, WARNING_TYPE, CONTINUATION_TYPE, WARNING_PROMPT, WARNING_RUNWAY_TOKENS, RESET_MARKER_TYPE, CONTINUATION, CONTEXT_WINDOW_OPEN_TAG, CONTEXT_WINDOW_CLOSE_TAG, CONTEXT_WINDOW_PROTOCOL_OPEN_TAG, CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG, GUIDANCE_OPEN_TAG, PI_CONTEXT_SETTINGS_KEY, DEFAULT_RESERVE_TOKENS, DEFAULT_REMINDER_MARGIN_TOKENS, deriveThresholds, mergePiContextSettings, assertVirtualPath };

package/dist/src/notes/address.js

@@ -1,5 +1,5 @@
 import { agentSlug, modelSlug, SLUG_PATTERN } from "./paths.js";
-export const ADDRESS_FORMS = "legal prefixes are @project/, @human/, @self/, @agents/<name>/, @model/, and @models/<name>/; bare names are the session home";
+export const ADDRESS_FORMS = "legal prefixes are @project/, @human/, @self/, and @model/; bare names are this session";
 export function assertVirtualPath(value) {
     if (typeof value !== "string" || value.length === 0)
         throw new Error("path must be a non-empty virtual relative path");