@astrosheep/pi-context 0.22.0 → 0.23.0

package/package.json

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

package/src/dream/cli.ts

@@ -7,6 +7,7 @@ import { materialGate, timeGate } from "./gates.js";
 import { loadPlaybook, runDreamer, type DreamerSessionFactory, type DreamResult, type DreamWrite } from "./runner.js";
 import { gitCommit } from "./git.js";
 import { readDreamerSettings, type DreamerSetting } from "../thresholds.js";
+import { doctor } from "./doctor.js";
 import { notesRoot } from "../notes/paths.js";
 
 function args(argv: string[]) { const out: Record<string, string | boolean> = {}; for (let i=0;i<argv.length;i++) { const a=argv[i]!; if (a === "--force" || a === "--help") out[a.slice(2)] = true; else if (a.startsWith("--")) out[a.slice(2)] = argv[++i] ?? ""; } return out; }
@@ -55,7 +56,15 @@ function finishDream(home: string, stamp: string, reportPath: string, failed: bo
 }
 
 export async function main(argv = process.argv.slice(2), deps: DreamDependencies = {}): Promise<number> {
-	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."); return 0; }
+	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 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())); process.env.PI_NOTES_HOME = home; mkdirSync(home, { recursive: true });
 	const lockPath = join(home, ".dream.lock"); const stampPath = lastRunPath(lockPath);
 	const minHours = Number(a["min-hours"] ?? 24); const minSessions = Number(a["min-sessions"] ?? 3);

package/src/dream/doctor.ts

@@ -0,0 +1,97 @@
+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: string): string[] {
+	const issues: string[] = [];
+	const report = (path: string, message: string) => issues.push(`${relative(home, path) || "."}: ${message}`);
+	const inspect = (path: string, action: () => void) => {
+		try { action(); } catch (error) { report(path, `cannot inspect: ${error instanceof Error ? error.message : String(error)}`); }
+	};
+	const directory = (path: string): boolean => {
+		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: string, root: string, project?: string) => {
+		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<string, string>();
+		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: string, root: string, project?: string) => {
+		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/src/history-tools.ts

@@ -1,6 +1,6 @@
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool, type ExtensionAPI } 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";
 
@@ -61,7 +61,7 @@ export function registerHistoryTools(pi: ExtensionAPI) {
 	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);
@@ -72,10 +72,9 @@ export function registerHistoryTools(pi: ExtensionAPI) {
 			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/src/notes/store.ts

@@ -220,19 +220,25 @@ export function editNote(ctx: ExtensionContext, vpath: string, scope: Scope, edi
 	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: NoteMeta, scope: Scope, now: number): NoteMeta {
+	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: ExtensionContext, vpath: string, scope: Scope): { meta: NoteMeta; body: string; resolvedScope: Scope } | undefined {
+export function readNote(ctx: ExtensionContext, vpath: string, scope: Scope): { meta: NoteMeta; body: string; text: string; resolvedScope: Scope } | undefined {
 	assertVirtualPath(vpath);
 	const path = physicalPath(scope, vpath, ctx);
 	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). */
@@ -264,11 +270,12 @@ export function searchNotes(ctx: ExtensionContext, queries: string[], opts: { sc
 			if (matcher && !matcher.test(address)) 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: NoteMatch[] = [];
 			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/src/notes/tools.ts

@@ -1,10 +1,10 @@
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool, type ExtensionAPI } 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, type NoteMeta, type Origin } from "./frontmatter.js";
+import { type Origin } 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")], {
@@ -12,10 +12,6 @@ const ORIGIN = Type.Optional(Type.Union([Type.Literal("user"), Type.Literal("sel
 }));
 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: NoteMeta): Record<string, unknown> {
-	return { ...meta, created_at: localIso(meta.created_at), updated_at: localIso(meta.updated_at), last_accessed: localIso(meta.last_accessed) };
-}
-
 function failure(error: unknown) {
 	if (error instanceof NoteError) {
 		const payload: Record<string, unknown> = { error: error.message };
@@ -35,28 +31,28 @@ export function registerNotesTools(pi: ExtensionAPI) {
 			const content = params.content;
 			try {
 				const destination = assertAddress(params.address);
-				const { meta } = writeNote(ctx, destination.path, content, { scope: destination.scope, origin: (params.origin ?? "self") as Origin, 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") as Origin, stale: params.stale });
+				return output({ address: params.address, written: true });
 			} catch (error) { return failure(error); }
 		},
 	}));
 
 	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 as Origin | undefined, 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 as Origin | undefined, stale: params.stale, replaceAll: params.replace_all });
+				return output({ address: params.address, applied, diff });
 			} catch (error) { return failure(error); }
 		},
 	}));
 
 	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: ReturnType<typeof readNote>;
@@ -65,27 +61,24 @@ export function registerNotesTools(pi: ExtensionAPI) {
 				note = readNote(ctx, destination.path, destination.scope);
 			} catch (error) { return failure(error); }
 			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: ReturnType<typeof listNotes>;
 			try { rows = listNotes(ctx, { pattern: params.pattern ?? undefined }); } catch (error) { return failure(error); }
-			const files: Array<{ address: string; scope: string; origin: Origin; status: string; stale: boolean; size_bytes: number; created_at: string; updated_at: string; address_truncated?: boolean }> = 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: Array<{ address: string; stale: boolean; updated_at: string; address_truncated?: boolean }> = 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;
 				const address = middleTruncate(file.address, (candidate) => fits({ ...file, address: candidate, address_truncated: true }));
@@ -96,16 +89,16 @@ export function registerNotesTools(pi: ExtensionAPI) {
 
 	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);
 			let rows: ReturnType<typeof searchNotes>;
 			try { rows = searchNotes(ctx, queries, { pattern: params.pattern ?? undefined }); } catch (error) { return failure(error); }
 			const maxPerFile = params.max_matches_per_file ?? Number.POSITIVE_INFINITY;
-			const result: Array<{ address: string; scope: string; created_at: string; updated_at: string; matches_total: number; matches: Array<{ line: number; text: string; truncated: boolean; total_chars: number; offset_chars: number }>; address_truncated?: boolean }> = 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 result: Array<{ address: string; updated_at: string; stale: boolean; matches_total: number; matches: Array<{ line: number; text: string; truncated: boolean; offset_chars: number }>; address_truncated?: boolean }> = rows.map((row) => {
+				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: (typeof result)[number], fits: (candidate: (typeof result)[number]) => boolean) => {
 				if (fits(file)) return file;

package/src/reset-lifecycle.ts

@@ -12,7 +12,16 @@ export function registerResetLifecycle(pi: ExtensionAPI, options: {
 	isCurrentReset: (entryId: string, ctx: ExtensionContext) => boolean;
 	onReset: (entryId: string) => void;
 }) {
-	type Attempt = { completed: boolean; sessionId: string; explicit: boolean };
+	type Attempt = {
+		completed: boolean;
+		explicit: boolean;
+		nextRequested: boolean;
+		continuationStarted: boolean;
+		sessionId: string;
+		settled: boolean;
+		wait: Promise<void>;
+		release: () => void;
+	};
 	type Request =
 		| { phase: "idle" }
 		| { phase: "requested" }
@@ -21,38 +30,39 @@ export function registerResetLifecycle(pi: ExtensionAPI, options: {
 	let handledEntry: string | undefined;
 	let active = true;
 
+	const release = (attempt: 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: Attempt, ctx: ExtensionContext) =>
 		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: Attempt = { completed: false, sessionId: ctx.sessionManager.getSessionId(), explicit: true };
+	const begin = (ctx: ExtensionContext) => {
+		let releaseWait!: () => void;
+		const request: Attempt = {
+			completed: false,
+			explicit: true,
+			nextRequested: false,
+			continuationStarted: false,
+			sessionId: ctx.sessionManager.getSessionId(),
+			settled: false,
+			wait: new Promise<void>((resolve) => { releaseWait = resolve; }),
+			release: () => releaseWait(),
+		};
 		state = { phase: "compacting", attempt: request };
 		const onError = (error: 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");
@@ -61,19 +71,64 @@ export function registerResetLifecycle(pi: ExtensionAPI, options: {
 			ctx.compact({
 				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,
 			});
 		} 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) => {
@@ -103,9 +158,15 @@ export function registerResetLifecycle(pi: ExtensionAPI, options: {
 
 	return {
 		request() {
-			const pending = state.phase !== "idle";
-			if (!pending) state = { phase: "requested" };
-			return pending ? "rollover_already_pending" : "rollover_requested";
+			if (state.phase === "idle") {
+				state = { phase: "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/src/tool-output.ts

@@ -115,16 +115,14 @@ export function readCharacterWindow<T>(text: string, offsetChars: number | undef
 }
 
 /**
- * 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: string, window: CharacterWindow, tail = ""): string {
-	// 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: ReadonlyArray<readonly [string, string]>, window: CharacterWindow): string {
 	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`;
 }
 
 /**
@@ -183,9 +181,8 @@ export function output(value: unknown, details?: unknown, terminate = false) {
 }
 
 /**
- * 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: string, content: string, details: unknown, terminate = false) {
 	return { content: [{ type: "text" as const, text: `${header}\n${content}` }], details, terminate };