@astrosheep/pi-context 0.25.1 → 0.26.0

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

@@ -109,22 +109,25 @@ function appendDrafts(sessionManager, entries) {
 }
 function turnEndFacts(overrides = {}) {
     return {
+        windowId: "pcw:test:window",
         aborted: false,
         overflow: false,
         failed: false,
         enabled: true,
         queued: false,
         automaticResetEnabled: true,
-        thresholdDue: false,
+        hardReserveDue: false,
         ...overrides,
     };
 }
 function beforeSettleFacts(overrides = {}) {
     return {
+        windowId: "pcw:test:window",
         queued: false,
         enabled: true,
         automaticResetEnabled: true,
         aborted: false,
+        failed: false,
         ...overrides,
     };
 }
@@ -156,14 +159,15 @@ test("public reset boundary drafts one marker, one boot, and one continuation af
     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");
+    assert.equal(boundary.entries[1]?.type, "compaction", "native retain-none checkpoint precedes the reset marker");
+    assert.equal(boundary.entries[2]?.type, "custom");
+    assert.equal(boundary.entries[3]?.type, "custom_message");
     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");
+    assert.equal(boundary.entries[4]?.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 }]);
@@ -189,12 +193,14 @@ 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, 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);
+    assert.equal(h.sent.length, 1, "/wipe-memory sends one hidden close-out warning and starts a normal turn");
+    assert.equal(h.sent[0]?.triggerTurn, true);
+    assert.equal(h.sent[0]?.customType, internal.WARNING_TYPE);
+    const warning = h.sessionManager.getBranch().find((entry) => entry.type === "custom_message" && entry.customType === internal.WARNING_TYPE);
+    assert.ok(warning && warning.type === "custom_message");
+    assert.equal(warning.content, internal.WARNING_CONTENT);
     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");
+    assert.equal(markers.length, 1, "manual command waits for an agent boundary; it does not persist an immediate reset");
 });
 test("reset construction failure preserves incoming and budget drafts without continuation", async () => {
     const sessionManager = Manager.inMemory("/private/tmp/pi-context-reset-failure-test");
@@ -220,13 +226,13 @@ test("reset construction failure preserves incoming and budget drafts without co
         isEnabled: () => true,
         budget: {
             automaticResetEnabled: () => true,
-            resetDue: () => false,
+            hardReserveDue: () => false,
             consumeTurnEnd: () => [budgetDraft],
             clear: () => { },
         },
         buildReset: () => { throw new Error("synthetic reset construction failure"); },
     });
-    lifecycle.request();
+    lifecycle.request(`pcw:${sessionManager.getSessionId().slice(0, 8)}:root`);
     const incoming = { type: "custom_message", customType: "foreign/boundary", content: "foreign draft", display: false };
     const results = [];
     for (const handler of handlers.get("turn_end") ?? [])
@@ -237,6 +243,52 @@ test("reset construction failure preserves incoming and budget drafts without co
     assert.equal(notices.at(-1)?.type, "warning");
     assert.match(notices.at(-1)?.message ?? "", /could not build reset/);
 });
+test("a stale async reset is discarded after a lifecycle switch without staging a notice", async () => {
+    const sessionManager = Manager.inMemory("/private/tmp/pi-context-stale-reset-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() { } },
+    };
+    let resolveBuild;
+    const pendingBuild = new Promise((resolve) => { resolveBuild = resolve; });
+    let readyCount = 0;
+    const lifecycle = registerResetLifecycle(api, {
+        isEnabled: () => true,
+        budget: {
+            automaticResetEnabled: () => true,
+            hardReserveDue: () => false,
+            consumeTurnEnd: () => [],
+            clear: () => { },
+        },
+        buildReset: () => pendingBuild,
+        onResetReady: () => { readyCount++; },
+    });
+    const windowId = `pcw:${sessionManager.getSessionId().slice(0, 8)}:root`;
+    lifecycle.request(windowId);
+    const incoming = { type: "custom_message", customType: "foreign/boundary", content: "preserve me", display: false };
+    const turnEnd = handlers.get("turn_end")?.[0];
+    const sessionTree = handlers.get("session_tree")?.[0];
+    assert.ok(turnEnd && sessionTree);
+    const pending = turnEnd(fakeBoundaryEvent([incoming]), ctx);
+    await sessionTree({}, ctx);
+    resolveBuild([{ type: "custom_message", customType: internal.BOOT_TYPE, content: "stale", display: false }]);
+    const result = resultEntries([await pending]);
+    assert.deepEqual(result.entries, [incoming], "a switched lifecycle keeps incoming drafts but discards stale reset drafts");
+    assert.equal(result.continue, false);
+    assert.equal(readyCount, 0, "stale reset work cannot stage a success notice");
+});
 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();
@@ -260,7 +312,7 @@ test("a queued success clears an overflow failure before settle recovery can res
         isEnabled: () => true,
         budget: {
             automaticResetEnabled: () => true,
-            resetDue: () => false,
+            hardReserveDue: () => false,
             consumeTurnEnd: () => [],
             clear: () => { },
         },
@@ -288,55 +340,63 @@ 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: close-out phases deduplicate, span turns, and upgrade to a tool commit", () => {
+    const windowId = "pcw:test:window";
+    const first = reduceResetControl(initialResetControl(), { type: "close_out", windowId, source: "manual" });
+    assert.equal(first.effect, "close-out-armed");
+    assert.deepEqual(first.state.request, { phase: "close-out", windowId, source: "manual" });
+    const duplicate = reduceResetControl(first.state, { type: "close_out", windowId, source: "manual" });
+    assert.equal(duplicate.effect, "already-pending");
+    const noteTurn = reduceResetControl(first.state, { type: "turn_end", facts: turnEndFacts() });
+    assert.equal(noteTurn.effect, "none");
+    assert.deepEqual(noteTurn.state.request, first.state.request, "note/tool turns do not consume close-out");
+    const tool = reduceResetControl(noteTurn.state, { type: "tool_request", windowId });
+    assert.deepEqual(tool.state.request, { phase: "tool-requested", windowId });
+    const commit = reduceResetControl(tool.state, { type: "turn_end", facts: turnEndFacts() });
+    assert.equal(commit.effect, "commit-boundary");
+    assert.deepEqual(commit.state, initialResetControl());
 });
-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: fallback is normal-stop only; hard reserve remains safety", () => {
+    const windowId = "pcw:test:window";
+    const manual = reduceResetControl(initialResetControl(), { type: "close_out", windowId, source: "manual" }).state;
+    const fallback = reduceResetControl(manual, { type: "before_settle", facts: beforeSettleFacts() });
+    assert.equal(fallback.effect, "commit-boundary", "manual close-out works even when automatic resets are disabled");
+    assert.deepEqual(fallback.state, initialResetControl());
+    const automatic = reduceResetControl(initialResetControl(), { type: "close_out", windowId, source: "automatic" }).state;
+    const disabledAuto = reduceResetControl(automatic, { type: "before_settle", facts: beforeSettleFacts({ automaticResetEnabled: false }) });
+    assert.equal(disabledAuto.effect, "none");
+    assert.deepEqual(disabledAuto.state, initialResetControl());
+    const safety = reduceResetControl(initialResetControl(), { type: "turn_end", facts: turnEndFacts({ hardReserveDue: true }) });
+    assert.equal(safety.effect, "commit-boundary");
+    for (const outcome of [{ failed: true }, { aborted: true }]) {
+        const notNormalStop = reduceResetControl(manual, { type: "before_settle", facts: beforeSettleFacts(outcome) });
+        assert.equal(notNormalStop.effect, "none");
+        assert.deepEqual(notNormalStop.state, initialResetControl());
+    }
+    assert.deepEqual(reduceResetControl(manual, { type: "settled" }).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 }) });
+test("reset-control: abort and lifecycle transitions clear every pending phase", () => {
+    const windowId = "pcw:test:window";
+    const pending = reduceResetControl(initialResetControl(), { type: "close_out", windowId, source: "manual" }).state;
+    const aborted = reduceResetControl(pending, { 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());
+    assert.deepEqual(aborted.state, initialResetControl());
+    assert.deepEqual(reduceResetControl(pending, { type: "clear" }).state, initialResetControl());
+    assert.deepEqual(reduceResetControl(pending, { type: "settled" }).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" });
+    assert.deepEqual(armed.state, { request: { phase: "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" });
+    assert.deepEqual(recovered.state, { request: { phase: "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" });
+    assert.deepEqual(rearmed.state, { request: { phase: "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" });
+    assert.deepEqual(bounded.state, { request: { phase: "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;
@@ -350,52 +410,40 @@ test("reset-control: disabled mode and explicit aborts disarm overflow without a
     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" });
+    assert.deepEqual(disabled.state, { request: { phase: "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" });
+    assert.deepEqual(automaticOff.state, { request: { phase: "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" });
+    assert.deepEqual(aborted.state, { request: { phase: "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 };
+test("reset-control: lazy guards preserve overflow policy ordering", () => {
+    const calls = { queued: 0, automatic: 0, hardReserve: 0 };
+    const facts = {
+        windowId: "pcw:test:window",
+        aborted: false,
+        overflow: true,
+        failed: true,
+        enabled: true,
+        get queued() { calls.queued += 1; return false; },
+        get automaticResetEnabled() { calls.automatic += 1; return true; },
+        get hardReserveDue() { calls.hardReserve += 1; return true; },
     };
-    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");
+    reduceResetControl(initialResetControl(), { type: "turn_end", facts });
+    assert.deepEqual(calls, { queued: 1, automatic: 1, hardReserve: 0 }, "overflow checks never consult hard-reserve policy");
     const settleCalls = { queued: 0, enabled: 0, automatic: 0 };
     const settleFacts = {
+        windowId: "pcw:test:window",
         get queued() { settleCalls.queued += 1; return true; },
         get enabled() { settleCalls.enabled += 1; return true; },
         get automaticResetEnabled() { settleCalls.automatic += 1; return true; },
         aborted: false,
+        failed: 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");
+    const pendingOverflow = reduceResetControl(initialResetControl(), { type: "turn_end", facts: turnEndFacts({ overflow: true, failed: true }) }).state;
+    reduceResetControl(pendingOverflow, { type: "before_settle", facts: settleFacts });
+    assert.deepEqual(settleCalls, { queued: 1, enabled: 0, automatic: 0 }, "queued settle checks no further overflow policy");
 });
 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");
@@ -421,17 +469,18 @@ test("a committed reset places incoming and budget drafts before marker -> boot
         isEnabled: () => true,
         budget: {
             automaticResetEnabled: () => true,
-            resetDue: () => false,
+            hardReserveDue: () => false,
             consumeTurnEnd: () => [budgetDraft],
             clear: () => { },
         },
         buildReset: () => [
+            { type: "compaction", summary: "", firstKeptEntryId: null },
             { 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();
+    lifecycle.request(`pcw:${sessionManager.getSessionId().slice(0, 8)}:root`);
     const incoming = { type: "custom_message", customType: "foreign/boundary", content: "incoming", display: false };
     const results = [];
     for (const handler of handlers.get("turn_end") ?? [])
@@ -439,12 +488,15 @@ test("a committed reset places incoming and budget drafts before marker -> boot
     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");
+        if (entry.type === "compaction")
+            return "native-compaction";
+        assert.ok(entry.type === "custom" || entry.type === "custom_message", "the boundary only carries expected reset drafts here");
         return entry.customType;
     });
     assert.deepEqual(customTypes(result.entries), [
         "foreign/boundary",
         internal.GUIDANCE_TYPE,
+        "native-compaction",
         internal.RESET_MARKER_TYPE,
         internal.BOOT_TYPE,
         internal.CONTINUATION_TYPE,
@@ -452,7 +504,12 @@ test("a committed reset places incoming and budget drafts before marker -> boot
     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.ok(markerIndex > 0);
+    assert.equal(branch[markerIndex - 1]?.type, "compaction", "the checkpoint is directly before the marker");
+    const checkpoint = branch[markerIndex - 1];
+    assert.ok(checkpoint?.type === "compaction");
+    assert.equal(checkpoint.summary, "");
+    assert.equal(checkpoint.firstKeptEntryId, checkpoint.id, "Pi materializes null as retain-none");
     assert.deepEqual(customTypes(branch.slice(markerIndex)), [
         internal.RESET_MARKER_TYPE,
         internal.BOOT_TYPE,

package/docs/architecture.md

@@ -29,30 +29,30 @@ Dependencies flow from the composition root and tool adapters to projections and
 
 ## State and persistence
 
-`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).
+`reset-lifecycle.ts` is the sole `turn_end` composer: it accepts incoming drafts, drains budget-owned guidance/warning drafts, and appends a reset boundary only for an explicit tool request or the hard-reserve safety path. Manual and budget close-outs stay armed across note/tool turns and fall back from `agent_before_settle` only after a successful stop and queued work are drained. Repeated requests for the same window deduplicate. See [reset lifecycle](reset-lifecycle.md).
 
-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.
+A new reset is a native empty-summary compaction checkpoint configured to retain none, followed by one `pi-context/reset-marker` custom entry with `{ windowId: string }`, a hidden `pi-context/boot` whose `details.windowId` matches, and a hidden continuation. The checkpoint is the canonical-history cut; the marker is the durable logical window identity. Raw session entries remain available to history tools. Legacy marker-only branches keep a narrow projection fallback. `context/context-window.ts` owns marker/checkpoint validation, 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.
 
 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.
 
 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.
 
-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.
+Manual `/wipe-memory` first waits for idle, then records the same hidden warning used by budget-triggered close-out and starts an ordinary model turn. The agent can checkpoint notes through multiple turns; an explicit `wipe_memory` commits at `turn_end`, while a successful stop without the tool falls back at `agent_before_settle`. Abort/error never counts as successful close-out. The final checkpoint, marker, boot, and continuation are emitted as ordered session-boundary drafts. Pi's retain-none compaction entry persists the canonical cut; the marker/boot preserve pi-context's logical identity and protocol.
 
-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`.
+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 the verified checkpoint, marker, boot, and continuation are present in the session. Committed 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.
+The boot notes index in `pi/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. Note storage and home traversal use `node:fs/promises`; same-file operations queue by absolute physical filename across store instances in this process, without promising symlink/case-alias or cross-process locking. Known persisted metadata is camelCase, and a known legacy snake_case key refuses use until the root-coordinated manual migration; startup does not migrate notes. 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. Boot/reset construction captures session, agent, and model identity before awaiting the snapshot, then checks lifecycle generation, active window, enabled state, and abort status before sending or returning artifacts; stale completions cannot commit into a switched or shut-down session. 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.
+The `/wipe-memory` command captures the current window before waiting for idle, refuses a duplicate if the wait crossed into a new window, then records a hidden warning and starts a model close-out turn. While enabled, `/compact` is cancelled with an actionable `/wipe-memory` notice. Disabling pi-context stops new automatic resets, but an existing native checkpoint/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 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 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.
+Scripted SDK tests execute the real Pi agent loop with no model/network request. They inspect provider contexts and durable entries for manual/budget close-out, multi-turn notes, explicit and normal-stop commits, abort/error cleanup, same-window command deduplication, queued steering/follow-up delivery, retain-none checkpoints across two resets and disk reopen, bounded 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.
 
-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.
+Mixed tool batches finish before a direct tool reset boundary. Manual/budget close-outs let queued steering/follow-up work run once in the old window before fallback; direct tool resets let Pi schedule queued work across the new boundary. Scripted loop tests check that these messages 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.