@astrosheep/pi-context 0.26.0 → 0.26.1

package/dist/test/notes.test.js

@@ -14,11 +14,9 @@ import test from "node:test";
 import { parseNote } from "../src/notes/frontmatter.js";
 import { projectKey } from "../src/notes/paths.js";
 import { listNotes, physicalPath, scopeDir } from "./helpers/notes.js";
-import { call, context, explicitBoot, installExtensionTestEnvironment, makeExtension, manager, resultJson, resultRead } from "./helpers/extension.js";
-const testEnvironment = installExtensionTestEnvironment("pi-context-notes");
-test.beforeEach(() => testEnvironment.beforeEach());
-test.afterEach(() => testEnvironment.afterEach());
-test.after(() => testEnvironment.dispose());
+import { call, context, explicitBoot, makeExtension, manager, resultJson, resultRead } from "./helpers/extension.js";
+import { installExtensionTestHooks } from "./helpers/extension-test-environment.js";
+const testEnvironment = installExtensionTestHooks("pi-context-notes");
 function freshRoot() {
     return testEnvironment.newNotesRoot();
 }
@@ -59,7 +57,7 @@ test("write lands a real markdown file with harness frontmatter and a pure body"
     const captured = makeExtension(session);
     const ctx = context(session);
     const sessionId = session.getSessionId();
-    const result = resultJson(await call(captured, "notes_write", { path: "a/b.md", content: "hello" }, ctx));
+    const result = resultJson(await call(captured, "notes_write", { address: "a/b.md", content: "hello" }, ctx));
     assert.deepEqual(Object.keys(result).sort(), ["address", "written"]);
     const file = physicalPath("session", "a/b.md", ctx);
     assert.equal(file, join(root, "pi", "session", sessionId, "a", "b.md"));
@@ -79,7 +77,7 @@ test("write lands a real markdown file with harness frontmatter and a pure body"
     assert.equal(result.written, true);
     assert.equal(existsSync(join(scopeDir("session", ctx), ".session.json")), false, "ownership is stored in note frontmatter, not a sidecar");
     // A leading YAML block in user content is stripped from the body.
-    await call(captured, "notes_write", { path: "stripped.md", content: "---\nscope: human\nnonsense: true\n---\nreal body" }, ctx);
+    await call(captured, "notes_write", { address: "stripped.md", content: "---\nscope: human\nnonsense: true\n---\nreal body" }, ctx);
     const stripped = readFileSync(physicalPath("session", "stripped.md", ctx), "utf8");
     assert.match(stripped, /\n---\n\nreal body$/, "the injected block is not part of the body");
     assert.equal(stripped.includes("nonsense"), false, "the injected block never reaches the file");
@@ -96,33 +94,33 @@ test("session-note project ownership is per note, persistent across sessions, an
     const firstSession = manager();
     const firstCaptured = makeExtension(firstSession);
     const firstCtx = context(firstSession, undefined, undefined, true, cwdA);
-    await call(firstCaptured, "notes_write", { path: "first.md", content: "first project session" }, firstCtx);
+    await call(firstCaptured, "notes_write", { address: "first.md", content: "first project session" }, firstCtx);
     const firstFile = physicalPath("session", "first.md", firstCtx);
     assert.equal(parseNote(readFileSync(firstFile, "utf8")).meta.project, projectA);
     const secondSession = manager();
     const secondCaptured = makeExtension(secondSession);
     const secondCtx = context(secondSession, undefined, undefined, true, cwdA);
-    await call(secondCaptured, "notes_write", { path: "second.md", content: "same project, another session" }, secondCtx);
+    await call(secondCaptured, "notes_write", { address: "second.md", content: "same project, another session" }, secondCtx);
     const secondFile = physicalPath("session", "second.md", secondCtx);
     assert.equal(parseNote(readFileSync(secondFile, "utf8")).meta.project, projectA, "another session in the same project carries the matching key");
     const thirdSession = manager();
     const thirdCaptured = makeExtension(thirdSession);
     const thirdCtx = context(thirdSession, undefined, undefined, true, cwdB);
-    await call(thirdCaptured, "notes_write", { path: "third.md", content: "different project" }, thirdCtx);
+    await call(thirdCaptured, "notes_write", { address: "third.md", content: "different project" }, thirdCtx);
     const thirdFile = physicalPath("session", "third.md", thirdCtx);
     assert.equal(parseNote(readFileSync(thirdFile, "utf8")).meta.project, projectB);
     const projectASessions = [firstFile, secondFile, thirdFile].filter((file) => parseNote(readFileSync(file, "utf8")).meta.project === projectA);
     assert.deepEqual(projectASessions.sort(), [firstFile, secondFile].sort(), "exact frontmatter project matching recognizes only sessions from the same project");
     const movedContext = context(firstSession, undefined, undefined, true, cwdB);
-    await call(firstCaptured, "notes_write", { path: "first.md", content: "overwritten from another cwd" }, movedContext);
+    await call(firstCaptured, "notes_write", { address: "first.md", content: "overwritten from another cwd" }, movedContext);
     assert.equal(parseNote(readFileSync(firstFile, "utf8")).meta.project, projectA, "overwriting an existing note does not silently reassign it");
-    await call(firstCaptured, "notes_edit", { path: "first.md", edits: [{ oldText: "overwritten", newText: "edited" }] }, movedContext);
+    await call(firstCaptured, "notes_edit", { address: "first.md", edits: [{ oldText: "overwritten", newText: "edited" }] }, movedContext);
     assert.equal(parseNote(readFileSync(firstFile, "utf8")).meta.project, projectA, "editing an existing note preserves its original project key");
-    await call(firstCaptured, "notes_read", { path: "first.md" }, movedContext);
+    await call(firstCaptured, "notes_read", { address: "first.md" }, movedContext);
     assert.equal(parseNote(readFileSync(firstFile, "utf8")).meta.project, projectA, "reading preserves existing project ownership");
-    await call(firstCaptured, "notes_write", { path: "new-from-project-b.md", content: "new note", scope: "session" }, movedContext);
+    await call(firstCaptured, "notes_write", { address: "new-from-project-b.md", content: "new note" }, movedContext);
     assert.equal(parseNote(readFileSync(physicalPath("session", "new-from-project-b.md", movedContext), "utf8")).meta.project, projectB, "only a newly-created session note uses the current project key");
-    await call(firstCaptured, "notes_write", { path: "project-note.md", content: "project home note", scope: "project" }, movedContext);
+    await call(firstCaptured, "notes_write", { address: "@project/project-note.md", content: "project home note" }, movedContext);
     assert.equal(parseNote(readFileSync(physicalPath("project", "project-note.md", movedContext), "utf8")).meta.project, undefined, "project-home notes do not receive session ownership metadata");
     assert.equal((await listNotes(movedContext, { scope: "session" })).length, 2, "project ownership remains frontmatter, not a separate note");
 });
@@ -165,8 +163,8 @@ legacy body`);
     assert.throws(() => parseNote(readFileSync(legacyFile, "utf8")), /legacy note metadata .*requires manual migration/);
     const legacyBytes = readFileSync(legacyFile, "utf8");
     await assert.rejects(() => listNotes(ctx, { scope: "session" }), /requires manual migration/);
-    await assert.rejects(() => call(captured, "notes_read", { path: "legacy.md" }, ctx), /requires manual migration/);
-    await assert.rejects(() => call(captured, "notes_write", { path: "legacy.md", content: "legacy overwritten" }, ctx), /requires manual migration/);
+    await assert.rejects(() => call(captured, "notes_read", { address: "legacy.md" }, ctx), /requires manual migration/);
+    await assert.rejects(() => call(captured, "notes_write", { address: "legacy.md", content: "legacy overwritten" }, ctx), /requires manual migration/);
     assert.equal(readFileSync(legacyFile, "utf8"), legacyBytes, "refusal preserves the unmigrated file byte-for-byte");
     const invalidFile = physicalPath("session", "invalid.md", ctx);
     writeFileSync(invalidFile, `---
@@ -183,7 +181,7 @@ project: 17
 invalid owner`);
     assert.equal(parseNote(readFileSync(invalidFile, "utf8")).meta.project, 17);
     assert.notEqual(parseNote(readFileSync(invalidFile, "utf8")).meta.project, projectKey(ctx.cwd), "invalid ownership does not match the current project key");
-    await call(captured, "notes_write", { path: "invalid.md", content: "still invalid" }, ctx);
+    await call(captured, "notes_write", { address: "invalid.md", content: "still invalid" }, ctx);
     assert.equal(parseNote(readFileSync(invalidFile, "utf8")).meta.project, 17, "an invalid value remains unknown and is not replaced with cwd-derived ownership");
     assert.equal(existsSync(join(scopeDir("session", ctx), ".session.json")), false, "new notes use no ownership sidecar");
 });
@@ -192,19 +190,19 @@ test("edit is body-scoped with named failures and a replace_all escape hatch", a
     const session = manager();
     const captured = makeExtension(session);
     const ctx = context(session);
-    await call(captured, "notes_write", { path: "edit.md", content: "alpha\nbeta\nbeta\ngamma" }, ctx);
-    const ambiguous = resultJson(await call(captured, "notes_edit", { path: "edit.md", edits: [{ oldText: "beta", newText: "B" }] }, ctx));
+    await call(captured, "notes_write", { address: "edit.md", content: "alpha\nbeta\nbeta\ngamma" }, ctx);
+    const ambiguous = resultJson(await call(captured, "notes_edit", { address: "edit.md", edits: [{ oldText: "beta", newText: "B" }] }, ctx));
     assert.match(ambiguous.error, /occurs 2 times/);
     assert.deepEqual(ambiguous.line_numbers, [2, 3], "the multi-match error carries every match line number");
-    const missing = resultJson(await call(captured, "notes_edit", { path: "edit.md", edits: [{ oldText: "absent", newText: "x" }] }, ctx));
+    const missing = resultJson(await call(captured, "notes_edit", { address: "edit.md", edits: [{ oldText: "absent", newText: "x" }] }, ctx));
     assert.equal(missing.edit_index, 0, "a zero-match anchor names the failing edit index");
-    const all = resultJson(await call(captured, "notes_edit", { path: "edit.md", edits: [{ oldText: "beta", newText: "B" }], replace_all: true }, ctx));
+    const all = resultJson(await call(captured, "notes_edit", { address: "edit.md", edits: [{ oldText: "beta", newText: "B" }], replace_all: true }, ctx));
     assert.equal(all.applied, 1);
     assert.equal(all.address, "edit.md");
     assertNoPublicScope(all, "notes_edit");
-    assert.equal(resultRead(await call(captured, "notes_read", { path: "edit.md" }, ctx)).content.endsWith("alpha\nB\nB\ngamma"), true, "replace_all replaces every occurrence");
+    assert.equal(resultRead(await call(captured, "notes_read", { address: "edit.md" }, ctx)).content.endsWith("alpha\nB\nB\ngamma"), true, "replace_all replaces every occurrence");
     // An anchor that occurs only in frontmatter is not matched: edits are body-only.
-    const frontmatterOnly = resultJson(await call(captured, "notes_edit", { path: "edit.md", edits: [{ oldText: "scope", newText: "x" }] }, ctx));
+    const frontmatterOnly = resultJson(await call(captured, "notes_edit", { address: "edit.md", edits: [{ oldText: "scope", newText: "x" }] }, ctx));
     assert.equal(frontmatterOnly.edit_index, 0, "a frontmatter-only anchor is not a body match");
 });
 test("nothing-to-do, not-found, atomic batches, and replace_all zero-match are named", async () => {
@@ -212,25 +210,25 @@ test("nothing-to-do, not-found, atomic batches, and replace_all zero-match are n
     const session = manager();
     const captured = makeExtension(session);
     const ctx = context(session);
-    const nameOnly = resultJson(await call(captured, "notes_edit", { path: "edit.md" }, ctx));
+    const nameOnly = resultJson(await call(captured, "notes_edit", { address: "edit.md" }, ctx));
     assert.match(nameOnly.error, /nothing to do/, "neither edits nor setters is a named error");
-    await call(captured, "notes_write", { path: "edit.md", content: "alpha\nbeta" }, ctx);
-    const empty = resultJson(await call(captured, "notes_edit", { path: "edit.md", edits: [] }, ctx));
+    await call(captured, "notes_write", { address: "edit.md", content: "alpha\nbeta" }, ctx);
+    const empty = resultJson(await call(captured, "notes_edit", { address: "edit.md", edits: [] }, ctx));
     assert.match(empty.error, /nothing to do/, "an empty edits list with no setters is also nothing to do");
-    const editMissing = resultJson(await call(captured, "notes_edit", { path: "missing.md", stale: true }, ctx));
+    const editMissing = resultJson(await call(captured, "notes_edit", { address: "missing.md", stale: true }, ctx));
     assert.equal(editMissing.error, "note not found");
-    const readMissing = resultJson(await call(captured, "notes_read", { path: "missing.md" }, ctx));
+    const readMissing = resultJson(await call(captured, "notes_read", { address: "missing.md" }, ctx));
     assert.equal(readMissing.error, "note not found");
-    assert.equal(readMissing.path, "missing.md");
+    assert.equal(readMissing.address, "missing.md");
     const file = physicalPath("session", "edit.md", ctx);
     const before = readFileSync(file, "utf8");
-    const failed = resultJson(await call(captured, "notes_edit", { path: "edit.md", edits: [{ oldText: "alpha", newText: "A" }, { oldText: "absent", newText: "x" }] }, ctx));
+    const failed = resultJson(await call(captured, "notes_edit", { address: "edit.md", edits: [{ oldText: "alpha", newText: "A" }, { oldText: "absent", newText: "x" }] }, ctx));
     assert.equal(failed.edit_index, 1, "the failing edit is named");
     assert.equal(readFileSync(file, "utf8"), before, "a failing batch leaves the file byte-identical, frontmatter included");
-    const applied = resultJson(await call(captured, "notes_edit", { path: "edit.md", edits: [{ oldText: "alpha", newText: "A" }, { oldText: "beta", newText: "B" }] }, ctx));
+    const applied = resultJson(await call(captured, "notes_edit", { address: "edit.md", edits: [{ oldText: "alpha", newText: "A" }, { oldText: "beta", newText: "B" }] }, ctx));
     assert.equal(applied.applied, 2);
-    assert.equal(resultRead(await call(captured, "notes_read", { path: "edit.md" }, ctx)).content.endsWith("A\nB"), true);
-    const zero = resultJson(await call(captured, "notes_edit", { path: "edit.md", edits: [{ oldText: "zzz", newText: "y" }], replace_all: true }, ctx));
+    assert.equal(resultRead(await call(captured, "notes_read", { address: "edit.md" }, ctx)).content.endsWith("A\nB"), true);
+    const zero = resultJson(await call(captured, "notes_edit", { address: "edit.md", edits: [{ oldText: "zzz", newText: "y" }], replace_all: true }, ctx));
     assert.equal(zero.edit_index, 0, "replace_all with zero matches is the same zero-match error, not a silent no-op");
 });
 test("all notes tool results use address as the only home identity", async () => {
@@ -270,16 +268,16 @@ test("list and search merge scopes and carry addresses; the path jail rejects es
     const session = manager();
     const captured = makeExtension(session);
     const ctx = context(session);
-    await call(captured, "notes_write", { path: "one.md", content: "needle one", scope: "session" }, ctx);
-    await call(captured, "notes_write", { path: "two.md", content: "needle two", scope: "project" }, ctx);
-    await call(captured, "notes_write", { path: "three.md", content: "needle three", scope: "human" }, ctx);
+    await call(captured, "notes_write", { address: "one.md", content: "needle one" }, ctx);
+    await call(captured, "notes_write", { address: "@project/two.md", content: "needle two" }, ctx);
+    await call(captured, "notes_write", { address: "@human/three.md", content: "needle three" }, ctx);
     const listed = resultJson(await call(captured, "notes_list", {}, ctx));
     assert.deepEqual([...listed.files].map((file) => file.address).sort(), ["@human/three.md", "@project/two.md", "one.md"], "every merged row carries its full address");
     for (const row of listed.files) {
         assert.deepEqual(Object.keys(row).sort(), ["address", "stale", "updated_at"]);
         assert.equal(row.stale, false);
     }
-    const scoped = resultJson(await call(captured, "notes_list", { scope: "human" }, ctx));
+    const scoped = resultJson(await call(captured, "notes_list", { pattern: "@human/**" }, ctx));
     assert.deepEqual(scoped.files.map((file) => file.address), ["@human/three.md"], "an address-pattern filter narrows the set");
     const searched = resultJson(await call(captured, "notes_search", { query: "needle" }, ctx));
     assert.equal(searched.files.length, 3, "literal search finds matches in every scope");
@@ -295,7 +293,7 @@ test("list and search merge scopes and carry addresses; the path jail rejects es
     const escaped = ["../evil", "/abs", "a\\b"];
     for (const tool of ["notes_write", "notes_edit", "notes_read"]) {
         for (const path of escaped) {
-            await assert.rejects(() => call(captured, tool, { path, content: "x", edits: [{ oldText: "a", newText: "b" }] }, ctx), `${tool} rejects ${path}`);
+            await assert.rejects(() => call(captured, tool, { address: path, content: "x", edits: [{ oldText: "a", newText: "b" }] }, ctx), `${tool} rejects ${path}`);
         }
     }
     await assert.rejects(() => call(captured, "notes_list", { pattern: "bad\\glob" }, ctx), /backslash/);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/pi-context",
-  "version": "0.26.0",
+  "version": "0.26.1",
   "type": "module",
   "main": "./dist/src/index.js",
   "types": "./dist/src/index.d.ts",

package/src/context/budget.ts

@@ -2,7 +2,7 @@ import { Type } from "@earendil-works/pi-ai";
 import { defineTool, type ExtensionAPI, type ExtensionContext, type SessionBoundaryDraft, type SettingsManager } from "@earendil-works/pi-coding-agent";
 import { GUIDANCE_TYPE, WARNING_CONTENT, WARNING_TYPE } from "../protocol.js";
 import { readThresholdSettings, type ResolvedThresholds, type ThresholdSettingsResolution } from "./thresholds.js";
-import { currentWindowId, hasWindowMessage, windowUsage } from "./context-window.js";
+import { currentWindowId, hasWindowMessage, isWindowMarker, rootWindowId, windowUsage } from "./context-window.js";
 import { tokenBudgetGuidance } from "./prompts.js";
 import { output } from "../tool-output.js";
 
@@ -45,16 +45,30 @@ export function registerBudget(
 	const invalidateThresholds = () => { cachedPolicy = undefined; };
 	let pendingGuidance: { windowId: string; content: string; remaining: number } | undefined;
 	let pendingWarning: { windowId: string; content: string; remaining: number } | undefined;
-	let pendingNotices: Array<{ windowId: string; customType: string; remaining: number }> = [];
-	const notifyCommittedReminders = (ctx: ExtensionContext) => {
-		const windowId = currentWindowId(ctx);
-		for (const notice of pendingNotices) {
-			if (notice.windowId !== windowId || !hasWindowMessage(ctx, notice.customType)) continue;
-			ctx.ui.notify(notice.customType === WARNING_TYPE
-				? "pi-context: Context almost full; close out the current memory window."
-				: "pi-context: Context running low; checkpoint your notes soon.", "warning");
+	let pendingNotices = new Map<string, { sessionId: string; windowId: string }>();
+	const noticeKey = (sessionId: string, windowId: string) => `${sessionId}:${windowId}`;
+	const warningCommittedInWindow = (ctx: ExtensionContext, notice: { sessionId: string; windowId: string }): boolean => {
+		if (ctx.sessionManager.getSessionId() !== notice.sessionId) return false;
+		let windowId = rootWindowId(notice.sessionId);
+		for (const entry of ctx.sessionManager.getBranch()) {
+			if (isWindowMarker(entry)) {
+				windowId = entry.data.windowId;
+				continue;
+			}
+			if (windowId === notice.windowId && entry.type === "custom_message" && entry.customType === WARNING_TYPE) return true;
+		}
+		return false;
+	};
+	const notifyCommittedWarnings = (ctx: ExtensionContext, settled = false) => {
+		for (const [key, notice] of pendingNotices) {
+			if (warningCommittedInWindow(ctx, notice)) {
+				pendingNotices.delete(key);
+				ctx.ui.notify("pi-context: Context almost full; close out the current memory window.", "warning");
+			} else if (settled) {
+				// An uncommitted draft must not be matched to a later manual warning.
+				pendingNotices.delete(key);
+			}
 		}
-		pendingNotices = [];
 	};
 
 	const clearStaged = () => {
@@ -63,7 +77,7 @@ export function registerBudget(
 	};
 	const resetForTransition = () => {
 		clearStaged();
-		pendingNotices = [];
+		pendingNotices.clear();
 		invalidateThresholds();
 		notifiedWarnings.clear();
 	};
@@ -76,7 +90,10 @@ export function registerBudget(
 		clearStaged();
 		const windowId = currentWindowId(ctx);
 		const drafts = staged.filter((draft): draft is NonNullable<typeof draft> => draft !== undefined && draft.windowId === windowId);
-		pendingNotices = drafts.map(({ windowId, customType, remaining }) => ({ windowId, customType, remaining }));
+		if (drafts.some((draft) => draft.customType === WARNING_TYPE)) {
+			const sessionId = ctx.sessionManager.getSessionId();
+			pendingNotices.set(noticeKey(sessionId, windowId), { sessionId, windowId });
+		}
 		return drafts.map((draft) => ({
 			type: "custom_message" as const,
 			customType: draft.customType,
@@ -89,12 +106,12 @@ export function registerBudget(
 	pi.on("session_tree", resetForTransition);
 	pi.on("model_select", resetForTransition);
 	pi.on("session_shutdown", resetForTransition);
-	// A request can fail before Pi emits turn_end. agent_settled is the public
-	// lifecycle point that must discard an uncommitted draft before the next prompt.
-	// UI notices follow committed reminders. Aborted requests can retry their drafts
-	// without showing the same low-budget notification twice.
+	// A warning can be committed at turn_end, before a tool turn or a reset changes the
+	// active window. Observe the active branch at public lifecycle boundaries and match
+	// the candidate against its originating window segment, not only the current window.
+	pi.on("turn_start", (_event, ctx) => notifyCommittedWarnings(ctx));
 	pi.on("agent_settled", (_event, ctx) => {
-		notifyCommittedReminders(ctx);
+		notifyCommittedWarnings(ctx, true);
 		clearStaged();
 	});
 	pi.on("context", (_event, ctx) => {
@@ -151,6 +168,6 @@ export function registerBudget(
 		automaticResetEnabled,
 		hardReserveDue,
 		consumeTurnEnd,
-		clear: () => { clearStaged(); pendingNotices = []; },
+		clear: () => { clearStaged(); pendingNotices.clear(); },
 	};
 }

package/src/notes/store.ts

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import type { Dirent } from "node:fs";
 import { mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
+import { earliestMatchOffsetChars } from "../text-match.js";
 import { assertAddress, assertGlobPattern, addressFor, globToRegExp } from "./address.js";
 import { snapshotNotesContext, type NotesContext } from "./context.js";
 import { MAX_NOTE_BYTES, MAX_NOTE_PATH_BYTES } from "./constants.js";
@@ -179,17 +180,6 @@ function matchLineNumbers(body: string, needle: string): number[] {
 	return lines;
 }
 
-/** Code-point offset of the earliest query occurrence, matching the serialized read text. */
-function earliestMatchOffsetChars(text: string, queries: string[]): number {
-	let earliest = -1;
-	for (const query of queries) {
-		const index = text.indexOf(query);
-		if (index < 0) continue;
-		if (earliest < 0 || index < earliest) earliest = index;
-	}
-	return earliest <= 0 ? 0 : Array.from(text.slice(0, earliest)).length;
-}
-
 /** Every mutation uses a tmp file renamed into place in the same directory. */
 async function atomicWrite(path: string, content: string): Promise<void> {
 	await mkdir(dirname(path), { recursive: true });
@@ -348,11 +338,10 @@ export function createNotesStore(input: NotesContext): NotesStore {
 		});
 	}
 
-	async function list(options: NotesQuery = {}): Promise<NoteRow[]> {
-		const stableOptions = { ...options } as NotesQuery;
-		const matcher = matcherFor(normalizePattern(stableOptions.pattern, context));
-		const rows: NoteRow[] = [];
-		for (const home of await homesFor(context, stableOptions)) {
+	async function* scan(options: NotesQuery): AsyncGenerator<Omit<NoteRow, "sizeBytes">> {
+		const matcher = matcherFor(normalizePattern(options.pattern, context));
+		const homes = await homesFor(context, options);
+		for (const home of homes) {
 			const scope = home.scope;
 			const root = scopeDir(scope, context, home.who);
 			for (const path of await walkMarkdown(root)) {
@@ -362,9 +351,17 @@ export function createNotesStore(input: NotesContext): NotesStore {
 				const raw = await withPathQueue(fullPath, () => readFile(fullPath, "utf8"));
 				const { meta, body } = parseNote(raw);
 				meta.scope = scope;
-				rows.push({ address, scope, path, meta, body, sizeBytes: Buffer.byteLength(body, "utf8") });
+				yield { address, scope, path, meta, body };
 			}
 		}
+	}
+
+	async function list(options: NotesQuery = {}): Promise<NoteRow[]> {
+		const stableOptions = { ...options } as NotesQuery;
+		const rows: NoteRow[] = [];
+		for await (const row of scan(stableOptions)) {
+			rows.push({ ...row, sizeBytes: Buffer.byteLength(row.body, "utf8") });
+		}
 		rows.sort((a, b) => b.meta.updatedAt - a.meta.updatedAt || a.address.localeCompare(b.address));
 		return rows;
 	}
@@ -372,29 +369,19 @@ export function createNotesStore(input: NotesContext): NotesStore {
 	async function search(queries: string[], options: NotesQuery = {}): Promise<NoteSearchRow[]> {
 		const stableQueries = [...queries];
 		const stableOptions = { ...options } as NotesQuery;
-		const matcher = matcherFor(normalizePattern(stableOptions.pattern, context));
 		const rows: NoteSearchRow[] = [];
-		for (const home of await homesFor(context, stableOptions)) {
-			const scope = home.scope;
-			const root = scopeDir(scope, context, home.who);
-			for (const path of await walkMarkdown(root)) {
-				const address = addressFor(context, scope, path, home.who);
-				if (matcher && !matcher.test(address)) continue;
-				const fullPath = join(root, path);
-				const raw = await withPathQueue(fullPath, () => readFile(fullPath, "utf8"));
-				const { meta, body } = parseNote(raw);
-				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 (stableQueries.some((query) => line.includes(query))) {
-						matches.push({ line: index + 1, text: line, offsetChars: serializedBodyOffset + baseChars + earliestMatchOffsetChars(line, stableQueries) });
-					}
-					baseChars += Array.from(line).length + 1;
+		for await (const note of scan(stableOptions)) {
+			const { address, path, scope, meta, body } = note;
+			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 (stableQueries.some((query) => line.includes(query))) {
+					matches.push({ line: index + 1, text: line, offsetChars: serializedBodyOffset + baseChars + earliestMatchOffsetChars(line, stableQueries) });
 				}
-				if (matches.length > 0) rows.push({ address, path, scope, meta, matches });
+				baseChars += Array.from(line).length + 1;
 			}
+			if (matches.length > 0) rows.push({ address, path, scope, meta, matches });
 		}
 		rows.sort((a, b) => a.address.localeCompare(b.address));
 		return rows;

package/src/text-match.ts

@@ -0,0 +1,13 @@
+/**
+ * Code-point offset of the earliest occurrence of any of `queries` in `text`, or 0 when
+ * none occurs. Shared by the two search tools so a match address is computed identically.
+ */
+export function earliestMatchOffsetChars(text: string, queries: string[]): number {
+	let earliest = -1;
+	for (const query of queries) {
+		const index = text.indexOf(query);
+		if (index < 0) continue;
+		if (earliest < 0 || index < earliest) earliest = index;
+	}
+	return earliest <= 0 ? 0 : Array.from(text.slice(0, earliest)).length;
+}

package/src/tool-output.ts

@@ -1,3 +1,5 @@
+export { earliestMatchOffsetChars } from "./text-match.js";
+
 export const TOOL_OUTPUT_MAX_BYTES = 32 * 1024;
 export const DEFAULT_READ_WINDOW_CHARS = 12000;
 export const MAX_READ_WINDOW_CHARS = 50000;
@@ -125,20 +127,6 @@ export function readWindowBlock(identity: ReadonlyArray<readonly [string, string
 	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
- * none occurs. Shared by the two search tools so a match address is computed identically.
- */
-export function earliestMatchOffsetChars(text: string, queries: string[]): number {
-	let earliest = -1;
-	for (const query of queries) {
-		const index = text.indexOf(query);
-		if (index < 0) continue;
-		if (earliest < 0 || index < earliest) earliest = index;
-	}
-	return earliest <= 0 ? 0 : Array.from(text.slice(0, earliest)).length;
-}
-
 /** Shrink a single page item to fit; only invoked when that item alone exceeds the budget. */
 export type ItemTruncator<T> = (item: T, fits: (candidate: T) => boolean) => T;