@astrosheep/pi-context 0.25.0 → 0.25.2

package/dist/src/notes/tools.js

@@ -8,7 +8,7 @@ import { NoteError, editNote, listNotes, readNote, searchNotes, writeNote } from
 const ORIGIN = Type.Optional(Type.Union([Type.Literal("user"), Type.Literal("self"), Type.Literal("external")], {
     description: "Where the note's content came from. user: written or dictated by the human. self: written by you, the agent (default). external: anything else — third-party text, tool output, fetched material.",
 }));
-const ADDRESS_DESCRIPTION = "Address forms are bare `<vpath>` for this session, `@project/<vpath>` for this project, `@human/<vpath>` for the human's cross-project home, `@self/<vpath>` / `@agents/<name>/<vpath>` for agent homes, and `@model/<vpath>` / `@models/<name>/<vpath>` for model homes. `@self` and `@model` mean the current agent/model; the `<name>` forms name one absolutely. The word after `@` is always one of the reserved home names — names live at the second level, never `@faye/`. `@` means leaving home. Any other `@` prefix, or `@` inside a vpath, is a hard error. There is no cross-home fallback. Paths reject `..`, absolute paths, and backslashes. Homes you do not own (`@agents/<other>/`, `@models/<other>/`) are read-only.";
+const ADDRESS_DESCRIPTION = "Address forms are bare `<vpath>` for this session, `@project/<vpath>` for this project, `@human/<vpath>` for the human's cross-project notes, `@self/<vpath>` for your own, and `@model/<vpath>` for the current model's. `@self` and `@model` mean whoever is running now. Any other `@` prefix, or `@` inside a vpath, is a hard error. There is no fallback across prefixes. Paths reject `..`, absolute paths, and backslashes.";
 function failure(error) {
     if (error instanceof NoteError) {
         const payload = { error: error.message };
@@ -79,7 +79,7 @@ export function registerNotesTools(pi) {
     }));
     pi.registerTool(defineTool({
         name: "notes_list", label: "Notes list",
-        description: `List note files as rows carrying address, updated_at, and stale, most recently updated first. ${ADDRESS_DESCRIPTION} Listings merge your five reachable homes: this session, @project/, @human/, your @self home, and the current @model home; other agents and models appear only under an explicit glob (@agents/<name>/**, @models/<name>/**, or a glob in the name segment to scan a whole namespace).`,
+        description: `List note files as rows carrying address, updated_at, and stale, most recently updated first. ${ADDRESS_DESCRIPTION} Listings merge your five prefixes: this session, @project/, @human/, @self/, and @model/.`,
         parameters: Type.Object({ pattern: nullableString(), cursor: cursor(), max_results: positiveInteger() }, { additionalProperties: false }),
         async execute(_id, params, _signal, _update, ctx) {
             let rows;
@@ -100,7 +100,7 @@ export function registerNotesTools(pi) {
     }));
     pi.registerTool(defineTool({
         name: "notes_search", label: "Notes search",
-        description: `Case-sensitive literal substring search over note bodies; query is one string or several (OR), each matched line appears once. ${ADDRESS_DESCRIPTION} Search merges the same five reachable homes as notes_list; explicit globs reach other agents and models. Patterns glob over full address strings. Each file entry carries matches_total, its full match count before capping. Each match carries line, text, offset_chars (a code-point offset into the serialized note returned by notes_read, at the earliest query match), and truncated.`,
+        description: `Case-sensitive literal substring search over note bodies; query is one string or several (OR), each matched line appears once. ${ADDRESS_DESCRIPTION} Search merges the same five prefixes as notes_list. Patterns glob over full address strings. Each file entry carries matches_total, its full match count before capping. Each match carries line, text, offset_chars (a code-point offset into the serialized note returned by notes_read, at the earliest query match), and truncated.`,
         parameters: Type.Object({ query: searchQuery(), pattern: nullableString(), cursor: cursor(), max_matches_per_file: positiveInteger(), max_files: positiveInteger() }, { additionalProperties: false }),
         async execute(_id, params, _signal, _update, ctx) {
             const queries = searchQueries(params.query);

package/dist/src/protocol.js

@@ -32,8 +32,8 @@ export const DEFAULT_REMINDER_MARGIN_TOKENS = 24_576;
  * never sees — Codex's fallback buffer, relocated above the line.
  */
 export const WARNING_RUNWAY_TOKENS = 12_288;
-export const RESET_SUMMARY = "You wake up. Your head is empty — no memories, the past a blank. The memory is gone for good. What outlived it: the notes you wrote, and the history that was recorded. They are not your memory — read them to rebuild what you need.";
-export const CONTINUATION = "Your memory was just erased. Pull only the details you need from history_* and notes_*, then get back to work.";
+/** The single reset message: the only reset prose persisted, carried by the continuation entry. */
+export const CONTINUATION = "Your memory was just erased. Your head is blank. Good news: your notes are still here, and history remains... searchable. Do try to keep up.";
 /**
  * Static protocol teaching adapted from Codex's token_budget.guidance_message to
  * pi-context's tool names. It lives once per window in the persisted boot block;
@@ -47,9 +47,7 @@ Keep a running checkpoint while you work, not at the last minute — the next wi
 
 Use get_context_remaining to see how much of the window is left. When it runs out, this window is gone — with no final turn at the limit — and you continue in a fresh one, recovering only through notes_* and history_*. Once your checkpoint is written, you can call wipe_memory yourself instead of waiting for the erase. Do not let a window die undocumented.
 
-If <context_window> lists a Previous context window id, a reset just happened and the old conversation is not included. Read your note checkpoint first, then recover details through history_*: history_read directly when you know the window and item IDs, history_list or history_search to find them when you don't.
-
-Notes live in five homes, and the word after @ is always one of their reserved names — your own name and other people's names live at the second level (@agents/faye/, never @faye/). Bare names are this session; @project/<vpath> is this project's workspace; @human/<vpath> is the human's cross-project home; @self/<vpath> and @agents/<name>/<vpath> are agent homes; @model/<vpath> and @models/<name>/<vpath> are model homes. @self and @model are the only relative forms — the current agent, the current model — and listings never show them, only the resolved name. There is no cross-home fallback.
+Note addresses take five prefixes: bare <vpath> is this session; @project/<vpath> is this project; @human/<vpath> is the human's cross-project notes; @self/<vpath> is your own, as the current agent; @model/<vpath> is the current model's. @self and @model resolve to who is running now; listings always show resolved names. Nothing else is legal — any other @ prefix, or @ inside a vpath, is a hard error, with no fallback across prefixes.
 Session notes belong to this trip — the goal, the progress, the loose ends. The next window of THIS trip wakes to them; once the trip is over, nobody does.
 @project notes hold facts about this project — architecture, conventions, workflows, deployment and environment details — for whoever works here next.
 @human notes hold the human's durable preferences and standing rules, plus lessons that apply across projects — for every agent that serves this human, whoever is running. You write there as the human's scribe; what the human dictates carries origin: user. When the intended scope is unclear, keep the note in the narrowest stated scope rather than widening it.

package/dist/test/agent-loop.test.js

@@ -6,7 +6,7 @@ import test from "node:test";
 import { createAssistantMessageEventStream, getCurrentSystemMessage } from "@earendil-works/pi-ai";
 import { createAgentSession, DefaultResourceLoader, ModelRuntime, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
 import piContext, { createPiContext } from "../src/index.js";
-import { BOOT_TYPE, CONTEXT_WINDOW_OPEN_TAG, GUIDANCE_OPEN_TAG, GUIDANCE_TYPE, RESET_MARKER_TYPE, WARNING_TYPE } from "../src/protocol.js";
+import { BOOT_TYPE, CONTEXT_WINDOW_OPEN_TAG, CONTINUATION, CONTINUATION_TYPE, GUIDANCE_OPEN_TAG, GUIDANCE_TYPE, RESET_MARKER_TYPE, WARNING_TYPE } from "../src/protocol.js";
 async function openFixture(options) {
     const dir = options.cwd ?? mkdtempSync(join(tmpdir(), "pi-context-agent-loop-"));
     const ownsDir = options.cwd === undefined;
@@ -59,6 +59,7 @@ async function openFixture(options) {
     const streamSignals = [];
     const events = [];
     const notices = [];
+    let budgetNotices = 0;
     let session;
     const loader = new DefaultResourceLoader({
         cwd: dir,
@@ -120,16 +121,14 @@ async function openFixture(options) {
     };
     await session.bindExtensions({
         uiContext: {
-            notify(message) {
+            notify(message, type) {
                 if (message.startsWith("pi-context: memory cleared · ")) {
                     const windowId = message.split(" · ")[1];
                     assert.ok(sessionManager.getBranch().some((entry) => entry.type === "custom" && entry.customType === RESET_MARKER_TYPE && entry.data?.windowId === windowId), "notification follows the reset marker commit");
                     assert.ok(sessionManager.getBranch().some((entry) => entry.type === "custom_message" && entry.customType === BOOT_TYPE && entry.details?.windowId === windowId), "notification follows the reset boot commit");
                 }
-                if (message.includes("context budget low") || message.includes("context budget critical")) {
-                    const customType = message.includes("context budget critical") ? WARNING_TYPE : GUIDANCE_TYPE;
-                    assert.ok(sessionManager.getBranch().some((entry) => entry.type === "custom_message" && entry.customType === customType), "budget notifications follow the reminder commit");
-                }
+                if (type === "warning" && sessionManager.getBranch().some((entry) => entry.type === "custom_message" && (entry.customType === GUIDANCE_TYPE || entry.customType === WARNING_TYPE)))
+                    budgetNotices++;
                 notices.push(message);
             },
         },
@@ -145,6 +144,7 @@ async function openFixture(options) {
         streamSignals,
         events,
         notices,
+        budgetNotices: () => budgetNotices,
         close: () => {
             session.dispose();
             if (managesEnvironment) {
@@ -211,6 +211,7 @@ function assertFreshRequest(fixture, requestIndex, oldSentinel) {
     const body = text(fixture.requests[requestIndex]);
     assert.equal(body.includes(oldSentinel), false, "the new provider request excludes the old window transcript");
     assert.ok(body.includes(CONTEXT_WINDOW_OPEN_TAG), "the new provider request includes the fresh context-window boot");
+    assert.equal(body.split(CONTINUATION).length - 1, 1, "the fresh window carries exactly one reset message");
 }
 test("real AgentSession: aborted low-budget requests notify only after a retry commits the reminder", async () => {
     let fixture;
@@ -220,22 +221,22 @@ test("real AgentSession: aborted low-budget requests notify only after a retry c
     });
     try {
         const reminders = () => fixture.sessionManager.getBranch().filter((entry) => entry.type === "custom_message" && entry.customType === GUIDANCE_TYPE);
-        const notices = () => fixture.notices.filter((message) => message.includes("context budget low"));
+        const notices = () => fixture.budgetNotices();
         await fixture.session.prompt("Establish usage below the reminder line.");
         await fixture.session.waitForIdle();
         assert.equal(reminders().length, 0);
         await fixture.session.prompt("Abort this low-budget request.");
         await fixture.session.waitForIdle();
         assert.equal(reminders().length, 0, "an aborted turn does not commit its reminder");
-        assert.equal(notices().length, 0, "an uncommitted reminder never notifies");
+        assert.equal(notices(), 0, "an uncommitted reminder never notifies");
         await fixture.session.prompt("Retry successfully.");
         await fixture.session.waitForIdle();
         assert.equal(reminders().length, 1);
-        assert.equal(notices().length, 1, "the committed retry notifies once");
+        assert.equal(notices(), 1, "the committed retry notifies once");
         await fixture.session.prompt("Continue in the same window.");
         await fixture.session.waitForIdle();
         assert.equal(reminders().length, 1);
-        assert.equal(notices().length, 1, "later turns cannot repeat the notice");
+        assert.equal(notices(), 1, "later turns cannot repeat the notice");
     }
     finally {
         fixture.close();
@@ -610,6 +611,7 @@ test("real AgentSession: concurrent trusted projects keep reserve and automatic
         ]);
         await Promise.all([automatic.session.waitForIdle(), modelInvalidated.session.waitForIdle(), sessionInvalidated.session.waitForIdle()]);
         assert.equal(resetMarkers(automatic).length, 1, "the low reserve and enabled project resets automatically");
+        assert.equal(automatic.sessionManager.getBranch().filter((entry) => entry.type === "custom_message" && entry.customType === CONTINUATION_TYPE).length, 1, "the automatic reset persists exactly one continuation");
         assert.equal(resetMarkers(modelInvalidated).length, 0, "the high reserve and disabled project does not reset");
         assert.equal(resetMarkers(sessionInvalidated).length, 0, "the second high reserve and disabled session does not reset");
         writeFileSync(join(cwdModel, ".pi", "settings.json"), JSON.stringify({ compaction: { enabled: true, reserveTokens: 20_000 } }));

package/dist/test/boot.integration.test.js

@@ -58,6 +58,7 @@ test("the root boot and reset boot carry durable window identity", async () => {
     assert.deepEqual(rootBoot?.message.details, { windowId: `pcw:${sessionManager.getSessionId().slice(0, 8)}:root` });
     const rootText = typeof rootBoot?.message.content === "string" ? rootBoot.message.content : "";
     assert.ok(rootText.startsWith(internal.CONTEXT_WINDOW_OPEN_TAG), "root block omits the reset line");
+    assert.equal(rootText.includes(internal.CONTINUATION), false, "root startup carries no reset message");
     assert.equal(rootText.includes("Previous context window id:"), false, "root block omits the previous-id line");
     assert.match(rootText, new RegExp(`First context window id: pcw:${sessionManager.getSessionId().slice(0, 8)}:root`));
     assert.match(rootText, new RegExp(`Current context window id: pcw:${sessionManager.getSessionId().slice(0, 8)}:root`));
@@ -84,7 +85,7 @@ test("the root boot and reset boot carry durable window identity", async () => {
     const continuation = entries.find((entry) => entry.type === "custom_message" && entry.customType === CONTINUATION_TYPE);
     assert.ok(continuation && continuation.type === "custom_message" && continuation.display === false, "the resumed run is represented by one hidden continuation");
 });
-test("a marker tail with only metadata repairs its missing boot without moving the boundary", () => {
+test("a marker tail with only metadata repairs its missing boot and continuation without moving the boundary", () => {
     const sessionManager = manager(true);
     const windowId = "pcw:metadata-tail";
     const markerId = sessionManager.appendCustomEntry(internal.RESET_MARKER_TYPE, { windowId });
@@ -96,11 +97,60 @@ test("a marker tail with only metadata repairs its missing boot without moving t
     const branch = sessionManager.getBranch();
     const markerIndex = branch.findIndex((entry) => entry.id === markerId);
     const bootEntries = branch.filter((entry) => entry.type === "custom_message" && entry.customType === internal.BOOT_TYPE && entry.details && typeof entry.details === "object" && entry.details.windowId === windowId);
+    const continuationEntries = branch.filter((entry) => entry.type === "custom_message" && entry.customType === CONTINUATION_TYPE);
     assert.equal(bootEntries.length, 1, "an incomplete marker tail gets one repaired boot");
+    assert.equal(continuationEntries.length, 1, "the same repair completes the missing continuation");
     assert.ok(branch.findIndex((entry) => entry.id === modelChangeId) > markerIndex, "metadata remains after the marker");
     assert.ok(branch.findIndex((entry) => entry.id === bootEntries[0]?.id) > markerIndex, "the repaired boot remains in the marked window");
-    assert.equal(captured.sent.length, 1, "repair emits one hidden boot without a model turn");
-    assert.equal(noticesOf(ctx).length, 0, "repairing a boot is not a new reset");
+    assert.ok(branch.findIndex((entry) => entry.id === continuationEntries[0]?.id) > branch.findIndex((entry) => entry.id === bootEntries[0]?.id), "the continuation follows its boot");
+    assert.equal(captured.sent.length, 2, "repair emits only the missing boot and continuation, without a model turn");
+    assert.equal(captured.sent[0]?.message.customType, internal.BOOT_TYPE);
+    assert.equal(captured.sent[1]?.message.customType, CONTINUATION_TYPE);
+    assert.equal(noticesOf(ctx).length, 0, "repairing a reset tail is not a new reset");
+});
+test("a bare marker tail repairs the full ordered reset shape", () => {
+    const sessionManager = manager(true);
+    const windowId = "pcw:bare-marker";
+    const markerId = sessionManager.appendCustomEntry(internal.RESET_MARKER_TYPE, { windowId });
+    const captured = makeExtension(sessionManager);
+    const ctx = context(sessionManager);
+    runHandlers(captured, "session_start", { reason: "startup" }, ctx);
+    assert.equal(captured.sent.length, 2, "a bare marker emits a boot and a continuation");
+    const branch = sessionManager.getBranch();
+    const markerIndex = branch.findIndex((entry) => entry.id === markerId);
+    const bootIndex = branch.findIndex((entry) => entry.type === "custom_message" && entry.customType === internal.BOOT_TYPE && entry.details?.windowId === windowId);
+    const continuationIndex = branch.findIndex((entry) => entry.type === "custom_message" && entry.customType === CONTINUATION_TYPE);
+    assert.ok(bootIndex > markerIndex, "the repaired boot follows its marker");
+    assert.ok(continuationIndex > bootIndex, "the repaired continuation follows its boot");
+});
+test("a marker tail that already carries a boot repairs only its missing continuation, once", () => {
+    const sessionManager = manager(true);
+    const windowId = "pcw:missing-continuation";
+    const markerId = sessionManager.appendCustomEntry(internal.RESET_MARKER_TYPE, { windowId });
+    sessionManager.appendModelChange("openai", "scripted-model");
+    sessionManager.appendCustomMessageEntry(internal.BOOT_TYPE, "already-persisted boot", false, { windowId });
+    const captured = makeExtension(sessionManager);
+    const ctx = context(sessionManager);
+    runHandlers(captured, "session_start", { reason: "startup" }, ctx);
+    assert.equal(captured.sent.length, 1, "only the missing continuation is emitted");
+    assert.equal(captured.sent[0]?.message.customType, CONTINUATION_TYPE);
+    assert.equal(sessionManager.getBranch().filter((entry) => entry.type === "custom_message" && entry.customType === internal.BOOT_TYPE).length, 1, "the existing boot is never duplicated");
+    assert.ok(sessionManager.getBranch().findIndex((entry) => entry.id === markerId) >= 0);
+    runHandlers(captured, "session_start", { reason: "reload" }, ctx);
+    assert.equal(captured.sent.length, 1, "a complete reset tail is idempotent");
+    assert.equal(sessionManager.getBranch().filter((entry) => entry.type === "custom_message" && entry.customType === CONTINUATION_TYPE).length, 1);
+});
+test("a marker tail followed by real conversation is never repaired", () => {
+    const sessionManager = manager(true);
+    const windowId = "pcw:unsafe-tail";
+    sessionManager.appendCustomEntry(internal.RESET_MARKER_TYPE, { windowId });
+    appendText(sessionManager, "user", "post-marker work that must not be pushed behind a late boot");
+    const captured = makeExtension(sessionManager);
+    const ctx = context(sessionManager);
+    runHandlers(captured, "session_start", { reason: "startup" }, ctx);
+    assert.equal(captured.sent.length, 0, "an unsafe marker tail emits nothing");
+    assert.equal(sessionManager.getBranch().filter((entry) => entry.type === "custom_message" && entry.customType === internal.BOOT_TYPE).length, 0, "no boot is appended after real work");
+    assert.equal(sessionManager.getBranch().filter((entry) => entry.type === "custom_message" && entry.customType === CONTINUATION_TYPE).length, 0, "no continuation is appended after real work");
 });
 test("off preserves an existing marker window and still cancels native compaction", async () => {
     const sessionManager = manager();
@@ -152,8 +202,10 @@ test("pi-context command toggles future work, /wipe-memory is the manual path, a
     notices = await runCommand(captured, "wipe-memory", "", low);
     assert.equal(notices.length, 1, "manual clear emits exactly one notification");
     assert.match(notices[0]?.message ?? "", /memory cleared/);
-    assert.equal(captured.sent.length, 2, "/wipe-memory writes one hidden boot without triggering a model turn");
+    assert.equal(captured.sent.length, 3, "/wipe-memory writes one hidden boot and one continuation without triggering a model turn");
     assert.equal(captured.sent[1]?.options?.triggerTurn, false);
+    assert.equal(captured.sent[1]?.message.customType, internal.BOOT_TYPE);
+    assert.equal(captured.sent[2]?.message.customType, CONTINUATION_TYPE);
     assert.equal(sessionManager.getBranch().filter((entry) => entry.type === "custom" && entry.customType === internal.RESET_MARKER_TYPE).length, 1);
     const markerContext = await runManualCompact(captured, low);
     assert.deepEqual(markerContext, { cancel: true }, "/compact is canceled while a marker is active");

package/dist/test/helpers/extension.js

@@ -130,14 +130,13 @@ export function makeExtension(sessionManager, settingsManager) {
     (settingsManager ? createPiContext({ settingsManager }) : piContext)(api);
     return captured;
 }
-export function explicitBoot(ctx, currentWindowId, previousWindowId, resetLine) {
+export function explicitBoot(ctx, currentWindowId, previousWindowId) {
     return renderBootBlock({
         agentName: agentSlug(ctx),
         modelName: modelSlug(ctx),
         firstWindowId: rootWindowId(ctx.sessionManager.getSessionId()),
         currentWindowId,
         previousWindowId,
-        resetLine,
         notes: loadNotesSnapshot(ctx),
     });
 }

package/dist/test/notes.integration.test.js

@@ -130,7 +130,6 @@ test("boot note acquisition is one closed snapshot and isolates one or all faile
         firstWindowId: "pcw:test:root",
         currentWindowId: "pcw:test:next",
         previousWindowId: "pcw:test:root",
-        resetLine: true,
         notes: snapshot,
     };
     const rendered = renderBootBlock(renderData);
@@ -150,7 +149,6 @@ test("boot note acquisition is one closed snapshot and isolates one or all faile
         modelName: "default",
         firstWindowId: "pcw:test:root",
         currentWindowId: "pcw:test:next",
-        resetLine: true,
         notes: oneFailed,
     });
     assert.ok(oneFailedText.includes("PROJECT_MAP_BODY") && oneFailedText.includes("notes_list can retry after recovery"), "healthy homes and the recovery notice survive one failure");
@@ -165,7 +163,6 @@ test("boot note acquisition is one closed snapshot and isolates one or all faile
         firstWindowId: "pcw:test:root",
         currentWindowId: "pcw:test:next",
         previousWindowId: "pcw:test:root",
-        resetLine: true,
         notes: allFailed,
     });
     assert.ok(allFailedText.includes("pcw:test:root") && allFailedText.includes("pcw:test:next"), "identity survives an all-home failure");
@@ -176,7 +173,7 @@ test("boot note acquisition is one closed snapshot and isolates one or all faile
 });
 test("the boot block gives awake agents the notes-home file layout", () => {
     const session = manager();
-    const rendered = explicitBoot(context(session), "pcw:test:root", undefined, false);
+    const rendered = explicitBoot(context(session), "pcw:test:root", undefined);
     assert.equal(rendered.includes(process.env.PI_NOTES_HOME ?? ""), false, "the absolute notes home is never exposed");
     assert.match(rendered, /bare <vpath>.*@project\/<vpath>.*@human\/<vpath>/);
 });

package/dist/test/notes.test.js

@@ -205,8 +205,8 @@ test("@ addresses select one home, reject illegal sigils, and never fall back",
     assert.ok(existsSync(physicalPath("human", "same.md", ctx)), "@human writes to the human home");
     assert.match(resultRead(await call(captured, "notes_read", { address: "same.md" }, ctx)).content, /session$/);
     assert.equal(resultJson(await call(captured, "notes_read", { address: "@project/missing.md" }, ctx)).error, "note not found");
-    await assert.rejects(() => call(captured, "notes_read", { address: "@glboal/same.md" }, ctx), /@project\/.*@human\/.*bare names are the session home/);
-    await assert.rejects(() => call(captured, "notes_write", { address: "bad@name.md", content: "no" }, ctx), /@project\/.*@human\/.*bare names are the session home/);
+    await assert.rejects(() => call(captured, "notes_read", { address: "@glboal/same.md" }, ctx), /@project\/.*@human\/.*bare names are this session/);
+    await assert.rejects(() => call(captured, "notes_write", { address: "bad@name.md", content: "no" }, ctx), /@project\/.*@human\/.*bare names are this session/);
     assert.equal(existsSync(join(root, "human", "bad@name.md")), false, "a bad sigil creates nothing anywhere");
 });
 const FRONTMATTER = (body) => `---\norigin: self\nstatus: active\nstale: false\ncreated_at: 2026-01-01T00:00:00.000+00:00\nupdated_at: 2026-01-01T00:00:00.000+00:00\nlast_accessed: 2026-01-01T00:00:00.000+00:00\naccess_count: 0\n---\n\n${body}`;

package/dist/test/reset-lifecycle.test.js

@@ -5,7 +5,7 @@ import { join } from "node:path";
 import test from "node:test";
 import { SessionManager as Manager } from "@earendil-works/pi-coding-agent";
 import piContext, { internal } from "../src/index.js";
-import { registerResetLifecycle } from "../src/context/reset-lifecycle.js";
+import { initialResetControl, reduceResetControl, registerResetLifecycle, } from "../src/context/reset-lifecycle.js";
 const previousNotesHome = process.env.PI_NOTES_HOME;
 const testNotesHome = mkdtempSync(join(tmpdir(), "pi-context-lifecycle-notes-"));
 process.env.PI_NOTES_HOME = testNotesHome;
@@ -107,6 +107,27 @@ function appendDrafts(sessionManager, entries) {
         }
     }
 }
+function turnEndFacts(overrides = {}) {
+    return {
+        aborted: false,
+        overflow: false,
+        failed: false,
+        enabled: true,
+        queued: false,
+        automaticResetEnabled: true,
+        thresholdDue: false,
+        ...overrides,
+    };
+}
+function beforeSettleFacts(overrides = {}) {
+    return {
+        queued: false,
+        enabled: true,
+        automaticResetEnabled: true,
+        aborted: false,
+        ...overrides,
+    };
+}
 function fakeBoundaryEvent(entries = []) {
     return {
         type: "turn_end",
@@ -140,6 +161,9 @@ test("public reset boundary drafts one marker, one boot, and one continuation af
     const windowId = markerDrafts[0].data.windowId;
     assert.match(windowId, /^pcw:/);
     assert.equal(bootDrafts[0].details.windowId, windowId);
+    const continuationDrafts = boundary.entries.filter((entry) => entry.type === "custom_message" && entry.customType === internal.CONTINUATION_TYPE);
+    assert.equal(continuationDrafts.length, 1, "the boundary persists exactly one reset message");
+    assert.equal(boundary.entries[3]?.type, "custom_message", "the continuation closes the ordered reset shape");
     appendDrafts(h.sessionManager, boundary.entries);
     const branch = h.sessionManager.getBranch();
     assert.deepEqual(branch.filter((entry) => entry.type === "custom" && entry.customType === internal.RESET_MARKER_TYPE).map((entry) => entry.type === "custom" ? entry.data : undefined), [{ windowId }]);
@@ -165,8 +189,10 @@ test("off stops future automatic/manual reset requests while an existing marker
     assert.equal(afterOff.entries.length, 0, "off does not create another reset");
     await h.runCommand("pi-context", "on");
     await h.runCommand("wipe-memory");
-    assert.equal(h.sent.length, 1, "/wipe-memory writes one hidden boot without a model turn");
+    assert.equal(h.sent.length, 2, "/wipe-memory writes one hidden boot and one continuation without a model turn");
     assert.equal(h.sent[0]?.triggerTurn, false);
+    assert.equal(h.sent[0]?.customType, internal.BOOT_TYPE);
+    assert.equal(h.sent[1]?.customType, internal.CONTINUATION_TYPE);
     const markers = h.sessionManager.getBranch().filter((entry) => entry.type === "custom" && entry.customType === internal.RESET_MARKER_TYPE);
     assert.equal(markers.length, 2, "off does not resurrect history; re-enabled wipe-memory creates the explicit new marker");
 });
@@ -262,3 +288,174 @@ test("a queued success clears an overflow failure before settle recovery can res
     assert.equal(await beforeSettle(settled, ctx), undefined, "the successful queued turn clears the stale recovery");
     assert.equal(resetCount, 0);
 });
+test("reset-control: an explicit request deduplicates and is consumed at the turn boundary", () => {
+    const idle = Object.freeze({ ...initialResetControl() });
+    const first = reduceResetControl(idle, { type: "request" });
+    assert.equal(first.effect, "requested");
+    assert.deepEqual(first.state, { request: "explicit", overflow: "idle" });
+    const again = reduceResetControl(first.state, { type: "request" });
+    assert.equal(again.effect, "already-requested");
+    assert.deepEqual(again.state, first.state, "a duplicate request does not change state");
+    const committed = reduceResetControl(again.state, { type: "turn_end", facts: turnEndFacts() });
+    assert.equal(committed.effect, "commit-boundary");
+    assert.deepEqual(committed.state, initialResetControl(), "the request is consumed whether or not it commits");
+});
+test("reset-control: turn_end commits explicit and threshold resets, and skips disabled or failed turns", () => {
+    const explicit = reduceResetControl({ request: "explicit", overflow: "idle" }, { type: "turn_end", facts: turnEndFacts() });
+    assert.equal(explicit.effect, "commit-boundary");
+    const threshold = reduceResetControl(initialResetControl(), { type: "turn_end", facts: turnEndFacts({ thresholdDue: true }) });
+    assert.equal(threshold.effect, "commit-boundary");
+    const neither = reduceResetControl(initialResetControl(), { type: "turn_end", facts: turnEndFacts() });
+    assert.equal(neither.effect, "none");
+    const disabled = reduceResetControl({ request: "explicit", overflow: "idle" }, { type: "turn_end", facts: turnEndFacts({ enabled: false, thresholdDue: true }) });
+    assert.equal(disabled.effect, "none");
+    assert.deepEqual(disabled.state, initialResetControl(), "a disabled turn drops the explicit request without committing");
+    const failed = reduceResetControl({ request: "explicit", overflow: "idle" }, { type: "turn_end", facts: turnEndFacts({ failed: true, thresholdDue: true }) });
+    assert.equal(failed.effect, "none");
+    assert.deepEqual(failed.state, initialResetControl());
+});
+test("reset-control: aborted turns clear the boundary, settlement keeps only an explicit request", () => {
+    const both = { request: "explicit", overflow: "pending" };
+    const aborted = reduceResetControl(both, { type: "turn_end", facts: turnEndFacts({ aborted: true }) });
+    assert.equal(aborted.effect, "none");
+    assert.deepEqual(aborted.state, initialResetControl(), "an abort manufactures no continuation");
+    const settled = reduceResetControl(both, { type: "settled" });
+    assert.deepEqual(settled.state, { request: "explicit", overflow: "idle" }, "settlement ends the failure chain only");
+    const cleared = reduceResetControl(both, { type: "clear" });
+    assert.deepEqual(cleared.state, initialResetControl());
+});
+test("reset-control: overflow recovery is armed at turn_end and spent exactly once at settle", () => {
+    const armed = reduceResetControl(initialResetControl(), { type: "turn_end", facts: turnEndFacts({ overflow: true, failed: true }) });
+    assert.deepEqual(armed.state, { request: "none", overflow: "pending" });
+    const recovered = reduceResetControl(armed.state, { type: "before_settle", facts: beforeSettleFacts() });
+    assert.equal(recovered.effect, "recover-overflow", "the first settle commits the bounded recovery");
+    assert.deepEqual(recovered.state, { request: "none", overflow: "spent" });
+    const repeated = reduceResetControl(recovered.state, { type: "before_settle", facts: beforeSettleFacts() });
+    assert.equal(repeated.effect, "none", "a spent recovery is never retried");
+    const rearmed = reduceResetControl(recovered.state, { type: "turn_end", facts: turnEndFacts({ overflow: true, failed: true }) });
+    assert.deepEqual(rearmed.state, { request: "none", overflow: "pending-spent" });
+    const bounded = reduceResetControl(rearmed.state, { type: "before_settle", facts: beforeSettleFacts() });
+    assert.equal(bounded.effect, "none", "a second failure chain stays bounded to the spent attempt");
+    assert.deepEqual(bounded.state, { request: "none", overflow: "spent" });
+});
+test("reset-control: a queued turn defers recovery and its success supersedes the failure", () => {
+    const armed = reduceResetControl(initialResetControl(), { type: "turn_end", facts: turnEndFacts({ overflow: true, failed: true }) }).state;
+    const deferred = reduceResetControl(armed, { type: "before_settle", facts: beforeSettleFacts({ queued: true }) });
+    assert.equal(deferred.effect, "none");
+    assert.deepEqual(deferred.state, armed, "a queued message leaves the overflow chain armed");
+    const success = reduceResetControl(armed, { type: "turn_end", facts: turnEndFacts() });
+    assert.deepEqual(success.state, initialResetControl(), "a successful queued turn clears the stale failure");
+});
+test("reset-control: disabled mode and explicit aborts disarm overflow without a recovery", () => {
+    const armed = reduceResetControl(initialResetControl(), { type: "turn_end", facts: turnEndFacts({ overflow: true, failed: true }) }).state;
+    const disabled = reduceResetControl(armed, { type: "before_settle", facts: beforeSettleFacts({ enabled: false }) });
+    assert.equal(disabled.effect, "none");
+    assert.deepEqual(disabled.state, { request: "none", overflow: "idle" });
+    const automaticOff = reduceResetControl(armed, { type: "before_settle", facts: beforeSettleFacts({ automaticResetEnabled: false }) });
+    assert.equal(automaticOff.effect, "none");
+    assert.deepEqual(automaticOff.state, { request: "none", overflow: "idle" });
+    const aborted = reduceResetControl(armed, { type: "before_settle", facts: beforeSettleFacts({ aborted: true }) });
+    assert.equal(aborted.effect, "none");
+    assert.deepEqual(aborted.state, { request: "none", overflow: "idle" });
+});
+test("reset-control: policy guards are consulted only in the branches that need them", () => {
+    const tracked = (overrides) => {
+        const calls = { queued: 0, automatic: 0, threshold: 0 };
+        const facts = {
+            aborted: overrides.aborted ?? false,
+            overflow: overrides.overflow ?? false,
+            failed: overrides.failed ?? false,
+            enabled: overrides.enabled ?? true,
+            get queued() { calls.queued += 1; return overrides.queuedResult ?? false; },
+            get automaticResetEnabled() { calls.automatic += 1; return overrides.automaticResult ?? true; },
+            get thresholdDue() { calls.threshold += 1; return overrides.thresholdResult ?? true; },
+        };
+        return { facts, calls };
+    };
+    const aborted = tracked({ aborted: true });
+    reduceResetControl(initialResetControl(), { type: "turn_end", facts: aborted.facts });
+    assert.deepEqual(aborted.calls, { queued: 0, automatic: 0, threshold: 0 }, "an abort consults no policy guard");
+    const failed = tracked({ failed: true });
+    reduceResetControl(initialResetControl(), { type: "turn_end", facts: failed.facts });
+    assert.deepEqual(failed.calls, { queued: 0, automatic: 0, threshold: 0 }, "a failed turn consults no threshold guard");
+    const disabled = tracked({ enabled: false });
+    reduceResetControl(initialResetControl(), { type: "turn_end", facts: disabled.facts });
+    assert.deepEqual(disabled.calls, { queued: 0, automatic: 0, threshold: 0 }, "a disabled turn consults no threshold guard");
+    const overflow = tracked({ overflow: true, queuedResult: false });
+    reduceResetControl(initialResetControl(), { type: "turn_end", facts: overflow.facts });
+    assert.deepEqual(overflow.calls, { queued: 1, automatic: 1, threshold: 0 }, "an overflow turn consults only the overflow guards");
+    const complete = tracked({ thresholdResult: false });
+    reduceResetControl(initialResetControl(), { type: "turn_end", facts: complete.facts });
+    assert.deepEqual(complete.calls, { queued: 0, automatic: 0, threshold: 1 }, "a completed turn consults only the threshold guard");
+    const settleCalls = { queued: 0, enabled: 0, automatic: 0 };
+    const settleFacts = {
+        get queued() { settleCalls.queued += 1; return true; },
+        get enabled() { settleCalls.enabled += 1; return true; },
+        get automaticResetEnabled() { settleCalls.automatic += 1; return true; },
+        aborted: false,
+    };
+    reduceResetControl({ request: "none", overflow: "pending" }, { type: "before_settle", facts: settleFacts });
+    assert.deepEqual(settleCalls, { queued: 1, enabled: 0, automatic: 0 }, "a queued settle consults only the pending-message guard");
+});
+test("a committed reset places incoming and budget drafts before marker -> boot -> continuation", async () => {
+    const sessionManager = Manager.inMemory("/private/tmp/pi-context-reset-ordering-test");
+    const handlers = new Map();
+    const api = {
+        on(name, handler) {
+            const list = handlers.get(name) ?? [];
+            list.push(handler);
+            handlers.set(name, list);
+            return () => { };
+        },
+    };
+    const ctx = {
+        sessionManager,
+        model: undefined,
+        signal: undefined,
+        hasPendingMessages: () => false,
+        ui: { notify() { } },
+    };
+    const windowId = "pcw:ordering:test";
+    const budgetDraft = { type: "custom_message", customType: internal.GUIDANCE_TYPE, content: "budget draft", display: false };
+    const lifecycle = registerResetLifecycle(api, {
+        isEnabled: () => true,
+        budget: {
+            automaticResetEnabled: () => true,
+            resetDue: () => false,
+            consumeTurnEnd: () => [budgetDraft],
+            clear: () => { },
+        },
+        buildReset: () => [
+            { type: "custom", customType: internal.RESET_MARKER_TYPE, data: { windowId } },
+            { type: "custom_message", customType: internal.BOOT_TYPE, content: "boot", display: false, details: { windowId } },
+            { type: "custom_message", customType: internal.CONTINUATION_TYPE, content: "continuation", display: false },
+        ],
+    });
+    lifecycle.request();
+    const incoming = { type: "custom_message", customType: "foreign/boundary", content: "incoming", display: false };
+    const results = [];
+    for (const handler of handlers.get("turn_end") ?? [])
+        results.push(await handler(fakeBoundaryEvent([incoming]), ctx));
+    const result = resultEntries(results);
+    assert.equal(result.continue, true);
+    const customTypes = (entries) => entries.map((entry) => {
+        assert.ok(entry.type === "custom" || entry.type === "custom_message", "the boundary only carries named reset drafts here");
+        return entry.customType;
+    });
+    assert.deepEqual(customTypes(result.entries), [
+        "foreign/boundary",
+        internal.GUIDANCE_TYPE,
+        internal.RESET_MARKER_TYPE,
+        internal.BOOT_TYPE,
+        internal.CONTINUATION_TYPE,
+    ], "ordinary and budget drafts precede the closed reset shape");
+    appendDrafts(sessionManager, result.entries);
+    const branch = sessionManager.getBranch();
+    const markerIndex = branch.findIndex((entry) => entry.type === "custom" && entry.customType === internal.RESET_MARKER_TYPE);
+    assert.ok(markerIndex >= 0);
+    assert.deepEqual(customTypes(branch.slice(markerIndex)), [
+        internal.RESET_MARKER_TYPE,
+        internal.BOOT_TYPE,
+        internal.CONTINUATION_TYPE,
+    ], "the persisted reset shape remains marker -> boot -> continuation");
+});

package/docs/reset-lifecycle.md

@@ -13,6 +13,63 @@
 | Startup / tree / partial append | Repair only a marker followed by an otherwise empty metadata tail; refuse hidden/absent boots once later work exists, leaving `/wipe-memory` as the explicit recovery path. Do not interpret legacy reset-v2 details. |
 | `/pi-context off` | Stop new automatic resets, but retain the boundary of an existing marker. Marked branches still cancel native compaction; a fresh root may use Pi's native semantics. |
 
+## Reset-control state machine
+
+`registerResetLifecycle` is the effect adapter. `reduceResetControl` in `src/context/reset-lifecycle.ts` is the pure transition surface: given the current state and one lifecycle event it returns the next state and one named effect, performing no writes, policy resolution, or UI work of its own. The adapter captures Pi's events, supplies the guards only in the branches that consult them, then performs the marker/boot/continuation writes, continuation requests, and notices.
+
+State is a single value with two explicitly typed axes. There are no independently combinable lifecycle booleans.
+
+| Axis | Value | Meaning |
+| --- | --- | --- |
+| `request` | `none` | no explicit wipe request pending |
+| | `explicit` | one explicit request is pending and will commit at the next `turn_end` |
+| `overflow` | `idle` | no overflow failure pending; a future recovery is available |
+| | `pending` | active-provider overflow failure pending; recovery still available |
+| | `pending-spent` | overflow failure pending, but its one recovery was already spent |
+| | `spent` | recovery spent and the failure is no longer pending |
+
+All eight combinations of the two axes are reachable and each has a defined transition.
+
+| Event | Guard | Next state | Effect |
+| --- | --- | --- | --- |
+| `request` | `request=none` | `request=explicit`, overflow unchanged | `requested` |
+| `request` | `request=explicit` | unchanged | `already-requested` |
+| `turn_end` | turn aborted | `(request=none, overflow=idle)` | `none` |
+| `turn_end` | overflow-like and `!queued && enabled && automaticResetEnabled` | `request=none`; overflow `pending`, or `pending-spent` if already spent | `none` |
+| `turn_end` | overflow-like and (`queued \|\| !enabled \|\| !automaticResetEnabled`) | `request=none`; overflow `idle`, or `spent` if already spent | `none` |
+| `turn_end` | completed, `enabled`, and (`explicit` requested or `thresholdDue`) | `(request=none, overflow=idle)` | `commit-boundary` |
+| `turn_end` | completed, `enabled`, but neither trigger | `(request=none, overflow=idle)` | `none` |
+| `turn_end` | non-overflow `failed` | `request=none`; overflow unchanged | `none` |
+| `turn_end` | `!enabled` | `request=none`; completed clears overflow, error keeps it | `none` |
+| `before_settle` | `overflow=pending`, not queued, `enabled`, `automaticResetEnabled`, not aborted | `overflow=spent` | `recover-overflow` |
+| `before_settle` | `overflow=pending-spent` | `overflow=spent` | `none` |
+| `before_settle` | `overflow` not pending, or queued | unchanged | `none` |
+| `before_settle` | pending but `!enabled`, `!automaticResetEnabled`, or aborted | disarms to `idle` (`spent` if already spent) | `none` |
+| `settled` | — | `overflow=idle`; `request` unchanged | `none` |
+| `abort` / `clear` | — | `(request=none, overflow=idle)` | `none` |
+
+### Invariants
+
+1. At most one explicit request is pending at a time; duplicate requests in one tool batch dedupe and never queue a second boundary.
+2. Every `turn_end` consumes a pending explicit request, whether or not that turn commits a reset.
+3. A committed reset is exactly `marker -> boot -> continuation`, and ordinary and budget drafts are ordered before the marker. Budget staging is drained once per turn and discarded on abort or disabled mode.
+4. Reset drafts are built once per commit. If construction throws, already-built incoming and budget drafts survive and no continuation is requested.
+5. Overflow recovery is one attempt per failure chain: a failure arms `pending` only when nothing is queued, the extension is enabled, and automatic reset is enabled; a settle spends it to `spent`; a later failure becomes `pending-spent` and cannot recover again until settlement ends the chain.
+6. Aborted turns never manufacture a continuation and clear both axes. Non-overflow errors keep the armed overflow chain for the settle boundary.
+7. A successful non-overflow turn clears the overflow chain first, so a queued success supersedes a stale overflow failure before settle recovery can act.
+8. `settled` ends the failure chain but preserves a pending explicit request; `clear` (session start, tree navigation, shutdown, `/pi-context off`, `/wipe-memory`) resets both axes.
+9. Disabled mode never commits a reset and never arms or spends overflow recovery; an existing persisted marker stays authoritative for native-compaction cancellation.
+10. Policy guards (`queued`, `automaticResetEnabled`, `thresholdDue`) are consulted only in the branch that needs them, preserving the adapter's original resolution order.
+
+### Critical sequences
+
+- **Normal reset.** A completed, enabled turn whose explicit request is pending or whose usage is due returns `commit-boundary`. The adapter drains budget drafts, keeps incoming drafts in order, appends `marker -> boot -> continuation`, and requests continuation. A second request in the same batch returns `already-requested`; the next turn commits it alone.
+- **Overflow recovery.** An overflow-like `turn_end` with no queued message, enabled mode, and automatic reset arms `pending`; a `before_settle` with no queued message returns `recover-overflow` and spends the attempt to `spent`. A repeated settle is a no-op, and a later overflow failure re-arms only `pending-spent`.
+- **Abort.** An aborted `turn_end` returns only the drafts already collected for that boundary, clears both axes, and never appends reset drafts.
+- **Queued success.** A queued message defers `before_settle`; the queued turn's successful `turn_end` clears the stale overflow chain, so no recovery fires.
+- **Process interruption.** If Pi stops between the marker and the later reset messages, the marker remains the authoritative boundary. On the next start, startup repair may append only the missing boot and continuation when the tail is otherwise repairable; it never moves or reinterprets the boundary.
+- **Startup tail repair.** On `session_start` / `session_tree`, `ensureBoot` asks `repairResetTail` to inspect the marker tail and emit only the missing artifacts in the closed order: the boot, then the continuation. A boot/continuation sequence that is already complete, or a tail containing real conversation, a foreign message, a later marker, or a misordered/duplicate artifact, refuses repair and leaves `/wipe-memory` as the explicit recovery path.
+
 The budget owner stages the early guidance and final checkpoint warning from active-window usage. The warning is visible in the current provider request, while both drafts are committed only by the lifecycle composer and are discarded on abort, settlement without a `turn_end`, transition, or window mismatch. After the warning, the model either writes its note and calls `wipe_memory`, or runtime recovery requests the same marker/boot boundary. Guidance and warning drafts precede reset drafts so stale reminders cannot be queued into the new window; durable entries remain the authority for redelivery. Their UI notices are emitted at the next turn start or settlement only after the matching reminder is committed in the active window, so aborted requests and retries cannot repeat an uncommitted reminder's notification.
 
 The turn-end commit is the scheduling boundary: Pi receives the finished tool batch and then the marker/boot drafts as one append operation. Pi owns queue scheduling and deduplication of the next request; the extension does not run a parallel compaction state machine or use a compaction completion callback.

package/package.json

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