@astrosheep/pi-context 0.22.1 → 0.23.0

package/README.md

@@ -34,7 +34,7 @@ pi -e npm:@astrosheep/pi-context
 | `notes.list` | `notes_list` |
 | `notes.search` | `notes_search` |
 
-The tool descriptions the model sees are the behavioral documentation: search is case-sensitive literal substring; reads are character windows whose cursors reconstruct the original exactly; anything a response does not deliver is named by an explicit field.
+The tool descriptions the model sees are the behavioral documentation: note results use `address` as the sole home identity; search is case-sensitive literal substring; both `notes_read` and `history_read` are character windows prefixed with the same `READ WINDOW` block, whose cursors reconstruct the source exactly when only the content after each block is concatenated; anything a response does not deliver is named by an explicit field.
 
 - **Runtime toggle** — `/pi-context off` restores Pi's default compaction (including `keepRecentTokens`); `/pi-context on` re-enables; bare `/pi-context` reports the current state.
 

package/dist/src/history-tools.js

@@ -1,6 +1,6 @@
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool } from "@earendil-works/pi-coding-agent";
-import { output, outputRaw, page, middleTruncate, prefixFit, earliestMatchOffsetChars, readCharacterWindow, characterWindowHeader, withinTextBudget, DEFAULT_READ_WINDOW_CHARS, HISTORY_PREVIEW_CHARS, MAX_READ_WINDOW_CHARS } from "./tool-output.js";
+import { output, outputRaw, page, middleTruncate, prefixFit, earliestMatchOffsetChars, readCharacterWindow, readWindowBlock, withinTextBudget, DEFAULT_READ_WINDOW_CHARS, HISTORY_PREVIEW_CHARS, MAX_READ_WINDOW_CHARS } from "./tool-output.js";
 import { positiveInteger, recentFirst, nullableString, role, cursor, searchQuery, searchQueries } from "./tool-schema.js";
 import { historyFromSession, filteredItems, visibleItem, allItems, vacuousRoleToolCombo, unknownWindowId } from "./history.js";
 /**
@@ -64,7 +64,7 @@ export function registerHistoryTools(pi) {
     pi.registerTool(defineTool({
         name: "history_read",
         label: "History read item",
-        description: "Read a bounded character range from one session item. Each response delivers the longest contiguous prefix of the requested window that fits the wire budget: follow the resume cursor to reconstruct the item exactly. A negative offset_chars counts back from the item's end. Offsets and counts are code points (an emoji or CJK character counts as one). The response is the raw item text behind a one-line [bracketed] header naming the item, the resolved offset, the delivered char range, and the resume cursor (continue at offset_chars=N, or end).",
+        description: "Read a bounded character range from one session item. Each response delivers the longest contiguous prefix of the requested window that fits the wire budget: follow the resume cursor to reconstruct the item exactly. A negative offset_chars counts back from the item's end. Offsets and counts are code points (an emoji or CJK character counts as one). The response begins with the shared READ WINDOW block naming window_id and item_id; concatenate only the content after that block to reconstruct the item.",
         parameters: Type.Object({ item_id: Type.String(), offset_chars: Type.Optional(Type.Integer({ description: "Code-point offset to start from. A negative value counts back from the end; the response echoes the resolved absolute offset. Pass the previous next_offset_chars back unchanged to continue." })), limit_chars: Type.Optional(Type.Integer({ minimum: 1, maximum: MAX_READ_WINDOW_CHARS, description: `Largest requested window in code points (default ${DEFAULT_READ_WINDOW_CHARS}). A window too large for the wire budget is cut short; next_offset_chars names where the next read resumes.` })), window_id: Type.String() }, { additionalProperties: false }),
         async execute(_id, params, _signal, _update, ctx) {
             const item = allItems(ctx).find((candidate) => candidate.windowId === params.window_id && candidate.itemId === params.item_id);
@@ -76,10 +76,9 @@ export function registerHistoryTools(pi) {
             if (typeof params.offset_chars === "number" && params.offset_chars > totalChars) {
                 return output({ error: `offset_chars ${params.offset_chars} is past the end: the item has ${totalChars} chars; the largest legal offset is ${totalChars} (an empty end-read)`, window_id: item.windowId, item_id: item.itemId, offset_chars: params.offset_chars, total_chars: totalChars });
             }
-            const limit_chars = Math.min(params.limit_chars ?? DEFAULT_READ_WINDOW_CHARS, MAX_READ_WINDOW_CHARS);
             return readCharacterWindow(item.content, params.offset_chars, params.limit_chars, (window) => {
                 const { content, ...cursor } = window;
-                return outputRaw(characterWindowHeader(`${item.windowId} · item ${item.itemId}`, window), content, { window_id: item.windowId, item_id: item.itemId, ...cursor, limit_chars });
+                return outputRaw(readWindowBlock([["window_id", item.windowId], ["item_id", item.itemId]], window), content, { window_id: item.windowId, item_id: item.itemId, ...cursor });
             }, (result) => withinTextBudget(result.content[0].text));
         },
     }));

package/dist/src/notes/store.js

@@ -208,6 +208,13 @@ export function editNote(ctx, vpath, scope, edits, opts = {}) {
     atomicWrite(path, serialized);
     return { meta, applied: operations.length, resolved_scope: scope, diff };
 }
+/** Normalize a parsed note exactly as a read does, including its access metadata mutation. */
+function accessedMeta(meta, scope, now) {
+    const next = { ...meta, scope };
+    next.last_accessed = now;
+    next.access_count = (typeof next.access_count === "number" ? next.access_count : 0) + 1;
+    return next;
+}
 /** Read a note and, as a side effect, bump last_accessed/access_count in the file. */
 export function readNote(ctx, vpath, scope) {
     assertVirtualPath(vpath);
@@ -215,13 +222,11 @@ export function readNote(ctx, vpath, scope) {
     if (!existsSync(path))
         return undefined;
     const now = Date.now();
-    const { meta, body } = parseNote(readFileSync(path, "utf8"), now);
-    meta.scope = scope;
-    // Only the two access keys move; updated_at and every other key keep their bytes.
-    meta.last_accessed = now;
-    meta.access_count = (typeof meta.access_count === "number" ? meta.access_count : 0) + 1;
-    atomicWrite(path, serializeNote(meta, body));
-    return { meta, body, resolvedScope: scope };
+    const parsed = parseNote(readFileSync(path, "utf8"), now);
+    const meta = accessedMeta(parsed.meta, scope, now);
+    const text = serializeNote(meta, parsed.body);
+    atomicWrite(path, text);
+    return { meta, body: parsed.body, text, resolvedScope: scope };
 }
 /** Merged rows across homes, most recently updated first (address breaks ties). */
 export function listNotes(ctx, opts = {}) {
@@ -253,11 +258,12 @@ export function searchNotes(ctx, queries, opts = {}) {
                 continue;
             const { meta, body } = parseNote(readFileSync(`${root}/${path}`, "utf8"));
             meta.scope = scope;
+            const serializedBodyOffset = Array.from(serializeNote(accessedMeta(meta, scope, Date.now()), "")).length;
             let baseChars = 0;
             const matches = [];
             for (const [index, line] of body.split("\n").entries()) {
                 if (queries.some((query) => line.includes(query))) {
-                    matches.push({ line: index + 1, text: line, offsetChars: baseChars + earliestMatchOffsetChars(line, queries) });
+                    matches.push({ line: index + 1, text: line, offsetChars: serializedBodyOffset + baseChars + earliestMatchOffsetChars(line, queries) });
                 }
                 baseChars += Array.from(line).length + 1;
             }

package/dist/src/notes/tools.js

@@ -1,18 +1,14 @@
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { localIso } from "./model.js";
-import { characterWindowHeader, DEFAULT_READ_WINDOW_CHARS, MAX_READ_WINDOW_CHARS, middleTruncate, output, outputRaw, page, prefixFit, readCharacterWindow, withinTextBudget } from "../tool-output.js";
+import { DEFAULT_READ_WINDOW_CHARS, MAX_READ_WINDOW_CHARS, middleTruncate, output, outputRaw, page, prefixFit, readCharacterWindow, readWindowBlock, withinTextBudget } from "../tool-output.js";
 import { cursor, nullableString, positiveInteger, searchQueries, searchQuery } from "../tool-schema.js";
 import { assertAddress } from "./address.js";
-import { serializeNote, stripLeadingFrontmatter } from "./frontmatter.js";
 import { NoteError, editNote, listNotes, readNote, searchNotes, writeNote } from "./store.js";
 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's home, and `@personal/<vpath>` for the human's cross-project home. `@` means leaving home. Any other `@` prefix, or `@` inside a vpath, is a hard error: legal prefixes are `@project/` and `@personal/`; bare names are the session home. There is no cross-home fallback. Paths reject `..`, absolute paths, and backslashes.";
-function wireMeta(meta) {
-    return { ...meta, created_at: localIso(meta.created_at), updated_at: localIso(meta.updated_at), last_accessed: localIso(meta.last_accessed) };
-}
 function failure(error) {
     if (error instanceof NoteError) {
         const payload = { error: error.message };
@@ -33,8 +29,8 @@ export function registerNotesTools(pi) {
             const content = params.content;
             try {
                 const destination = assertAddress(params.address);
-                const { meta } = writeNote(ctx, destination.path, content, { scope: destination.scope, origin: (params.origin ?? "self"), stale: params.stale });
-                return output({ address: params.address, scope: meta.scope, size_bytes: Buffer.byteLength(stripLeadingFrontmatter(content), "utf8"), meta: wireMeta(meta) });
+                writeNote(ctx, destination.path, content, { scope: destination.scope, origin: (params.origin ?? "self"), stale: params.stale });
+                return output({ address: params.address, written: true });
             }
             catch (error) {
                 return failure(error);
@@ -43,13 +39,13 @@ export function registerNotesTools(pi) {
     }));
     pi.registerTool(defineTool({
         name: "notes_edit", label: "Notes edit",
-        description: `Edit a note body by exact-text replacement; frontmatter is never editable this way. ${ADDRESS_DESCRIPTION} Each oldText must occur exactly once unless replace_all is set; a multi-match anchor fails with its match line numbers and a zero-match anchor names the failing edit index. edits may be omitted (or empty) for a metadata-only update, which requires at least one of origin/stale. Moving while awake means notes_write at a new address and notes_edit at the old address with stale=true. The success return carries resolved_scope and a diff of what changed.`,
+        description: `Edit a note body by exact-text replacement; frontmatter is never editable this way. ${ADDRESS_DESCRIPTION} Each oldText must occur exactly once unless replace_all is set; a multi-match anchor fails with its match line numbers and a zero-match anchor names the failing edit index. edits may be omitted (or empty) for a metadata-only update, which requires at least one of origin/stale. Moving while awake means notes_write at a new address and notes_edit at the old address with stale=true. The success return carries the address and a diff of what changed.`,
         parameters: Type.Object({ address: Type.String(), edits: Type.Optional(Type.Array(Type.Object({ oldText: Type.String(), newText: Type.String() }, { additionalProperties: false }))), origin: ORIGIN, stale: Type.Optional(Type.Boolean()), replace_all: Type.Optional(Type.Boolean()) }, { additionalProperties: false }), executionMode: "sequential",
         async execute(_id, params, _signal, _update, ctx) {
             try {
                 const destination = assertAddress(params.address);
-                const { meta, applied, resolved_scope, diff } = editNote(ctx, destination.path, destination.scope, params.edits, { origin: params.origin, stale: params.stale, replaceAll: params.replace_all });
-                return output({ address: params.address, applied, resolved_scope, diff, meta: wireMeta(meta) });
+                const { applied, diff } = editNote(ctx, destination.path, destination.scope, params.edits, { origin: params.origin, stale: params.stale, replaceAll: params.replace_all });
+                return output({ address: params.address, applied, diff });
             }
             catch (error) {
                 return failure(error);
@@ -58,7 +54,7 @@ export function registerNotesTools(pi) {
     }));
     pi.registerTool(defineTool({
         name: "notes_read", label: "Notes read",
-        description: `Read a character window of a note file, frontmatter included. ${ADDRESS_DESCRIPTION} offset_chars is the code-point offset to start from (default 0) — a negative value counts back from the end — and limit_chars caps the window (default ${DEFAULT_READ_WINDOW_CHARS}, max ${MAX_READ_WINDOW_CHARS}). Each response delivers the longest fitting prefix of that window: concatenate pages in order to reconstruct the note. The response is the raw frontmatter + body behind a one-line [bracketed] header naming the address, the resolved offset, the delivered char range, and the resume cursor.`,
+        description: `Read a character window of a note file, frontmatter included. ${ADDRESS_DESCRIPTION} offset_chars is the code-point offset to start from (default 0) — a negative value counts back from the end — and limit_chars caps the window (default ${DEFAULT_READ_WINDOW_CHARS}, max ${MAX_READ_WINDOW_CHARS}). Each response delivers the longest fitting prefix of that window in the shared READ WINDOW block: concatenate only the content after the block to reconstruct the note.`,
         parameters: Type.Object({ address: Type.String(), offset_chars: Type.Optional(Type.Integer({ description: "Code-point offset to start from (default 0). A negative value counts back from the end; the response echoes the resolved absolute offset. Pass the previous next_offset_chars back unchanged to continue." })), limit_chars: Type.Optional(Type.Integer({ minimum: 1, maximum: MAX_READ_WINDOW_CHARS, description: `Largest requested window in code points (default ${DEFAULT_READ_WINDOW_CHARS}). A window too large for the wire budget is cut short; next_offset_chars names where the next read resumes.` })) }, { additionalProperties: false }),
         async execute(_id, params, _signal, _update, ctx) {
             let note;
@@ -71,22 +67,19 @@ export function registerNotesTools(pi) {
             }
             if (!note)
                 return output({ error: "note not found", address: params.address });
-            const text = serializeNote(note.meta, note.body);
+            const text = note.text;
             const totalChars = Array.from(text).length;
             if (typeof params.offset_chars === "number" && params.offset_chars > totalChars)
                 return output({ error: `offset_chars ${params.offset_chars} is past the end: the note has ${totalChars} chars; the largest legal offset is ${totalChars} (an empty end-read)`, address: params.address, offset_chars: params.offset_chars, total_chars: totalChars });
-            const created_at = localIso(note.meta.created_at);
-            const updated_at = localIso(note.meta.updated_at);
-            const limit_chars = Math.min(params.limit_chars ?? DEFAULT_READ_WINDOW_CHARS, MAX_READ_WINDOW_CHARS);
             return readCharacterWindow(text, params.offset_chars, params.limit_chars, (window) => {
                 const { content, ...rest } = window;
-                return outputRaw(characterWindowHeader(params.address, window, ` · ${note.resolvedScope} · created ${created_at} · updated ${updated_at}`), content, { address: params.address, scope: note.resolvedScope, ...rest, limit_chars, created_at, updated_at });
+                return outputRaw(readWindowBlock([["address", params.address]], window), content, { address: params.address, ...rest });
             }, (result) => withinTextBudget(result.content[0].text));
         },
     }));
     pi.registerTool(defineTool({
         name: "notes_list", label: "Notes list",
-        description: `List note files as rows carrying address, scope, origin, status, stale, size_bytes, created_at, and updated_at, most recently updated first. ${ADDRESS_DESCRIPTION} All three homes are merged. A glob pattern (* within a path segment, ** across segments) filters full address strings: *.md is session-only, @project/** is project-only, and ** covers every home.`,
+        description: `List note files as rows carrying address, updated_at, and stale, most recently updated first. ${ADDRESS_DESCRIPTION} All three homes are merged. A glob pattern (* within a path segment, ** across segments) filters full address strings: *.md is session-only, @project/** is project-only, and ** covers every home.`,
         parameters: Type.Object({ pattern: nullableString(), cursor: cursor(), max_results: positiveInteger() }, { additionalProperties: false }),
         async execute(_id, params, _signal, _update, ctx) {
             let rows;
@@ -96,7 +89,7 @@ export function registerNotesTools(pi) {
             catch (error) {
                 return failure(error);
             }
-            const files = rows.map((row) => ({ address: row.address, scope: row.scope, origin: row.meta.origin, status: row.meta.status, stale: row.meta.stale, size_bytes: row.sizeBytes, created_at: localIso(row.meta.created_at), updated_at: localIso(row.meta.updated_at) }));
+            const files = rows.map((row) => ({ address: row.address, stale: row.meta.stale, updated_at: localIso(row.meta.updated_at) }));
             return output(page(files, params.cursor ?? 0, "files", params.max_results, (file, fits) => {
                 if (fits(file))
                     return file;
@@ -107,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} All three homes are merged and every entry carries its full address and derived scope. 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 (the body-absolute code-point offset of the earliest match).`,
+        description: `Case-sensitive literal substring search over note bodies; query is one string or several (OR), each matched line appears once. ${ADDRESS_DESCRIPTION} All three homes are merged and every entry carries its full address. 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);
@@ -120,8 +113,8 @@ export function registerNotesTools(pi) {
             }
             const maxPerFile = params.max_matches_per_file ?? Number.POSITIVE_INFINITY;
             const result = rows.map((row) => {
-                const matches = row.matches.map((match) => ({ line: match.line, text: match.text, truncated: false, total_chars: Array.from(match.text).length, offset_chars: match.offsetChars }));
-                return { address: row.address, scope: row.scope, created_at: localIso(row.meta.created_at), updated_at: localIso(row.meta.updated_at), matches_total: matches.length, matches: matches.slice(0, maxPerFile) };
+                const matches = row.matches.map((match) => ({ line: match.line, text: match.text, truncated: false, offset_chars: match.offsetChars }));
+                return { address: row.address, updated_at: localIso(row.meta.updated_at), stale: row.meta.stale, matches_total: matches.length, matches: matches.slice(0, maxPerFile) };
             });
             const fitFile = (file, fits) => {
                 if (fits(file))

package/dist/src/reset-lifecycle.js

@@ -3,38 +3,40 @@ export function registerResetLifecycle(pi, options) {
     let state = { phase: "idle" };
     let handledEntry;
     let active = true;
+    const release = (attempt) => {
+        if (attempt.settled)
+            return;
+        attempt.settled = true;
+        if (state.phase === "compacting" && state.attempt === attempt) {
+            state = { phase: "idle" };
+            handledEntry = undefined;
+        }
+        attempt.release();
+    };
     const clear = () => {
+        if (state.phase === "compacting")
+            release(state.attempt);
         state = { phase: "idle" };
         handledEntry = undefined;
     };
     const valid = (request, ctx) => active && options.isEnabled() && state.phase === "compacting" && state.attempt === request && ctx.sessionManager.getSessionId() === request.sessionId;
-    // State is intentionally not resumed from a pending request: a loaded session must
-    // not execute work from a tool that belonged to a previous runtime or tree branch.
-    pi.on("session_start", () => { clear(); active = true; });
-    pi.on("session_shutdown", () => { clear(); active = false; });
-    pi.on("session_tree", clear);
-    pi.on("agent_end", (_event, ctx) => {
-        if (!active || !options.isEnabled())
-            return;
-        if (ctx.signal?.aborted) {
-            // Esc cancels the user's run. Do not reset or resurrect it at settled.
-            state = { phase: "idle" };
-            return;
-        }
-    });
-    pi.on("agent_settled", (_event, ctx) => {
-        if (!active || !options.isEnabled() || state.phase === "compacting" || !ctx.isIdle())
-            return;
-        if (state.phase !== "requested")
-            return;
-        // One owner for requested resets. Consume the request before any external call;
-        // repeated settled events and reentrant callbacks are harmless.
-        const request = { completed: false, sessionId: ctx.sessionManager.getSessionId(), explicit: true };
+    const begin = (ctx) => {
+        let releaseWait;
+        const request = {
+            completed: false,
+            explicit: true,
+            nextRequested: false,
+            continuationStarted: false,
+            sessionId: ctx.sessionManager.getSessionId(),
+            settled: false,
+            wait: new Promise((resolve) => { releaseWait = resolve; }),
+            release: () => releaseWait(),
+        };
         state = { phase: "compacting", attempt: request };
         const onError = (error) => {
             if (!valid(request, ctx))
                 return;
-            state = { phase: "idle" };
+            release(request);
             // Do not retry from settled in a tight loop. A later prompt may trigger a
             // native reset or explicitly request one.
             ctx.ui.notify(`pi-context: reset did not complete (${error.message}). The conversation is retained; resume with another prompt.`, "warning");
@@ -44,13 +46,24 @@ export function registerResetLifecycle(pi, options) {
                 onComplete: () => {
                     if (!valid(request, ctx))
                         return;
-                    state = { phase: "idle" };
                     // session_compact only confirms the boundary. onComplete runs after
                     // Pi clears compaction state; sending inside the hook starts too early.
                     // A queued user prompt may already have started at compaction_end.
                     if (request.completed && ctx.isIdle() && !ctx.hasPendingMessages()) {
-                        pi.sendMessage(options.continuation, { triggerTurn: true });
+                        // The SDK detaches sendMessage, so own the next settled event before
+                        // starting it. The originating agent_settled handler awaits wait.
+                        if (request.continuationStarted)
+                            return;
+                        request.continuationStarted = true;
+                        try {
+                            pi.sendMessage(options.continuation, { triggerTurn: true });
+                        }
+                        catch (error) {
+                            onError(error instanceof Error ? error : new Error(String(error)));
+                        }
+                        return;
                     }
+                    release(request);
                 },
                 onError,
             });
@@ -58,6 +71,42 @@ export function registerResetLifecycle(pi, options) {
         catch (error) {
             onError(error instanceof Error ? error : new Error(String(error)));
         }
+        return request;
+    };
+    // State is intentionally not resumed from a pending request: a loaded session must
+    // not execute work from a tool that belonged to a previous runtime or tree branch.
+    pi.on("session_start", () => { clear(); active = true; });
+    pi.on("session_shutdown", () => { clear(); active = false; });
+    pi.on("session_tree", clear);
+    pi.on("agent_end", (_event, ctx) => {
+        if (!active || !options.isEnabled())
+            return;
+        if (ctx.signal?.aborted) {
+            // Esc cancels the user's run. Do not reset or resurrect it at settled.
+            clear();
+        }
+    });
+    pi.on("agent_settled", (_event, ctx) => {
+        if (!active || !options.isEnabled() || !ctx.isIdle())
+            return;
+        if (state.phase === "compacting" && state.attempt.continuationStarted) {
+            const preceding = state.attempt;
+            if (!preceding.nextRequested) {
+                release(preceding);
+                return;
+            }
+            // This settled event belongs to the continuation started by preceding.
+            // If it requested another reset, retain preceding until that reset's own
+            // continuation settles. Its eventual nested handler only releases its own
+            // waiter, so it never awaits itself.
+            const next = begin(ctx);
+            return next.wait.then(() => release(preceding));
+        }
+        if (state.phase !== "requested")
+            return;
+        // One owner for requested resets. Consume the request before any external call;
+        // repeated settled events and reentrant callbacks are harmless.
+        return begin(ctx).wait;
     });
     pi.on("session_before_compact", (event, ctx) => {
         if (!active || !options.isEnabled())
@@ -91,10 +140,15 @@ export function registerResetLifecycle(pi, options) {
     });
     return {
         request() {
-            const pending = state.phase !== "idle";
-            if (!pending)
+            if (state.phase === "idle") {
                 state = { phase: "requested" };
-            return pending ? "rollover_already_pending" : "rollover_requested";
+                return "rollover_requested";
+            }
+            if (state.phase === "compacting" && state.attempt.continuationStarted && !state.attempt.nextRequested) {
+                state.attempt.nextRequested = true;
+                return "rollover_requested";
+            }
+            return "rollover_already_pending";
         },
         clear,
     };

package/dist/src/tool-output.js

@@ -102,16 +102,14 @@ export function readCharacterWindow(text, offsetChars, limitChars, render, measu
     return render(build(content));
 }
 /**
- * One-line bracketed header preceding a raw character-window payload: the identity, the
- * delivered char range, and either the resume cursor or `end`. `tail` appends extra
- * metadata (notes add their timestamps) inside the same brackets.
+ * Fixed metadata block preceding any raw character-window payload. Callers supply their
+ * source identity fields in wire order; range and continuation semantics are shared.
  */
-export function characterWindowHeader(identity, window, tail = "") {
-    // The range end is offset + delivered count, never `total_chars`: a read resolved past the
-    // end delivers zero characters there, and the header must not render an inverted range.
+export function readWindowBlock(identity, window) {
     const end = window.offset_chars + Array.from(window.content).length;
-    const resume = window.next_offset_chars === null ? "end" : `continue at offset_chars=${window.next_offset_chars}`;
-    return `[${identity} · chars ${window.offset_chars}-${end} of ${window.total_chars} · ${resume}${tail}]`;
+    const next = window.next_offset_chars === null ? "null" : String(window.next_offset_chars);
+    const fields = identity.map(([name, value]) => `${name}: ${value}`).join("\n");
+    return `--- READ WINDOW ---\n${fields}\nchars: [${window.offset_chars},${end}) of ${window.total_chars}\nnext_offset_chars: ${next}\n`;
 }
 /**
  * Code-point offset of the earliest occurrence of any of `queries` in `text`, or 0 when
@@ -166,9 +164,8 @@ export function output(value, details, terminate = false) {
     return { content: [{ type: "text", text: json(value) }], details, terminate };
 }
 /**
- * Encode a prose payload as raw text: a one-line bracketed metadata header, then the payload
- * verbatim. The model reads the note or history item itself instead of a JSON envelope;
- * `details` carries the slim metadata object and never duplicates the payload.
+ * Encode a prose payload as raw text: metadata prefix, a blank line, then the payload
+ * verbatim. `details` carries the slim metadata object and never duplicates the payload.
  */
 export function outputRaw(header, content, details, terminate = false) {
     return { content: [{ type: "text", text: `${header}\n${content}` }], details, terminate };

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

@@ -7,7 +7,7 @@ import { createAssistantMessageEventStream } from "@earendil-works/pi-ai";
 import { createAgentSession, DefaultResourceLoader, ModelRuntime, SessionManager, SettingsManager } from "@earendil-works/pi-coding-agent";
 import piContext from "../src/index.js";
 import { WARNING_TYPE, GUIDANCE_TYPE } from "../src/protocol.js";
-for (const mode of ["golden", "write-error", "ignored-warning", "explicit", "uncompactable", "followup", "steering", "repeat", "abort"]) {
+for (const mode of ["golden", "write-error", "ignored-warning", "explicit", "uncompactable", "followup", "steering", "repeat", "nested", "immediate-dispose", "abort"]) {
     test(`real Pi loop: ${mode} reset preserves history and handles completion`, { timeout: 15000 }, async () => {
         const dir = mkdtempSync(join(tmpdir(), "pi-context-loop-"));
         const previousDir = process.env.PI_CODING_AGENT_DIR;
@@ -16,6 +16,7 @@ for (const mode of ["golden", "write-error", "ignored-warning", "explicit", "unc
         const notesRoot = mkdtempSync(join(tmpdir(), "pi-context-loop-notes-"));
         process.env.PI_NOTES_HOME = notesRoot;
         let session;
+        let disposed = false;
         try {
             const runtime = await ModelRuntime.create({ authPath: join(dir, "auth.json"), modelsPath: null, modelsStorePath: join(dir, "models"), refreshOnCreate: false });
             await runtime.setRuntimeApiKey("openai", "scripted-test-key");
@@ -23,7 +24,7 @@ for (const mode of ["golden", "write-error", "ignored-warning", "explicit", "unc
             assert.ok(base);
             const model = { ...base, contextWindow: 100000, maxTokens: 4096 };
             const usageMode = mode === "golden" || mode === "write-error" || mode === "ignored-warning";
-            const expectedResets = mode === "abort" || mode === "uncompactable" ? 0 : 1;
+            const expectedResets = mode === "abort" || mode === "uncompactable" ? 0 : mode === "nested" ? 2 : 1;
             // 0.86 split-turn cut can still summarize a turn prefix, so keepRecentTokens: 1 no longer
             // makes a reset uncompactable; a keep larger than the whole session keeps everything and does.
             const settings = { compaction: { enabled: usageMode, reserveTokens: 32768, keepRecentTokens: mode === "uncompactable" ? 1_000_000 : 200 }, retry: { enabled: false } };
@@ -36,7 +37,7 @@ for (const mode of ["golden", "write-error", "ignored-warning", "explicit", "unc
             let finish;
             let failFinish;
             const finished = new Promise((resolve, reject) => { finish = resolve; failFinish = reject; });
-            const finishTimeout = setTimeout(() => failFinish(new Error(`timed out waiting for ${mode} agent settlement`)), 5000);
+            const finishTimeout = setTimeout(() => failFinish(new Error(`timed out waiting for ${mode} agent settlement (resets=${resets}, settled=${settled}, requests=${requests.length})`)), 5000);
             const loader = new DefaultResourceLoader({ cwd: dir, agentDir: dir, settingsManager,
                 noExtensions: true, noSkills: true, noThemes: true, noPromptTemplates: true,
                 systemPromptOverride: () => "Use the tools as requested.", agentsFilesOverride: () => ({ agentsFiles: [] }),
@@ -83,7 +84,8 @@ for (const mode of ["golden", "write-error", "ignored-warning", "explicit", "unc
                     freshTurns++;
                 const sawWarning = request.includes("Your memory is about to be erased");
                 const sawGuidance = request.includes("Your brain is almost out of room");
-                const explicitReset = (n === 1 && !usageMode && mode !== "uncompactable") || (mode === "repeat" && (n === 1 || n === 3));
+                const explicitReset = (n === 1 && !usageMode && mode !== "uncompactable") || (mode === "repeat" && (n === 1 || n === 3)) || (mode === "nested" && n === 3);
+                const nestedCheckpoint = mode === "nested" && n === 2;
                 const checkpoint = usageMode && sawWarning && !checkpointed && mode !== "ignored-warning";
                 if (checkpoint)
                     checkpointed = true;
@@ -92,11 +94,11 @@ for (const mode of ["golden", "write-error", "ignored-warning", "explicit", "unc
                 // window's reminder. "ignored-warning" keeps working instead of checkpointing.
                 const probe = usageMode && !checkpoint && ((!fresh && !sawWarning) || (mode === "ignored-warning" && sawWarning) || (fresh && freshTurns === 2 && !sawGuidance));
                 const tokens = usageMode ? (fresh ? (freshTurns === 1 ? 100 : 50000) : sawWarning ? 70000 : n === 1 ? 50000 : 60000) : 100;
-                const tool = explicitReset || (mode === "uncompactable" && n === 1);
-                const call = probe ? "get_context_remaining" : checkpoint ? "notes_write" : tool ? "new_context" : undefined;
+                const tool = explicitReset || nestedCheckpoint || (mode === "uncompactable" && n === 1);
+                const call = probe ? "get_context_remaining" : checkpoint || nestedCheckpoint ? "notes_write" : tool ? "new_context" : undefined;
                 const message = { role: "assistant", api: model.api, provider: model.provider, model: model.id,
                     content: probe ? [{ type: "toolCall", id: "probe-call", name: "get_context_remaining", arguments: {} }]
-                        : checkpoint ? [{ type: "toolCall", id: "checkpoint-call", name: "notes_write", arguments: { address: mode === "write-error" ? "../invalid.md" : "checkpoint.md", content: "CHECKPOINT_SENTINEL" } }]
+                        : checkpoint || nestedCheckpoint ? [{ type: "toolCall", id: "checkpoint-call", name: "notes_write", arguments: { address: mode === "write-error" ? "../invalid.md" : "checkpoint.md", content: nestedCheckpoint ? "NESTED_RESET_PADDING ".repeat(300) : "CHECKPOINT_SENTINEL" } }]
                             : tool ? [{ type: "toolCall", id: "reset-call", name: "new_context", arguments: {} }]
                                 : [{ type: "text", text: fresh ? "Resumed." : "Working." }],
                     stopReason: call ? "toolUse" : "stop", timestamp: Date.now(),
@@ -116,9 +118,18 @@ for (const mode of ["golden", "write-error", "ignored-warning", "explicit", "unc
                 }
             });
             await session.prompt("OLD_CONTEXT_SENTINEL: save progress and continue the task.");
+            if (mode === "immediate-dispose") {
+                // prompt() must not resolve after compaction merely because sendMessage is
+                // detached: by this point the continuation has settled and answered.
+                session.dispose();
+                disposed = true;
+                assert.ok(settled >= 2, "the continuation settles before the originating prompt resolves");
+                assert.ok(requests.length >= 2 && !requests.at(-1).includes("OLD_CONTEXT_SENTINEL"), "the resumed answer exists before immediate disposal");
+            }
             await finished;
             clearTimeout(finishTimeout);
-            await session.waitForIdle();
+            if (!disposed)
+                await session.waitForIdle();
             if (mode === "abort") {
                 assert.equal(resets, 0, "user cancellation clears pending rollover");
                 assert.equal(requests.length, 1, "no continuation resurrects the cancelled run");
@@ -169,6 +180,10 @@ for (const mode of ["golden", "write-error", "ignored-warning", "explicit", "unc
                 const queuedEntries = sm.getBranch().filter((entry) => entry.type === "message" && JSON.stringify(entry.message).includes("QUEUED_INPUT_SENTINEL"));
                 assert.equal(queuedEntries.length, 1, "one durable user input");
             }
+            if (mode === "nested") {
+                assert.equal(resets, 2, "a continuation-requested reset forms a second completed handoff");
+                assert.equal(new Set(sm.getBranch().filter((entry) => entry.type === "compaction").map((entry) => JSON.stringify(entry.details))).size, 2);
+            }
             if (mode === "repeat") {
                 const nextFinished = new Promise((resolve) => { finish = resolve; });
                 targetResets = 2;
@@ -198,7 +213,8 @@ for (const mode of ["golden", "write-error", "ignored-warning", "explicit", "unc
             }
         }
         finally {
-            session?.dispose();
+            if (!disposed)
+                session?.dispose();
             if (previousDir === undefined)
                 delete process.env.PI_CODING_AGENT_DIR;
             else

package/dist/test/coherence.test.js

@@ -71,25 +71,19 @@ function assertWithinBudget(result, label) {
 function appendText(sessionManager, text) {
     return sessionManager.appendMessage({ role: "user", content: [{ type: "text", text }], timestamp: Date.now() });
 }
-/**
- * Decode a raw read (notes_read / history_read): a one-line bracketed header, then
- * the payload verbatim (which may itself contain newlines), so split on the first newline only.
- */
+/** Decode either raw read through the shared READ WINDOW grammar without including metadata in the payload. */
 function resultRead(result) {
     const text = result.content[0];
     assert.ok(text && text.type === "text", "read result carries text");
-    const newline = text.text.indexOf("\n");
-    assert.ok(newline !== -1, "raw read carries a header line and a payload");
-    const header = text.text.slice(0, newline);
-    const content = text.text.slice(newline + 1);
-    assert.match(header, /^\[/, "the header is bracketed");
-    assert.match(header, /\]$/, "the header closes its bracket");
-    const match = header.match(/ · chars (\d+)-(\d+) of (\d+) · (end|continue at offset_chars=(\d+))/);
-    assert.ok(match, `read header names the char range and resume cursor: ${header}`);
-    const offset_chars = Number(match[1]);
-    const total_chars = Number(match[3]);
-    const next_offset_chars = match[4] === "end" ? null : Number(match[5]);
-    assert.equal([...content].length, Number(match[2]) - offset_chars, "the header range matches the delivered payload");
+    const block = /^(--- READ WINDOW ---\n(?:[a-z_]+: [^\n]*\n)+chars: \[(\d+),(\d+)\) of (\d+)\nnext_offset_chars: (null|\d+)\n)\n/.exec(text.text);
+    assert.ok(block, "raw read carries one READ WINDOW block followed by exactly one blank line");
+    const header = block[1];
+    const content = text.text.slice(block[0].length);
+    const offset_chars = Number(block[2]);
+    const end = Number(block[3]);
+    const total_chars = Number(block[4]);
+    const next_offset_chars = block[5] === "null" ? null : Number(block[5]);
+    assert.equal([...content].length, end - offset_chars, "READ WINDOW range matches the delivered payload");
     return { header, content, offset_chars, total_chars, next_offset_chars };
 }
 const PROFILES = [
@@ -213,18 +207,17 @@ test("coherence: following the returned cursors reconstructs the original text e
     const searched = resultJson(await call(captured, "notes_search", { query: "历", pattern: "huge-cjk.md" }, ctx));
     const matchedFile = searched.files[0];
     const matched = matchedFile?.matches[0];
-    report.push(`notes_search: matches_total=${String(matchedFile?.matches_total)} returned=${String(matchedFile?.matches.length)} first match delivered ${codePoints(matched?.text ?? "")} of ${String(matched?.total_chars)} chars, truncated=${String(matched?.truncated)}`);
+    report.push(`notes_search: matches_total=${String(matchedFile?.matches_total)} returned=${String(matchedFile?.matches.length)} first match delivered ${codePoints(matched?.text ?? "")} chars, truncated=${String(matched?.truncated)}`);
     if (!matched)
         failures.push("notes_search dropped the over-budget matched line entirely");
     else {
         if (matched.truncated !== true)
             failures.push("notes_search does not flag the over-budget matched line as truncated");
-        if (matched.total_chars !== codePoints(hugeCjkLine))
-            failures.push(`notes_search match total_chars=${matched.total_chars}, expected ${codePoints(hugeCjkLine)}`);
         if (!hugeCjkLine.startsWith(matched.text))
             failures.push("notes_search delivered a non-prefix of the matched line");
-        if (codePoints(matched.text) >= matched.total_chars)
-            failures.push("notes_search claims the over-budget line fits in one response");
+        const atMatch = resultRead(await call(captured, "notes_read", { path: "huge-cjk.md", offset_chars: matched.offset_chars }, ctx));
+        if (!atMatch.content.startsWith("历"))
+            failures.push("notes_search offset does not start notes_read at the matched substring");
         const walked = stripLeadingFrontmatter(await walkNote(captured, ctx, "huge-cjk.md"));
         if (walked !== `${hugeCjkLine}\ntail line`)
             failures.push(`notes_search match line is not reconstructible from the note read: missing ${codePoints(`${hugeCjkLine}\ntail line`) - codePoints(walked)} chars`);
@@ -309,27 +302,30 @@ test("coherence: following the returned cursors reconstructs the original text e
         if (hugeEntry.matches[0]?.truncated !== true)
             failures.push("huge-many: the kept match is not flagged as a prefix");
     }
-    // --- notes_search addresses: a match's offset_chars is the body-absolute code-point
-    // position of the earliest query occurrence in its line, so search → read composes exactly like
-    // history's match_offset_chars two-stage.
+    // --- notes_search addresses: each match offset directly starts notes_read at the earliest
+    // query occurrence in its line, including multi-query OR.
     const addressLine1 = "pad ".repeat(50);
     const addressLine3 = `${"历".repeat(20)}needle-address here`;
     const addressLine4 = "zeta 历 needle-address";
     await call(captured, "notes_write", { path: "address.md", content: `${addressLine1}\nsecond\n${addressLine3}\n${addressLine4}` }, ctx);
-    const expectedAddress = codePoints(addressLine1) + 1 + codePoints("second") + 1 + 20;
     const addressHit = resultJson(await call(captured, "notes_search", { query: "needle-address", pattern: "address.md" }, ctx)).files[0]?.matches.find((match) => match.line === 3);
-    report.push(`notes_search address: line=${String(addressHit?.line)} offset_chars=${String(addressHit?.offset_chars)} expected=${expectedAddress}`);
-    const addressOffset = addressHit?.offset_chars;
-    if (typeof addressOffset !== "number")
-        failures.push("notes_search carries no offset_chars");
-    else if (addressOffset !== expectedAddress)
-        failures.push(`notes_search offset_chars=${addressOffset}, expected ${expectedAddress} (body-absolute, at the query)`);
-    // Multi-query OR: a line's address is the earliest occurrence of any query inside that line.
-    const line4Base = expectedAddress - 20 + codePoints(addressLine3) + 1;
+    report.push(`notes_search address: line=${String(addressHit?.line)} offset_chars=${String(addressHit?.offset_chars)}`);
+    if (addressHit === undefined)
+        failures.push("notes_search carries no line-three match");
+    else {
+        const atMatch = resultRead(await call(captured, "notes_read", { path: "address.md", offset_chars: addressHit.offset_chars }, ctx));
+        if (!atMatch.content.startsWith("needle-address"))
+            failures.push(`notes_search offset_chars=${addressHit.offset_chars} does not start at the line-three query`);
+    }
     const orLine4 = resultJson(await call(captured, "notes_search", { query: ["needle-address", "zeta"], pattern: "address.md" }, ctx)).files[0]?.matches.find((match) => match.line === 4);
-    report.push(`notes_search OR address: offset_chars=${String(orLine4?.offset_chars)} expected=${line4Base}`);
-    if (orLine4?.offset_chars !== line4Base)
-        failures.push(`notes_search OR offset_chars=${String(orLine4?.offset_chars)}, expected ${line4Base} (earliest of any query)`);
+    report.push(`notes_search OR address: offset_chars=${String(orLine4?.offset_chars)}`);
+    if (orLine4 === undefined)
+        failures.push("notes_search carries no line-four OR match");
+    else {
+        const atMatch = resultRead(await call(captured, "notes_read", { path: "address.md", offset_chars: orLine4.offset_chars }, ctx));
+        if (!atMatch.content.startsWith("zeta"))
+            failures.push(`notes_search OR offset_chars=${orLine4.offset_chars} does not start at the earliest line-four query`);
+    }
     // --- Negative offsets on both stores: a tail read reaches the end in one call, the response
     // echoes the resolved absolute offset, N >= total_chars reads from the start, and the cursor
     // law still holds when a negative-start page is cut short.