@astrosheep/pi-context 0.23.1 → 0.25.0

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

@@ -1,196 +1,264 @@
 import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import test from "node:test";
-import { registerResetLifecycle } from "../src/reset-lifecycle.js";
+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";
+const previousNotesHome = process.env.PI_NOTES_HOME;
+const testNotesHome = mkdtempSync(join(tmpdir(), "pi-context-lifecycle-notes-"));
+process.env.PI_NOTES_HOME = testNotesHome;
+test.after(() => {
+    if (previousNotesHome === undefined)
+        delete process.env.PI_NOTES_HOME;
+    else
+        process.env.PI_NOTES_HOME = previousNotesHome;
+    rmSync(testNotesHome, { recursive: true, force: true });
+});
 function harness() {
+    const sessionManager = Manager.inMemory("/private/tmp/pi-context-lifecycle-test");
     const handlers = new Map();
-    const messages = [];
+    const tools = new Map();
+    const commands = new Map();
+    const sent = [];
     const notices = [];
-    const requests = [];
-    let sessionId = "first", currentReset = "", enabled = true, idle = true, pending = false;
-    let signal;
-    let throwOnCompact = false;
-    const ctx = {
-        sessionManager: { getSessionId: () => sessionId },
-        isIdle: () => idle,
-        hasPendingMessages: () => pending,
-        get signal() { return signal; },
-        compact: (options) => {
-            if (throwOnCompact)
-                throw new Error("synchronous failure");
-            requests.push(options);
+    const api = {
+        on(name, handler) {
+            const list = handlers.get(name) ?? [];
+            list.push(handler);
+            handlers.set(name, list);
+            return () => { };
+        },
+        registerTool(tool) { tools.set(tool.name, tool); },
+        registerCommand(name, command) { commands.set(name, command); },
+        registerFlag() { },
+        appendEntry(customType, data) { sessionManager.appendCustomEntry(customType, data); },
+        sendMessage(message, options) {
+            sent.push({ customType: message.customType, details: message.details, triggerTurn: options?.triggerTurn });
+            sessionManager.appendCustomMessageEntry(message.customType, message.content, message.display, message.details);
         },
-        ui: { notify: (message) => notices.push(message) },
     };
-    const lifecycle = registerResetLifecycle({
-        on: (name, fn) => handlers.set(name, fn),
-        sendMessage: (message) => messages.push(message.customType),
-    }, {
-        isEnabled: () => enabled,
-        continuation: { customType: "continue", content: "resume", display: false },
-        buildReset: () => ({ compaction: { summary: "reset", firstKeptEntryId: "marker", tokensBefore: 100, details: {} } }),
-        isCurrentReset: (id) => id === currentReset,
-        onReset: () => { },
-    });
-    const emit = (name, event = {}) => handlers.get(name)?.(event, ctx);
+    piContext(api);
+    const ctx = {
+        sessionManager,
+        cwd: "/private/tmp",
+        model: undefined,
+        isIdle: () => true,
+        hasPendingMessages: () => false,
+        signal: undefined,
+        getContextUsage: () => undefined,
+        compact: () => assert.fail("the reset path must not call ctx.compact()"),
+        abort: () => { },
+        isProjectTrusted: () => true,
+        ui: { notify: (message, type) => notices.push({ message, type }) },
+    };
+    const emit = async (name, event) => {
+        const results = [];
+        for (const handler of handlers.get(name) ?? [])
+            results.push(await handler(event, ctx));
+        return results;
+    };
+    const runCommand = async (name, args = "") => {
+        const command = commands.get(name);
+        assert.ok(command, `${name} command is registered`);
+        const commandCtx = Object.assign({}, ctx, {
+            waitForIdle: async () => { },
+            ui: { notify: (message, type) => notices.push({ message, type }) },
+        });
+        await command.handler(args, commandCtx);
+    };
+    const callTool = async (name) => {
+        const tool = tools.get(name);
+        assert.ok(tool, `${name} is registered`);
+        return tool.execute("call", {}, new AbortController().signal, () => { }, ctx);
+    };
+    return { sessionManager, handlers, sent, notices, emit, runCommand, callTool };
+}
+function resultEntries(results) {
+    let entries = [];
+    let shouldContinue = false;
+    for (const result of results) {
+        if (!result || typeof result !== "object")
+            continue;
+        const value = result;
+        if (value.entries)
+            entries = value.entries;
+        if (value.continue !== undefined)
+            shouldContinue = value.continue;
+    }
+    return { entries, continue: shouldContinue };
+}
+function appendDrafts(sessionManager, entries) {
+    for (const entry of entries) {
+        switch (entry.type) {
+            case "custom":
+                sessionManager.appendCustomEntry(entry.customType, entry.data);
+                break;
+            case "custom_message":
+                sessionManager.appendCustomMessageEntry(entry.customType, entry.content, entry.display, entry.details);
+                break;
+            case "context_edit":
+                sessionManager.appendContextEdit(entry.targetId, entry.replacement);
+                break;
+            case "compaction":
+                sessionManager.appendCompaction(entry.summary, entry.firstKeptEntryId, 0, entry.details, true, entry.usage);
+                break;
+        }
+    }
+}
+function fakeBoundaryEvent(entries = []) {
     return {
-        ctx, lifecycle, emit, messages, notices, requests,
-        setIdle: (value) => { idle = value; },
-        setPending: (value) => { pending = value; },
-        setSignal: (value) => { signal = value; },
-        setSession: (value) => { sessionId = value; },
-        setThrow: () => { throwOnCompact = true; },
-        disable: () => { enabled = false; lifecycle.clear(); },
-        enable: () => { enabled = true; },
-        before: (reason = "threshold") => emit("session_before_compact", { reason, signal: new AbortController().signal }),
-        // Do not await this result until after the manually driven compact callbacks:
-        // real Pi awaits the originating handler while the continuation can emit its
-        // own nested agent_settled event.
-        settle: () => { emit("agent_end"); idle = true; return emit("agent_settled"); },
-        success: (id = "reset", willRetry = false) => {
-            currentReset = id;
-            emit("session_compact", { compactionEntry: { id }, willRetry });
-        },
-        complete: (index = 0) => requests[index].onComplete({}),
+        type: "turn_end",
+        entries,
+        continue: false,
+        context: { contextEntries: [], contextMessages: [], llmMessages: [], pendingMessages: [], canContinue: true },
+        outcome: "completed",
+        turnIndex: 0,
+        message: { role: "assistant", content: [], timestamp: Date.now() },
+        toolResults: [],
+        messageEntryId: "assistant-entry",
+        toolResultEntryIds: [],
     };
 }
-test("the originating settled handler waits for its continuation's nested settlement", async () => {
+test("public reset boundary drafts one marker, one boot, and one continuation after a tool batch", async () => {
     const h = harness();
-    assert.equal(h.lifecycle.request(), "rollover_requested");
-    assert.equal(h.lifecycle.request(), "rollover_already_pending");
-    const outer = h.settle();
-    assert.equal(h.requests.length, 1);
-    h.success();
-    h.success();
-    h.complete();
-    h.complete();
-    assert.deepEqual(h.messages, ["continue"], "one continuation starts after compaction completion");
-    let released = false;
-    void Promise.resolve(outer).then(() => { released = true; });
-    await Promise.resolve();
-    assert.equal(released, false, "sending the continuation does not release the original handler");
-    await h.settle();
-    await outer;
-    assert.equal(released, true, "only the continuation's settled event releases its owner");
-    assert.equal(h.requests.length, 1, "duplicate compact and settled callbacks do not restart reset work");
+    h.sessionManager.appendMessage({ role: "user", content: [{ type: "text", text: "before reset" }], timestamp: Date.now() });
+    const first = await h.callTool("wipe_memory");
+    const second = await h.callTool("wipe_memory");
+    assert.ok(first.content.length > 0 && second.content.length > 0, "both tool calls return normally");
+    const toolBatch = [{ type: "custom_message", customType: "foreign/tool-batch", content: "tool finished", display: false }];
+    const boundary = resultEntries(await h.emit("turn_end", fakeBoundaryEvent(toolBatch)));
+    assert.equal(boundary.continue, true, "the whole tool batch continues only after the boundary is committed");
+    const markerDrafts = boundary.entries.filter((entry) => entry.type === "custom" && entry.customType === internal.RESET_MARKER_TYPE);
+    const bootDrafts = boundary.entries.filter((entry) => entry.type === "custom_message" && entry.customType === internal.BOOT_TYPE);
+    assert.equal(markerDrafts.length, 1, "duplicate wipe requests in one turn dedupe");
+    assert.equal(bootDrafts.length, 1);
+    assert.equal(boundary.entries[0]?.type, "custom_message", "ordinary tool-batch entries precede the reset drafts");
+    assert.equal(boundary.entries[1]?.type, "custom");
+    assert.equal(boundary.entries[2]?.type, "custom_message");
+    const windowId = markerDrafts[0].data.windowId;
+    assert.match(windowId, /^pcw:/);
+    assert.equal(bootDrafts[0].details.windowId, windowId);
+    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 }]);
+    assert.equal(branch.filter((entry) => entry.type === "custom_message" && entry.customType === internal.BOOT_TYPE).length, 1);
 });
-test("a reset requested by a continuation completes before its predecessor releases", async () => {
+test("off stops future automatic/manual reset requests while an existing marker remains authoritative", async () => {
     const h = harness();
-    h.lifecycle.request();
-    const first = h.settle();
-    h.success("first");
-    h.complete();
-    assert.deepEqual(h.messages, ["continue"]);
-    // This models new_context being called during the first continuation run.
-    assert.equal(h.lifecycle.request(), "rollover_requested");
-    const second = h.settle();
-    assert.equal(h.requests.length, 2, "the continuation's settled handler starts its requested reset");
-    h.success("second");
-    h.complete(1);
-    assert.deepEqual(h.messages, ["continue", "continue"]);
-    let firstReleased = false;
-    void Promise.resolve(first).then(() => { firstReleased = true; });
-    await Promise.resolve();
-    assert.equal(firstReleased, false, "the predecessor remains owned while the second continuation runs");
-    await h.settle();
-    await second;
-    await first;
-    assert.equal(firstReleased, true);
-    assert.equal(h.lifecycle.request(), "rollover_requested", "a later window can request another reset");
-});
-test("automatic compactions reset on the spot, with no continuation", () => {
-    const h = harness();
-    assert.ok(h.before().compaction, "the native attempt becomes our reset immediately");
-    assert.deepEqual(h.messages, []);
-});
-test("failure, synchronous scheduling errors, and cancellation release their owners without retry", async () => {
-    const failed = harness();
-    failed.lifecycle.request();
-    const outer = failed.settle();
-    failed.requests[0].onError(new Error("Nothing to compact"));
-    failed.requests[0].onError(new Error("duplicate callback"));
-    failed.complete();
-    await outer;
-    assert.equal(failed.notices.length, 1);
-    assert.deepEqual(failed.messages, []);
-    assert.equal(failed.lifecycle.request(), "rollover_requested", "a later explicit request is possible");
-    const synchronous = harness();
-    synchronous.setThrow();
-    synchronous.lifecycle.request();
-    await synchronous.settle();
-    assert.equal(synchronous.notices.length, 1);
-    assert.equal(synchronous.lifecycle.request(), "rollover_requested");
-    const aborted = harness();
-    aborted.lifecycle.request();
-    aborted.setSignal(AbortSignal.abort());
-    await aborted.settle();
-    assert.equal(aborted.requests.length, 0);
-    assert.deepEqual(aborted.messages, []);
-});
-test("shutdown, tree invalidation, toggling off, and stale sessions release waiters safely", async () => {
-    for (const boundary of ["session_shutdown", "session_start", "session_tree", "off", "session-change"]) {
-        const h = harness();
-        h.lifecycle.request();
-        const outer = h.settle();
-        h.success();
-        h.complete();
-        if (boundary === "off") {
-            h.disable();
-            h.enable();
-        }
-        else if (boundary === "session-change") {
-            h.setSession("second");
-            h.complete();
-            h.emit("session_tree");
-        }
-        else
-            h.emit(boundary);
-        h.complete();
-        h.requests[0].onError(new Error("late error"));
-        await outer;
-        assert.deepEqual(h.notices, [], boundary);
-        assert.deepEqual(h.messages, ["continue"], boundary);
-        if (boundary === "session_shutdown")
-            h.emit("session_start");
-        if (boundary === "session-change")
-            h.emit("session_tree");
-        assert.equal(h.lifecycle.request(), "rollover_requested", `${boundary}: a fresh request still works`);
-    }
+    await h.callTool("wipe_memory");
+    const first = resultEntries(await h.emit("turn_end", fakeBoundaryEvent()));
+    assert.ok(first.entries.some((entry) => entry.type === "custom" && entry.customType === internal.RESET_MARKER_TYPE));
+    appendDrafts(h.sessionManager, first.entries);
+    await h.runCommand("pi-context", "off");
+    const before = await h.emit("session_before_compact", {
+        type: "session_before_compact",
+        reason: "manual",
+        willRetry: false,
+        branchEntries: h.sessionManager.getBranch(),
+        preparation: { tokensBefore: 100, firstKeptEntryId: null, keptMessages: [], droppedMessages: [] },
+        signal: new AbortController().signal,
+    });
+    assert.deepEqual(before.at(-1), { cancel: true }, "/compact is canceled when an existing marker would expose old canonical history");
+    const afterOff = resultEntries(await h.emit("turn_end", fakeBoundaryEvent()));
+    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[0]?.triggerTurn, false);
+    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");
 });
-test("queued or competing work is not duplicated and releases an unneeded continuation owner", async () => {
-    const competing = harness();
-    competing.lifecycle.request();
-    competing.setIdle(false);
-    assert.equal(competing.emit("agent_settled"), undefined, "another run owns the first settled event");
-    competing.setIdle(true);
-    const outer = competing.settle();
-    competing.success();
-    competing.setIdle(false);
-    competing.complete();
-    await outer;
-    assert.deepEqual(competing.messages, [], "an active prompt owns continuation");
-    const queued = harness();
-    queued.lifecycle.request();
-    const queuedOuter = queued.settle();
-    queued.success();
-    queued.setPending(true);
-    queued.complete();
-    await queuedOuter;
-    assert.deepEqual(queued.messages, [], "queued user work is never duplicated");
+test("reset construction failure preserves incoming and budget drafts without continuation", async () => {
+    const sessionManager = Manager.inMemory("/private/tmp/pi-context-reset-failure-test");
+    const handlers = new Map();
+    const notices = [];
+    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: (message, type) => notices.push({ message, type }) },
+    };
+    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: () => { throw new Error("synthetic reset construction failure"); },
+    });
+    lifecycle.request();
+    const incoming = { type: "custom_message", customType: "foreign/boundary", content: "foreign draft", display: false };
+    const results = [];
+    for (const handler of handlers.get("turn_end") ?? [])
+        results.push(await handler(fakeBoundaryEvent([incoming]), ctx));
+    const result = resultEntries(results);
+    assert.deepEqual(result.entries, [incoming, budgetDraft], "already-built drafts survive reset construction failure");
+    assert.equal(result.continue, false, "a failed reset does not request continuation");
+    assert.equal(notices.at(-1)?.type, "warning");
+    assert.match(notices.at(-1)?.message ?? "", /could not build reset/);
 });
-test("foreign boundaries and native compactions do not manufacture a continuation", async () => {
-    const h = harness();
-    h.lifecycle.request();
-    const outer = h.settle();
-    h.emit("session_compact", { compactionEntry: { id: "foreign" }, willRetry: false });
-    h.emit("session_compact", { compactionEntry: { id: "foreign" }, willRetry: false });
-    assert.equal(h.lifecycle.request(), "rollover_already_pending");
-    h.complete();
-    await outer;
-    assert.deepEqual(h.messages, []);
-    const native = harness();
-    native.lifecycle.request();
-    native.success("native", false);
-    await native.settle();
-    assert.equal(native.requests.length, 0);
-    assert.deepEqual(native.messages, []);
+test("a queued success clears an overflow failure before settle recovery can reset", async () => {
+    const sessionManager = Manager.inMemory("/private/tmp/pi-context-queued-overflow-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: { contextWindow: 100_000, maxTokens: 4_096 },
+        signal: undefined,
+        hasPendingMessages: () => false,
+        ui: { notify() { } },
+    };
+    let resetCount = 0;
+    const lifecycle = registerResetLifecycle(api, {
+        isEnabled: () => true,
+        budget: {
+            automaticResetEnabled: () => true,
+            resetDue: () => false,
+            consumeTurnEnd: () => [],
+            clear: () => { },
+        },
+        buildReset: () => {
+            resetCount += 1;
+            return [];
+        },
+    });
+    const failed = fakeBoundaryEvent();
+    failed.message = { ...failed.message, stopReason: "error", errorMessage: "Prompt too long: context exceeds maximum context length" };
+    const turnEnd = handlers.get("turn_end")?.[0];
+    const beforeSettle = handlers.get("agent_before_settle")?.[0];
+    assert.ok(turnEnd && beforeSettle);
+    await turnEnd(failed, ctx);
+    const queued = {
+        ...failed,
+        type: "agent_before_settle",
+        outcome: "error",
+        context: { ...failed.context, pendingMessages: [{ role: "user", content: [{ type: "text", text: "queued success" }], timestamp: Date.now() }] },
+    };
+    assert.equal(await beforeSettle(queued, ctx), undefined, "a queued message defers overflow recovery");
+    const success = fakeBoundaryEvent();
+    await turnEnd(success, ctx);
+    const settled = { ...queued, context: { ...queued.context, pendingMessages: [] }, outcome: "completed" };
+    assert.equal(await beforeSettle(settled, ctx), undefined, "the successful queued turn clears the stale recovery");
+    assert.equal(resetCount, 0);
 });

package/docs/architecture.md

@@ -6,36 +6,53 @@ pi-context uses Pi's session branch as the durable source of truth. It does not
 
 | Module | Responsibility | Boundary |
 | --- | --- | --- |
-| `index.ts` | Compose features, expose toggle/reset tool, construct reset boundary | Pi extension API |
-| `history.ts` | Project branch entries into windows/items; identify active window | `SessionReader`, read-only branch and session ID |
-| `notes.ts` | Replay note operations, validate paths/timestamps | `SessionReader`; no scheduling or writes |
-| `history-tools.ts`, `note-tools.ts` | Public schemas and tool results; append validated note operations | Pi tool API plus read projections |
-| `budget.ts` | Resolve settings, report usable budget, persist guidance once | Pi settings/context hooks |
-| `thresholds.ts` | Derive the reminder/reserve/warning lines from Pi's reserve plus the pi-context margins | Pi `SettingsManager`, read-only; session-scoped cache |
-| `warning.ts` | Steer the final checkpoint warning once per window | Pi context hook |
-| `prompts.ts` | Render static boot block, note index, reminder and warning | Read projections and protocol text |
-| `reset-lifecycle.ts` | Own reset requests, completion and continuation | Pi lifecycle hooks and injected boundary builder |
+| `index.ts` | Thin public entrypoint: register the context runtime and tool adapters, and preserve public history/notes re-exports | Pi extension API |
+| `context/runtime.ts` | Compose runtime hooks, toggle/reset commands, boot construction, marker/boot boundaries, and provider projection | Pi extension API plus context and notes modules |
+| `history/history.ts` | Project branch entries into windows/items using the shared window identity | `SessionReader`, read-only branch and session ID |
+| `context/context-window.ts` | Own durable window identity, select the active boot, project provider context, and account for active-window usage | `SessionReader` plus Pi context/system projection APIs |
+| `notes/session-replay.ts` | Replay persisted note operations from session entries | `SessionReader`; no filesystem acquisition |
+| `notes/address.ts` | Validate virtual note paths and resolve address/glob forms | Note address syntax; no session-branch selection |
+| `notes/notes-snapshot.ts` | Acquire the five notes homes once into a closed boot snapshot and isolate filesystem-home failures | Filesystem-backed notes homes; no rendering or UI effects |
+| `notes/store.ts` | Read and mutate the filesystem-backed homes; distinguish an absent home from a real read failure | Notes filesystem only; boot acquisition isolates one home at a time |
+| `history/history-tools.ts` | Public history schemas and tool results over branch projections | Pi tool API plus read projections |
+| `notes/tools.ts` | Filesystem note tool adapters; validate and perform note reads, writes, edits, listings, and searches | Pi tool API plus notes filesystem |
+| `context/budget.ts` | Own the default-path per-extension-instance settings cache, read injected policy live, report usable budget, stage guidance/warning drafts, and resolve automatic reset decisions | Pi settings/context hooks plus protocol warning text |
+| `context/thresholds.ts` | Read the selected public settings authority and derive reminder/reserve/warning thresholds from Pi's reserve plus the pi-context margins | Pi `SettingsManager`, read-only; no mutable cache or UI effects |
+| `settings.ts` | Merge the global and project `pi-context` settings object per key | Parsed Pi settings scopes; no I/O or runtime state |
+| `dream/settings.ts` | Validate and resolve the configured dreamer model from the shared settings merge | Pi `SettingsManager`; no runtime context state |
+| `context/prompts.ts` | Render the static boot block, note index, and low-budget reminder from explicit data | Snapshot data and protocol text; no filesystem acquisition or UI effects |
+| `context/reset-lifecycle.ts` | Own reset requests, turn-end batching, recovery and continuation | Pi lifecycle hooks and injected boundary builder |
 | `protocol.ts` | Persisted entry tags, protocol text and defaults | No imports or effects |
 | `tool-schema.ts`, `tool-output.ts` | Shared wire-schema primitives and JSON result encoding | No session state |
 
-Dependencies flow from the composition root and tool adapters to projections and protocol constants. Projections cannot send messages, compact, notify, or mutate the session. A runtime framework or generic event bus would add indirection without strengthening these boundaries.
+Dependencies flow from the composition root and tool adapters to projections and protocol constants. The published Pi entry is `dist/extension.js`, built from `src/index.ts`; its public `pi-ai/utils/estimate` dependency is inlined so Pi's root-package aliases cannot misresolve the utility subpath. Host-owned package APIs remain external. Projections cannot send messages, compact, notify, or mutate the session. A runtime framework or generic event bus would add indirection without strengthening these boundaries.
 
 ## State and persistence
 
-Reset requests are a discriminated union: `idle`, `requested`, or `compacting` with an identified attempt. A request cannot simultaneously be pending and in flight. Each attempt records its originating session, whether it was explicit, and whether a matching boundary completed. Callback identity prevents an old attempt from consuming a newer one. See [reset lifecycle](reset-lifecycle.md).
+`turn_end` has one composer in `reset-lifecycle.ts`: it accepts the incoming drafts, drains the budget instance's staged guidance/warning drafts, and only then appends reset drafts. Reset requests are committed after the complete tool batch with `continue: true`, so Pi owns queue scheduling. Repeated `wipe_memory` requests in one batch deduplicate; a later window may still request another reset. Aborts and reset-construction failures preserve already-built drafts without manufacturing a continuation. See [reset lifecycle](reset-lifecycle.md).
 
-Manual, threshold and overflow compactions all build the reset boundary on the spot, idle or streaming: `session_before_compact` returns the reset immediately, never cancels and never takes a model turn, and only an aborted signal cancels. The final checkpoint warning was already steered from the context hook (see [reset lifecycle](reset-lifecycle.md)), so the model had its chance to write a note; what crosses the line now is the wipe itself. `agent_settled` services only explicit `new_context` requests, whose `ctx.compact` route needs the completion callback.
+The durable boundary is one `pi-context/reset-marker` custom entry with `{ windowId: string }`, followed by one hidden `pi-context/boot` custom message with `details.windowId` equal to the marker identity. The marker is the only window boundary. `context/context-window.ts` owns the marker predicate, active-branch scan, root/current IDs, and per-window message lookup; `history/history.ts` consumes those identity primitives while projecting entries. The scan never uses a global entry tail. Native compaction and branch-summary entries remain history items in the current window, so the old compaction-entry identity is not a window identity.
 
-Boot and reminder deduplication inspect messages in the current persisted window. Reloading the extension or the JSONL file therefore does not duplicate either message. Reminder reservation in memory covers Pi's deferred message write; navigation clears that reservation, while persisted branch-local messages remain authoritative. A sibling branch cannot suppress a reminder it never received.
+The runtime in `context/runtime.ts` performs final context projection by selecting the active boot through `details.windowId` and folding only the dropped system prefix through Pi's `getCurrentSystemMessage`. Later prompt patches and new messages stay in order. A missing boot aborts the hook with a safe head and notice rather than silently sending raw history. Startup/tree handling repairs only a genuinely incomplete marker tail: a missing boot with no later raw message, custom message, compaction, branch summary, or authoritative raw boot. If later work exists, boot creation is refused and `/wipe-memory` is the explicit recovery path; it does not parse or migrate the legacy reset-v2 protocol.
 
-Note replay accepts only supported operations, safe virtual paths, representable timestamps and results within the UTF-8 size limit. Invalid operations are ignored; they cannot replace a valid note. Reads reconstruct the current branch without a cache, so navigating a branch cannot expose notes from a sibling.
+Boot and reminder deduplication inspect the current branch-local window. Reloading JSONL therefore does not duplicate messages, while navigation to a sibling branch cannot inherit another branch's window state. A fork/clone receives a new session ID while copying its selected path, so startup must also verify that a root boot's `details.windowId` matches the new `rootWindowId(sessionId)` before treating it as present.
 
-Reset IDs are opaque strings tagged with `reset-v2`; newly minted IDs use `pcw:<session>:<8 lowercase hex digits>`. Unsupported details fall back to Pi's compaction-entry identity for history lookup. Minting checks existing branch window IDs, which are independent of Pi entry IDs. A reset adds a marker via the public append API, then uses its real entry ID as `firstKeptEntryId`; old conversation remains searchable in the durable branch.
+Startup and idle manual resets use `pi.sendMessage(..., { triggerTurn: false })` for the boot. Pi appends it to the session and refreshes context without initiating a model request; during streaming the same call is deferred until the completed tool batch. This is session persistence, not a promise of immediate disk durability: Pi 0.87 defers a new session file until its first assistant message, and the extension API reports send failures through extension errors rather than an awaitable result. Running resets therefore use boundary drafts for ordering and continuation, not `sendMessage`. Drafts are validated together but disk writes are not transactional.
+
+Boot is a fixed snapshot for its window, stored as an extension custom message and converted by Pi to a user-role model message. History's `developer` classification records extension authorship, not provider instruction priority. A system-role projection is technically possible through `context_with_system`, but would change the authority of the mixed protocol/MAP content and provider-specific prompt/cache behavior; it is not a prerequisite for persistence. Boot injection is silent, including startup, reload, and boot repair. Only an actual context reset produces `pi-context: memory cleared · <windowId>` through `ctx.ui.notify`, after both marker and boot are present in the session. Manual clear is checked immediately; running resets are checked at the next turn start or final settlement. Uncommitted reset drafts never announce success. Boot and continuation messages retain `display: false`.
+
+History reads reconstruct the selected session branch on demand without a cache, so branch navigation cannot expose history from a sibling.
+
+The boot notes index in `notes/notes-snapshot.ts` is a closed snapshot: the current session, project, human, agent, and model homes are each loaded at most once while constructing a boot. `context/prompts.ts` then renders that explicit snapshot without reading the filesystem or consulting the clock. MAP bodies and pocket metadata are derived from the same snapshot, so a boot cannot mix two filesystem reads. A missing home (`ENOENT`) is normal. A real read failure omits only that home's index, preserves healthy homes, adds a model-facing `notes_list` recovery notice, and notifies the human once for that window. The window identity, reset/protocol text, and lifecycle boundary are still constructed through the normal runtime path; note reads never mutate files or create fallback state.
+
+`notes/session-replay.ts` accepts only supported operations, safe virtual paths, representable timestamps and results within the UTF-8 size limit. Invalid operations are ignored; they cannot replace a valid note. Notes remain in their filesystem-backed homes, unchanged by session branch navigation.
+
+The `/wipe-memory` command waits for idle, appends the marker and boot with Pi's public `appendEntry`/`sendMessage` APIs, and never calls a model. While enabled, `/compact` is cancelled with an actionable `/wipe-memory` notice. Disabling pi-context stops new automatic resets, but an existing marker still excludes earlier history and native compaction is still cancelled on that marked branch; a fresh root may use native Pi semantics. Threshold and warning accounting use active-window provider usage rather than pre-reset global usage. Budget policy and staged prompts are instance-owned, so concurrent sessions cannot share reserve/enablement or uncommitted drafts; default file-backed policy is cached per instance, while injected policy is resolved live on each decision and model/session transitions reset the diagnostic lifecycle.
 
 ## Evidence and limits
 
-The integration suite uses real SessionManager and SettingsManager instances, including JSONL restoration, branch navigation, Unicode content, malformed note operations and settings precedence. Lifecycle event tests cover duplicate/stale callbacks, native scheduling, disabled state, abort and failed compaction.
+The retained integration tests use real SessionManager and SettingsManager instances. They check reset-window history retention, bounded history/notes reads with resumable cursors, notes-home isolation, and settings precedence. The suite is a representative regression set; the standalone coherence, pagination property, history, and threshold suites were removed during test reduction.
 
-Scripted SDK tests execute the real Pi agent loop with no model network request. They cover explicit reset, instant automatic reset, rejected compaction, steering and follow-up delivery before reset without replay, consecutive distinct windows, and cancellation followed by a new user prompt. They inspect actual provider contexts and durable entries. They do not establish reliability of an external provider or every possible interleaving between unrelated extensions.
+Scripted SDK tests execute the real Pi agent loop with no model network request. They inspect provider contexts and durable entries for reset boundaries, mixed-tool completion, queued steering/follow-up delivery, overflow recovery, and settings authority. Smaller dream tests retain lock exclusion/ownership, jailed writes, CLI audit/report failure propagation, and read-only doctor behavior. Removing duplicate scenarios and edge-case matrices reduces coverage; the remaining tests do not establish every malformed-input case, branch interleaving, external-provider behavior, or filesystem failure mode.
 
-Pi decides compaction eligibility before the boundary hook. A short uncompactable session therefore cannot be force-reset with the public API. Mixed tool batches and queued messages may finish before `agent_settled`; the extension preserves their delivery rather than clearing the queue. Native compaction owns its subsequent scheduling, while extension-requested compaction resumes from `onComplete` after Pi clears compaction state.
+Mixed tool batches finish before the marker/boot boundary. Queued steering/follow-up messages are delivered exactly once in the new window; they are neither dropped nor replayed. Runtime overflow recovery is bounded to one reset/retry per failure chain, while ordinary retryable provider errors remain Pi-owned. When either the source or destination branch has a reset marker, `/tree` navigation still succeeds but its generated summary is replaced by an empty summary plus a notice; raw history and branch selection remain available. If neither branch has a marker, Pi's native tree summary is retained.