@astrosheep/pi-context 0.22.0 → 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.
 
@@ -59,6 +59,10 @@ The dreamer model is configured under the same key. `--dreamer <model pattern>`
 }
 ```
 
+## Check the notes store
+
+Run `dream doctor` (or `dream doctor --notes-home <dir>`) to check home layout, note frontmatter, concrete backtick-quoted note addresses, MAP entries, and lock presence/format. It is read-only: no model, git commits, directory creation, or repairs. Exit status is 0 when clean and 1 when issues are found. References needing an unavailable project context are reported as unresolved; prose and example/glob addresses are not validated. A present lock is reported without inferring process liveness.
+
 ## The dream lock
 
 The `dream` CLI takes an exclusive `.dream.lock` in the notes home with a single O_CREAT|O_EXCL creation. The lock is Git-style existence locking: an existing lock refuses a new run regardless of its contents, PID, or age, and `--force` bypasses only the scheduling and material gates, never the lock. A lock is released only by the run that acquired it (and repeated cleanup is harmless), so a live dream is never displaced.

package/dist/src/dream/cli.js

@@ -7,6 +7,7 @@ import { materialGate, timeGate } from "./gates.js";
 import { loadPlaybook, runDreamer } from "./runner.js";
 import { gitCommit } from "./git.js";
 import { readDreamerSettings } from "../thresholds.js";
+import { doctor } from "./doctor.js";
 import { notesRoot } from "../notes/paths.js";
 function args(argv) { const out = {}; for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -67,9 +68,20 @@ function finishDream(home, stamp, reportPath, failed, body, writes) {
     return failed || !audit.ok || reportError !== undefined ? 1 : 0;
 }
 export async function main(argv = process.argv.slice(2), deps = {}) {
+    if (argv[0] === "doctor") {
+        const options = args(argv.slice(1));
+        if (options.help) {
+            console.log("dream doctor [--notes-home <dir>] — read-only diagnostics; no model or repairs");
+            return 0;
+        }
+        const home = resolve(String(options["notes-home"] ?? notesRoot()));
+        const issues = doctor(home);
+        console.log(issues.length ? issues.join("\n") : `dream doctor: OK (${home})`);
+        return issues.length ? 1 : 0;
+    }
     const a = args(argv);
     if (a.help) {
-        console.log("dream --notes-home <dir> [--min-hours 24] [--min-sessions 3] [--force] [--dreamer <model pattern>] [--playbook <path>]\nDreamer model: --dreamer wins, else pi-context.dreamer from settings, else the automatic model. Default playbook: <installed package root>/playbook.md; --playbook overrides it.");
+        console.log("dream doctor [--notes-home <dir>] — read-only diagnostics\ndream --notes-home <dir> [--min-hours 24] [--min-sessions 3] [--force] [--dreamer <model pattern>] [--playbook <path>]\nDreamer model: --dreamer wins, else pi-context.dreamer from settings, else the automatic model. Default playbook: <installed package root>/playbook.md; --playbook overrides it.");
         return 0;
     }
     const home = resolve(String(a["notes-home"] ?? notesRoot()));

package/dist/src/dream/doctor.js

@@ -0,0 +1,138 @@
+import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
+import { basename, join, relative } from "node:path";
+import { assertAddress } from "../notes/address.js";
+/** Read-only diagnostics. Never follows symlinks or acquires/removes a dream lock. */
+export function doctor(home) {
+    const issues = [];
+    const report = (path, message) => issues.push(`${relative(home, path) || "."}: ${message}`);
+    const inspect = (path, action) => {
+        try {
+            action();
+        }
+        catch (error) {
+            report(path, `cannot inspect: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    };
+    const directory = (path) => {
+        const stat = lstatSync(path);
+        if (stat.isDirectory())
+            return true;
+        report(path, "expected a directory (symlinks are not followed); check its location/type");
+        return false;
+    };
+    const checkNote = (path, root, project) => {
+        const raw = readFileSync(path, "utf8");
+        const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(raw);
+        if (!match) {
+            report(path, "missing or unclosed frontmatter; add a valid metadata block");
+            return;
+        }
+        const fields = new Map();
+        for (const line of match[1].split(/\r?\n/)) {
+            const field = /^([\w]+):\s*(.*?)\s*$/.exec(line);
+            if (!field)
+                continue;
+            if (fields.has(field[1]))
+                report(path, `duplicate metadata key ${field[1]}; keep one value`);
+            fields.set(field[1], field[2].replace(/^(["'])(.*)\1$/, "$2"));
+        }
+        for (const [key, valid] of Object.entries({ origin: /^(user|self|external)$/, status: /^(active|superseded|pending|archived)$/, stale: /^(true|false)$/, access_count: /^\d+$/ })) {
+            if (!valid.test(fields.get(key) ?? ""))
+                report(path, `missing/invalid ${key}; repair frontmatter`);
+        }
+        for (const key of ["created_at", "updated_at", "last_accessed"]) {
+            const value = fields.get(key);
+            if (!value || !Number.isFinite(Date.parse(value)))
+                report(path, `missing/invalid ${key}; use an ISO timestamp`);
+        }
+        if (fields.has("scope"))
+            report(path, "obsolete scope field; remove it (home determines scope)");
+        // Check concrete, code-formatted addresses; examples/globs and prose are not links.
+        for (const link of raw.slice(match[0].length).matchAll(/`([^`\n]+)`/g)) {
+            const address = link[1];
+            if (!address.endsWith(".md") || /[<>*?\s]/.test(address))
+                continue;
+            if (!address.startsWith("@") && basename(path) !== "MAP.md")
+                continue;
+            try {
+                const parsed = assertAddress(address);
+                const targetHome = parsed.scope === "personal" ? join(home, "personal") : parsed.scope === "project" ? project : root;
+                if (!targetHome) {
+                    report(path, `${address}: project context unavailable; use a resolvable reference`);
+                    continue;
+                }
+                if (!existsSync(join(targetHome, parsed.path)))
+                    report(path, `${address}: target missing; update or remove the reference`);
+            }
+            catch {
+                report(path, `${address}: invalid address; use bare, @project/ or @personal/ addresses`);
+            }
+        }
+    };
+    const walk = (dir, root, project) => {
+        for (const name of readdirSync(dir)) {
+            const path = join(dir, name);
+            inspect(path, () => {
+                const stat = lstatSync(path);
+                if (stat.isSymbolicLink())
+                    report(path, "symlink not inspected; replace with a regular note/directory");
+                else if (stat.isDirectory())
+                    walk(path, root, project);
+                else if (stat.isFile() && name.endsWith(".md"))
+                    checkNote(path, root, project);
+                else
+                    report(path, "unexpected file in note home; inspect and relocate it");
+            });
+        }
+    };
+    inspect(home, () => {
+        if (!directory(home))
+            return;
+        for (const name of readdirSync(home)) {
+            const path = join(home, name);
+            inspect(path, () => {
+                if (name === "global") {
+                    report(path, "legacy home; manually migrate to personal/ without overwriting existing files");
+                    return;
+                }
+                if (name === ".dream.lock") {
+                    const valid = lstatSync(path).isFile() && /^[1-9]\d* [\da-f]{8}(?:-[\da-f]{4}){3}-[\da-f]{12}\s*$/i.test(readFileSync(path, "utf8"));
+                    report(path, `${valid ? "lock present" : "malformed lock"}; verify no dream is running before manual removal; liveness not inferred`);
+                    return;
+                }
+                if ([".git", "dreams", "snapshots", "trash", ".dream.lock.last-run"].includes(name))
+                    return;
+                if (name === "personal") {
+                    if (directory(path))
+                        walk(path, path);
+                    return;
+                }
+                if (name === "project" || name === "pi") {
+                    if (!directory(path))
+                        return;
+                    const homes = name === "pi" ? join(path, "session") : path;
+                    if (name === "pi") {
+                        for (const entry of readdirSync(path))
+                            if (entry !== "session")
+                                report(join(path, entry), "unexpected directory; expected pi/session/<id>/");
+                        if (!existsSync(homes) || !directory(homes))
+                            return;
+                    }
+                    for (const id of readdirSync(homes)) {
+                        const root = join(homes, id);
+                        inspect(root, () => {
+                            if (!directory(root))
+                                return;
+                            if (name === "project" && !/^.+-[\da-f]{8}$/.test(id))
+                                report(root, "invalid project key; expected <name>-<8 hex>");
+                            walk(root, root, name === "project" ? root : undefined);
+                        });
+                    }
+                    return;
+                }
+                report(path, "unexpected root entry; expected personal/, project/, pi/session/ or dream artifacts");
+            });
+        }
+    });
+    return issues;
+}

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 };