@astrosheep/pi-context 0.24.0 → 0.25.0

package/dist/test/history.integration.test.js

@@ -0,0 +1,316 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { historyFromSession } from "../src/index.js";
+import { TOOL_OUTPUT_MAX_BYTES } from "../src/tool-output.js";
+import { appendText, assertWithinBudget, call, context, installExtensionTestEnvironment, makeExtension, manager, objectSchema, resultJson, resultRead, } from "./helpers/extension.js";
+const testEnvironment = installExtensionTestEnvironment("pi-context-integration");
+test.beforeEach(() => testEnvironment.beforeEach());
+test.afterEach(() => testEnvironment.afterEach());
+test.after(() => testEnvironment.dispose());
+test("schemas cover the History/Notes actions plus reset controls", () => {
+    const captured = makeExtension(manager());
+    for (const name of [
+        "history_windows", "history_list", "history_read", "history_search",
+        "notes_list", "notes_read", "notes_search", "notes_edit", "notes_write",
+        "wipe_memory", "get_context_remaining",
+    ]) {
+        const tool = captured.tools.get(name);
+        assert.equal(objectSchema(tool)?.type, "object", name);
+    }
+    assert.equal(objectSchema(captured.tools.get("history_read"))?.required?.includes("item_id"), true);
+    // The write surface requires its body; the edit surface requires its anchors.
+    const writeSchema = captured.tools.get("notes_write")?.parameters;
+    assert.ok(writeSchema?.properties?.content, "notes_write exposes content");
+    assert.ok(writeSchema?.properties?.address, "notes_write exposes address");
+    assert.equal(writeSchema?.properties?.scope, undefined, "notes_write has no scope parameter");
+    assert.deepEqual([...(writeSchema?.required ?? [])].sort(), ["address", "content"], "notes_write requires address and content");
+    const editSchema = captured.tools.get("notes_edit")?.parameters;
+    assert.ok(editSchema?.properties?.edits, "notes_edit exposes edits");
+    assert.equal(editSchema?.properties?.scope, undefined, "notes_edit has no scope parameter");
+    assert.deepEqual([...(editSchema?.required ?? [])].sort(), ["address"], "notes_edit requires only address; edits are optional for metadata-only updates");
+    // Both read tools are the same character window: identical params, one offset sugar, no line surface.
+    for (const name of ["notes_read", "history_read"]) {
+        const schema = captured.tools.get(name)?.parameters;
+        assert.ok(schema?.properties?.offset_chars, `${name} exposes offset_chars`);
+        assert.ok(schema?.properties?.limit_chars, `${name} exposes limit_chars`);
+        assert.equal(schema?.properties?.offset_chars?.minimum, undefined, `${name} accepts negative offset_chars`);
+        assert.equal(schema?.properties?.limit_chars?.maximum, 50000, `${name} caps limit_chars at 50000`);
+    }
+    const noteReadSchema = captured.tools.get("notes_read")?.parameters;
+    assert.deepEqual(Object.keys(noteReadSchema?.properties ?? {}).sort(), ["address", "limit_chars", "offset_chars"], "notes_read exposes exactly address and character-window params");
+    for (const name of ["notes_write", "notes_edit", "notes_read", "notes_list", "notes_search"]) {
+        const schema = captured.tools.get(name)?.parameters;
+        assert.equal(schema?.properties?.scope, undefined, `${name} has no scope property`);
+        assert.equal(schema?.additionalProperties, false, `${name} rejects scope as an additional property`);
+    }
+});
+test("paged tool outputs stay bounded and cursors reconstruct history and notes", async () => {
+    const session = manager();
+    const captured = makeExtension(session);
+    const ctx = context(session);
+    const historyText = "历史内容-" + "x".repeat(50_000);
+    const historyIds = [appendText(session, "user", historyText), appendText(session, "user", historyText), appendText(session, "user", historyText)];
+    for (let index = 0; index < 10; index++)
+        appendText(session, "user", historyText);
+    const historyPages = [];
+    let cursor = 0;
+    let next = 0;
+    while (next !== null) {
+        const result = resultJson(await call(captured, "history_list", { recent_first: false, max_chars_per_item: 1200, cursor }, ctx));
+        assert.ok(Buffer.byteLength(JSON.stringify(result), "utf8") <= TOOL_OUTPUT_MAX_BYTES);
+        historyPages.push(...result.items);
+        next = result.next_cursor;
+        if (next !== null)
+            cursor = next;
+    }
+    assert.deepEqual(historyPages.filter((item) => historyIds.includes(item.item_id)).map((item) => item.item_id), historyIds);
+    const search = resultJson(await call(captured, "history_search", { query: "历史内容", recent_first: false, max_chars_per_item: 50_000 }, ctx));
+    assert.ok(Buffer.byteLength(JSON.stringify(search), "utf8") <= TOOL_OUTPUT_MAX_BYTES);
+    assert.notEqual(search.next_cursor, null);
+    const searchPages = [];
+    let searchOffset = 0;
+    let searchNext = 0;
+    while (searchNext !== null) {
+        const result = resultJson(await call(captured, "history_search", { query: "历史内容", recent_first: false, max_chars_per_item: 1200, cursor: searchOffset }, ctx));
+        assert.ok(Buffer.byteLength(JSON.stringify(result), "utf8") <= TOOL_OUTPUT_MAX_BYTES);
+        searchPages.push(...result.items);
+        searchNext = result.next_cursor;
+        if (searchNext !== null)
+            searchOffset = searchNext;
+    }
+    assert.equal(searchPages.length, 13);
+    assert.equal(searchNext, null);
+    const readParts = [];
+    let readOffset = 0;
+    let readNext = 0;
+    while (readNext !== null) {
+        const raw = await call(captured, "history_read", { window_id: historyFromSession(ctx)[0].windowId, item_id: historyIds[0], offset_chars: readOffset, limit_chars: 12000 }, ctx);
+        assertWithinBudget(raw, `history_read page at ${readOffset}`);
+        const result = resultRead(raw);
+        readParts.push(result.content);
+        readNext = result.next_offset_chars;
+        if (readNext !== null)
+            readOffset = readNext;
+    }
+    assert.equal(readParts.join(""), historyText);
+    for (let index = 0; index < 100; index++) {
+        await call(captured, "notes_write", { path: `page-${"x".repeat(120)}-${index}.md`, content: Array.from({ length: 1000 }, (_, line) => `needle ${line} ${"z".repeat(30)}`).join("\n") }, ctx);
+    }
+    const listPages = [];
+    let listOffset = 0;
+    let listNext = 0;
+    while (listNext !== null) {
+        const result = resultJson(await call(captured, "notes_list", { max_results: 300, cursor: listOffset }, ctx));
+        assert.ok(Buffer.byteLength(JSON.stringify(result), "utf8") <= TOOL_OUTPUT_MAX_BYTES);
+        listPages.push(...result.files.map((file) => file.path));
+        listNext = result.next_cursor;
+        if (listNext !== null)
+            listOffset = listNext;
+    }
+    assert.deepEqual([...listPages].sort((a, b) => a.localeCompare(b)), Array.from({ length: 100 }, (_, index) => `page-${"x".repeat(120)}-${index}.md`).sort((a, b) => a.localeCompare(b)));
+    assert.equal(listNext, null);
+    const searchFiles = [];
+    let notesSearchOffset = 0;
+    let notesSearchNext = 0;
+    while (notesSearchNext !== null) {
+        const result = resultJson(await call(captured, "notes_search", { query: "needle", max_matches_per_file: 100, max_files: 300, cursor: notesSearchOffset }, ctx));
+        assert.ok(Buffer.byteLength(JSON.stringify(result), "utf8") <= TOOL_OUTPUT_MAX_BYTES);
+        searchFiles.push(...result.files);
+        notesSearchNext = result.next_cursor;
+        if (notesSearchNext !== null)
+            notesSearchOffset = notesSearchNext;
+    }
+    assert.equal(searchFiles.length, 100);
+    assert.equal(notesSearchNext, null);
+    const bodyText = Array.from({ length: 1000 }, (_, line) => `needle ${line} ${"z".repeat(30)}`).join("\n");
+    const noteParts = [];
+    let noteOffset = 0;
+    let noteNext = 0;
+    while (noteNext !== null) {
+        const raw = await call(captured, "notes_read", { path: `page-${"x".repeat(120)}-0.md`, offset_chars: noteOffset }, ctx);
+        assertWithinBudget(raw, `notes_read page at ${noteOffset}`);
+        const result = resultRead(raw);
+        // The window is a plain prefix of the file, so the pages join by plain concatenation.
+        noteParts.push(result.content);
+        noteNext = result.next_offset_chars;
+        if (noteNext !== null)
+            noteOffset = noteNext;
+    }
+    const joined = noteParts.join("");
+    assert.ok(joined.startsWith("---\n"), "the frontmatter is delivered first");
+    assert.ok(joined.endsWith(bodyText), "cursor-following reconstructs the body");
+    assert.equal(noteNext, null);
+});
+test("a page cap limits the page, not the enumerable set: cursors stay truthful past the cap", async () => {
+    const session = manager();
+    const captured = makeExtension(session);
+    const ctx = context(session);
+    for (let index = 0; index < 60; index++) {
+        appendText(session, "user", `entry-${index}`);
+        appendText(session, "assistant", `reply-${index}`);
+    }
+    // history_list: 120 items with limit 50 page as 50/50/20, null only at the true end.
+    const windows = resultJson(await call(captured, "history_windows", {}, ctx));
+    assert.equal(windows.windows[0]?.item_count, 120);
+    const list = async (params) => resultJson(await call(captured, "history_list", params, ctx));
+    const first = await list({ limit: 50, recent_first: false, max_chars_per_item: 100 });
+    assert.equal(first.items.length, 50);
+    assert.equal(first.next_cursor, 50, "limit caps the page, not the enumerable set");
+    const second = await list({ limit: 50, cursor: 50, recent_first: false, max_chars_per_item: 100 });
+    assert.equal(second.items.length, 50);
+    assert.equal(second.next_cursor, 100);
+    const third = await list({ limit: 50, cursor: 100, recent_first: false, max_chars_per_item: 100 });
+    assert.equal(third.items.length, 20);
+    assert.equal(third.next_cursor, null, "null only at the true end");
+    // history_search: the same contract holds over the matching set.
+    const search = async (params) => resultJson(await call(captured, "history_search", params, ctx));
+    const searchFirst = await search({ query: "entry-", limit: 50, recent_first: false, max_chars_per_item: 100 });
+    assert.equal(searchFirst.items.length, 50);
+    assert.equal(searchFirst.next_cursor, 50);
+    const searchTail = await search({ query: "entry-", limit: 50, cursor: 50, recent_first: false, max_chars_per_item: 100 });
+    assert.equal(searchTail.items.length, 10);
+    assert.equal(searchTail.next_cursor, null);
+    // notes_search: max_files caps the page, not the matched files.
+    for (let index = 0; index < 7; index++)
+        await call(captured, "notes_write", { path: `needle-${index}.md`, content: "needle" }, ctx);
+    const notes = async (params) => resultJson(await call(captured, "notes_search", params, ctx));
+    const notesFirst = await notes({ query: "needle", max_files: 3 });
+    assert.equal(notesFirst.files.length, 3);
+    assert.equal(notesFirst.next_cursor, 3);
+    const notesSecond = await notes({ query: "needle", max_files: 3, cursor: 3 });
+    assert.equal(notesSecond.files.length, 3);
+    assert.equal(notesSecond.next_cursor, 6);
+    const notesTail = await notes({ query: "needle", max_files: 3, cursor: 6 });
+    assert.equal(notesTail.files.length, 1);
+    assert.equal(notesTail.next_cursor, null);
+});
+test("multi-query search: OR semantics, dedupe, and bare-string backward compatibility", async () => {
+    const session = manager();
+    const captured = makeExtension(session);
+    const ctx = context(session);
+    // One item matches both queries, one only the first, one only the second, one neither.
+    const bothId = appendText(session, "user", "alpha beta together");
+    const alphaId = appendText(session, "user", "alpha only");
+    const betaId = appendText(session, "assistant", "beta only");
+    const noneId = appendText(session, "user", "gamma only");
+    const historyIds = async (params) => resultJson(await call(captured, "history_search", { recent_first: false, ...params }, ctx)).items.map((item) => item.item_id);
+    const orIds = await historyIds({ query: ["alpha", "beta"] });
+    assert.deepEqual(orIds, [bothId, alphaId, betaId], "history: an item matching any query is returned once");
+    assert.equal(orIds.includes(noneId), false, "history: an item matching no query is not returned");
+    assert.deepEqual(await historyIds({ query: ["alpha"] }), [bothId, alphaId], "history: a one-element array searches that literal");
+    assert.deepEqual(await historyIds({ query: "alpha" }), orIds.filter((id) => id !== betaId), "history: a bare string still behaves exactly as before");
+    assert.deepEqual(await historyIds({ query: "alpha" }), await historyIds({ query: ["alpha"] }), "history: bare string equals the single-element list");
+    await call(captured, "notes_write", { path: "both.md", content: "alpha beta\nunrelated" }, ctx);
+    await call(captured, "notes_write", { path: "alpha.md", content: "alpha only" }, ctx);
+    await call(captured, "notes_write", { path: "beta.md", content: "beta only" }, ctx);
+    await call(captured, "notes_write", { path: "gamma.md", content: "gamma only" }, ctx);
+    const notesSearch = async (params) => resultJson(await call(captured, "notes_search", params, ctx)).files;
+    const orFiles = await notesSearch({ query: ["alpha", "beta"] });
+    assert.deepEqual(orFiles.map((file) => file.path), ["alpha.md", "beta.md", "both.md"], "notes: a file matching any query is returned once, path-ordered");
+    assert.equal(orFiles.find((file) => file.path === "both.md")?.matches.length, 1, "notes: one line containing both queries is reported once");
+    assert.deepEqual((await notesSearch({ query: ["alpha"] })).map((file) => file.path), ["alpha.md", "both.md"], "notes: a one-element array searches that literal");
+    assert.deepEqual((await notesSearch({ query: "alpha" })).map((file) => file.path), ["alpha.md", "both.md"], "notes: a bare string still behaves exactly as before");
+    assert.deepEqual((await notesSearch({ query: "alpha" })).map((file) => file.path), (await notesSearch({ query: ["alpha"] })).map((file) => file.path), "notes: bare string equals the single-element list");
+    assert.deepEqual((await notesSearch({ query: ["gamma"] })).map((file) => file.path), ["gamma.md"]);
+    // An empty array is an argument error, not a silently empty result set.
+    await assert.rejects(() => call(captured, "history_search", { query: [] }, ctx), /non-empty array of strings/, "history: empty query array is refused");
+    await assert.rejects(() => call(captured, "notes_search", { query: [] }, ctx), /non-empty array of strings/, "notes: empty query array is refused");
+    await assert.rejects(() => call(captured, "history_search", { query: ["alpha", 7] }, ctx), /elements must be strings/, "history: non-string query element is refused");
+    await assert.rejects(() => call(captured, "notes_search", { query: ["alpha", 7] }, ctx), /elements must be strings/, "notes: non-string query element is refused");
+});
+test("history_read delivers a prefix and next_offset_chars names the delivered count", async () => {
+    const session = manager();
+    const captured = makeExtension(session);
+    const ctx = context(session);
+    const original = "z".repeat(TOOL_OUTPUT_MAX_BYTES * 3);
+    const id = appendText(session, "user", original);
+    const rawRead = await call(captured, "history_read", { window_id: historyFromSession(ctx)[0].windowId, item_id: id, limit_chars: 50000 }, ctx);
+    assertWithinBudget(rawRead, "single history_read call");
+    const read = resultRead(rawRead);
+    assert.ok(read.content.length > 0, "the read is not empty");
+    assert.equal(read.content.includes("…"), false, "no marker is appended to the payload");
+    assert.ok(original.startsWith(read.content), "the delivered text is a prefix of the item");
+    assert.equal(read.total_chars, original.length);
+    assert.equal(read.header, `--- READ WINDOW ---\nwindow_id: ${historyFromSession(ctx)[0].windowId}\nitem_id: ${id}\nchars: [0,${read.next_offset_chars}) of ${read.total_chars}\nnext_offset_chars: ${read.next_offset_chars}\n`, "the paged history block names identities, half-open range, and resume cursor");
+    assert.deepEqual(Object.keys(read.details), ["window_id", "item_id", "offset_chars", "total_chars", "next_offset_chars"], "history_read details carries exactly the raw window identity and cursor metadata");
+    assert.equal("limit_chars" in read.details, false, "history_read details omits the request cap");
+    assert.equal("content" in read.details, false, "details never duplicates the payload");
+    assert.equal(read.next_offset_chars, read.offset_chars + Array.from(read.content).length, "the cursor is offset plus delivered code points");
+    assert.ok(read.next_offset_chars !== null && read.next_offset_chars < read.total_chars, "the cursor points at the first undelivered character");
+    // Following the cursor reaches the true end and reconstructs the item.
+    const parts = [read.content];
+    let offset = read.next_offset_chars;
+    let next = offset;
+    while (next !== null) {
+        const page = resultRead(await call(captured, "history_read", { window_id: historyFromSession(ctx)[0].windowId, item_id: id, offset_chars: offset, limit_chars: 50000 }, ctx));
+        assert.equal(page.header, `--- READ WINDOW ---\nwindow_id: ${historyFromSession(ctx)[0].windowId}\nitem_id: ${id}\nchars: [${page.offset_chars},${page.offset_chars + Array.from(page.content).length}) of ${page.total_chars}\nnext_offset_chars: ${page.next_offset_chars}\n`, "every history page retains the exact shared READ WINDOW block");
+        assert.equal(page.next_offset_chars, page.offset_chars + Array.from(page.content).length < page.total_chars ? page.offset_chars + Array.from(page.content).length : null, "the cursor is offset plus delivered, null only at item end");
+        parts.push(page.content);
+        next = page.next_offset_chars;
+        if (next !== null)
+            offset = next;
+    }
+    assert.equal(parts.join(""), original, "the cursors reconstruct the item exactly");
+});
+test("history items carry honest truncated/total_chars and max_chars_per_item:1 addresses them", async () => {
+    const session = manager();
+    const captured = makeExtension(session);
+    const ctx = context(session);
+    const content = `${'padding '.repeat(400)}NEEDLE${' trailing'.repeat(400)}`;
+    const id = appendText(session, "user", content);
+    const list = resultJson(await call(captured, "history_list", { recent_first: false, max_chars_per_item: 5 }, ctx));
+    const listed = list.items.find((item) => item.item_id === id);
+    assert.equal(listed.truncated, true, "a capped item is flagged truncated");
+    assert.equal(listed.total_chars, Array.from(content).length, "total_chars is the full code-point length");
+    assert.equal(listed.truncated_content, 'paddi', "the payload is the longest fitting prefix, with no marker");
+    assert.equal(listed.truncated_content.includes("…"), false);
+    const whole = resultJson(await call(captured, "history_list", { recent_first: false, max_chars_per_item: 50_000 }, ctx));
+    const untruncated = whole.items.find((item) => item.item_id === id);
+    assert.equal(untruncated.truncated, false, "an item that fits is not flagged truncated");
+    assert.equal(untruncated.truncated_content, content, "a fitting item is returned whole");
+    const addresses = resultJson(await call(captured, "history_search", { query: "NEEDLE", max_chars_per_item: 1 }, ctx));
+    const address = addresses.items.find((item) => item.item_id === id);
+    assert.equal(Array.from(address.truncated_content).length, 1, "max_chars_per_item:1 delivers one code point");
+    assert.equal(address.truncated, true);
+    assert.equal(address.total_chars, Array.from(content).length);
+    const resolved = resultRead(await call(captured, "history_read", { window_id: historyFromSession(ctx)[0].windowId, item_id: id, offset_chars: address.match_offset_chars, limit_chars: 6 }, ctx));
+    assert.ok(resolved.content.includes("NEEDLE"), "the address resolves to the query through history_read");
+});
+test("tool calls wear their own role and assistant text stays pure", async () => {
+    const session = manager();
+    const captured = makeExtension(session);
+    const ctx = context(session);
+    const turnId = session.appendMessage({
+        role: "assistant",
+        content: [
+            { type: "text", text: "on it" },
+            { type: "toolCall", id: "tc-1", name: "bash", arguments: { command: "keiyaku status" } },
+            { type: "toolCall", id: "tc-2", name: "notes_read", arguments: { path: "x.md" } },
+        ],
+        stopReason: "stop",
+        timestamp: Date.now(),
+    });
+    const windowId = historyFromSession(ctx)[0].windowId;
+    const listed = resultJson(await call(captured, "history_list", { recent_first: false, max_chars_per_item: 50_000 }, ctx));
+    const turn = listed.items.find((item) => item.item_id === turnId);
+    assert.equal(turn.role, "assistant");
+    assert.equal(turn.tool_name, null, "the turn's text item carries no tool identity");
+    assert.equal(turn.truncated_content, "on it", "the turn item keeps only the visible text");
+    const call1 = listed.items.find((item) => item.item_id === `${turnId}#0`);
+    assert.equal(call1.role, "tool_call");
+    assert.equal(call1.tool_name, "bash");
+    assert.equal(call1.truncated_content, JSON.stringify({ command: "keiyaku status" }), "a call item's content is the call's JSON arguments");
+    const call2 = listed.items.find((item) => item.item_id === `${turnId}#1`);
+    assert.equal(call2.tool_name, "notes_read");
+    // The invocation is searchable exactly where a searcher reaches for it: tool_call + tool_name.
+    const calls = resultJson(await call(captured, "history_search", { query: "keiyaku status", role: "tool_call", tool_name: "bash" }, ctx));
+    assert.deepEqual(calls.items.map((item) => item.item_id), [`${turnId}#0`], "the command line is found on the call item, not the turn");
+    const assistantCalls = resultJson(await call(captured, "history_search", { query: "keiyaku status", role: "assistant" }, ctx));
+    assert.equal(assistantCalls.items.length, 0, "calls never leak into assistant text");
+    const assistantText = resultJson(await call(captured, "history_search", { query: "on it", role: "assistant" }, ctx));
+    assert.deepEqual(assistantText.items.map((item) => item.item_id), [turnId], "assistant search returns the turn's text item only");
+    const outputs = resultJson(await call(captured, "history_search", { query: "keiyaku status", role: "tool" }, ctx));
+    assert.equal(outputs.items.length, 0, "nothing ran, so no output carries the command");
+    const resolved = resultRead(await call(captured, "history_read", { window_id: windowId, item_id: `${turnId}#0` }, ctx));
+    assert.equal(resolved.content, JSON.stringify({ command: "keiyaku status" }), "a call item resolves through history_read like any other");
+});

package/dist/test/notes.integration.test.js

@@ -0,0 +1,273 @@
+import assert from "node:assert/strict";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import test from "node:test";
+import { loadNotesSnapshot as loadNotesSnapshot } from "../src/notes/notes-snapshot.js";
+import { renderBootBlock } from "../src/context/prompts.js";
+import { localIso } from "../src/notes/frontmatter.js";
+import { physicalPath, scopeDir } from "../src/notes/paths.js";
+import { listNotes } from "../src/notes/store.js";
+import { TOOL_OUTPUT_MAX_BYTES } from "../src/tool-output.js";
+import { assertWithinBudget, call, context, explicitBoot, installExtensionTestEnvironment, makeExtension, manager, resultJson, resultRead, } from "./helpers/extension.js";
+const testEnvironment = installExtensionTestEnvironment("pi-context-integration");
+test.beforeEach(() => testEnvironment.beforeEach());
+test.afterEach(() => testEnvironment.afterEach());
+test.after(() => testEnvironment.dispose());
+test("notes_list is most-recently-updated first across merged scopes", async () => {
+    const session = manager();
+    const captured = makeExtension(session);
+    const ctx = context(session);
+    const put = (scope, path, updated) => {
+        const file = physicalPath(scope, path, ctx);
+        mkdirSync(dirname(file), { recursive: true });
+        writeFileSync(file, `---\nscope: ${scope}\norigin: self\nstatus: active\nstale: false\ncreated_at: ${localIso(updated - 1000)}\nupdated_at: ${localIso(updated)}\nlast_accessed: ${localIso(updated)}\naccess_count: 0\n---\n\nbody`);
+    };
+    const base = 1_700_000_000_000;
+    put("session", "b.md", base + 10);
+    put("session", "a.md", base + 10);
+    put("project", "c.md", base + 5);
+    put("human", "e.md", base + 20);
+    const files = async (params) => resultJson(await call(captured, "notes_list", params, ctx)).files;
+    assert.deepEqual((await files({})).map((file) => file.address), ["@human/e.md", "a.md", "b.md", "@project/c.md"], "updated_at descending with address ascending as the tiebreak");
+    // A same-path pair in two scopes keeps both rows; equal timestamps tie-break by scope name.
+    put("human", "a.md", base + 10);
+    assert.deepEqual((await files({})).filter((file) => file.address.endsWith("a.md")).map((file) => file.address), ["@human/a.md", "a.md"], "equal timestamps tie-break by full address");
+    assert.deepEqual((await files({ pattern: "*.md" })).map((file) => file.address), ["a.md", "b.md"], "a bare pattern narrows to the session home");
+});
+test("notes are real files that persist across sessions and round-trip Unicode", async () => {
+    const original = manager();
+    const captured = makeExtension(original);
+    const ctx = context(original);
+    await call(captured, "notes_write", { path: "checkpoint/进度.md", content: "第一行\nneedle Café", scope: "human" }, ctx);
+    // A brand-new session over the same physical root sees the human note: nothing is replayed
+    // from session entries, the file itself is the durable artifact.
+    const restored = manager();
+    const restoredCaptured = makeExtension(restored);
+    const restoredCtx = context(restored);
+    const rawRead = await call(restoredCaptured, "notes_read", { path: "checkpoint/进度.md", scope: "human", offset_chars: -4 }, restoredCtx);
+    const read = resultRead(rawRead);
+    assert.equal(read.details.address, "@human/checkpoint/进度.md");
+    assert.equal(read.content, "Café", "a negative offset reads the body tail in one call");
+    const searched = resultJson(await call(restoredCaptured, "notes_search", { query: "Café", scope: "human" }, restoredCtx));
+    assert.equal(searched.files[0]?.matches[0]?.line, 2);
+    const listedFiles = resultJson(await call(restoredCaptured, "notes_list", { pattern: "checkpoint/**", scope: "human" }, restoredCtx));
+    assert.equal(listedFiles.files.length, 1, "glob ** crosses into the checkpoint directory");
+    assert.equal(listedFiles.files[0]?.path, "checkpoint/进度.md");
+    // A single-segment * never crosses `/`, so a nested-only store matches nothing at the root.
+    const rootOnly = resultJson(await call(restoredCaptured, "notes_list", { pattern: "*", scope: "human" }, restoredCtx));
+    assert.equal(rootOnly.files.length, 0, "glob * stays within one segment");
+    assert.equal(searched.files[0]?.created_at, listedFiles.files[0]?.created_at, "note tools agree on the timestamp format");
+    assert.equal(searched.files[0]?.updated_at, listedFiles.files[0]?.updated_at);
+    await assert.rejects(() => call(captured, "notes_write", { path: "../escape", content: "x" }, ctx), /unsupported component/);
+});
+test("stale lifecycle: writes and metadata-only edits close and revive a note", async () => {
+    const sm = manager();
+    const captured = makeExtension(sm);
+    const ctx = context(sm);
+    await call(captured, "notes_write", { path: "journal.md", content: "log line" }, ctx);
+    // metadata-only: content unchanged, flag set, applied 0
+    const markOnly = resultJson(await call(captured, "notes_edit", { path: "journal.md", stale: true }, ctx));
+    assert.equal(markOnly.applied, 0);
+    assert.equal(listNotes(ctx, { scope: "session" })[0]?.meta.stale, true);
+    assert.equal(resultRead(await call(captured, "notes_read", { path: "journal.md" }, ctx)).content.endsWith("log line"), true, "mark-only leaves content unchanged");
+    // explicit revive
+    const revived = resultJson(await call(captured, "notes_edit", { path: "journal.md", stale: false }, ctx));
+    assert.equal(listNotes(ctx, { scope: "session" })[0]?.meta.stale, false, "stale:false revives");
+    // write+stale closure then plain write revival
+    await call(captured, "notes_write", { path: "journal.md", content: "final", stale: true }, ctx);
+    assert.equal(listNotes(ctx, { scope: "session" })[0]?.meta.stale, true);
+    await call(captured, "notes_write", { path: "journal.md", content: "reopened" }, ctx);
+    assert.equal(listNotes(ctx, { scope: "session" })[0]?.meta.stale, false, "writing without stale revives");
+    // metadata-only on a missing path is the typed not-found arm
+    const missing = resultJson(await call(captured, "notes_edit", { path: "missing.md", stale: true }, ctx));
+    assert.equal(missing.error, "note not found");
+});
+test("the filesystem notes loader treats an absent home as empty but surfaces a real directory read failure", () => {
+    const sm = manager();
+    const ctx = context(sm);
+    assert.deepEqual(listNotes(ctx, { scope: "human" }), [], "a home that has not been created is empty");
+    const blockedHome = scopeDir("human", ctx);
+    writeFileSync(blockedHome, "not a directory");
+    assert.throws(() => listNotes(ctx, { scope: "human" }), (error) => error.code === "ENOTDIR", "a non-ENOENT directory failure is not swallowed as an empty home");
+});
+test("boot note acquisition is one closed snapshot and isolates one or all failed homes", () => {
+    const sm = manager();
+    const ctx = context(sm);
+    const updated = Date.now();
+    const note = (scope, path, address, body) => ({
+        address,
+        scope,
+        path,
+        body,
+        sizeBytes: Buffer.byteLength(body, "utf8"),
+        meta: {
+            scope,
+            origin: "self",
+            status: "active",
+            stale: false,
+            created_at: updated,
+            updated_at: updated,
+            last_accessed: updated,
+            access_count: 0,
+        },
+    });
+    const rows = new Map([
+        ["session", [note("session", "session.md", "session.md", "SESSION_POCKET_BODY")]],
+        ["project", [note("project", "MAP.md", "@project/MAP.md", "PROJECT_MAP_BODY")]],
+        ["human", [note("human", "human.md", "@human/human.md", "HUMAN_POCKET_BODY")]],
+        ["agent", [note("agent", "MAP.md", "@agents/root/MAP.md", "AGENT_MAP_BODY")]],
+        ["model", [note("model", "model.md", "@models/default/model.md", "MODEL_POCKET_BODY")]],
+    ]);
+    const calls = new Map();
+    const snapshot = loadNotesSnapshot(ctx, (_ctx, scope) => {
+        calls.set(scope, (calls.get(scope) ?? 0) + 1);
+        return rows.get(scope) ?? [];
+    });
+    assert.deepEqual([...calls.entries()], [["session", 1], ["project", 1], ["human", 1], ["agent", 1], ["model", 1]], "each selected home is loaded exactly once");
+    const renderData = {
+        agentName: "root",
+        modelName: "default",
+        firstWindowId: "pcw:test:root",
+        currentWindowId: "pcw:test:next",
+        previousWindowId: "pcw:test:root",
+        resetLine: true,
+        notes: snapshot,
+    };
+    const rendered = renderBootBlock(renderData);
+    assert.equal(renderBootBlock(renderData), rendered, "rendering the same boot data twice is deterministic");
+    assert.ok(rendered.includes("PROJECT_MAP_BODY") && rendered.includes("AGENT_MAP_BODY"), "MAP residency comes from the snapshot");
+    assert.ok(rendered.includes("session.md") && rendered.includes("@human/human.md"), "pocket rows come from the same snapshot");
+    assert.equal(rendered.includes("SESSION_POCKET_BODY"), false, "pocket bodies stay excluded");
+    const readFailure = (code) => Object.assign(new Error("scripted read failure"), { code });
+    const oneFailed = loadNotesSnapshot(ctx, (_ctx, scope) => {
+        if (scope === "human")
+            throw readFailure("EIO");
+        return rows.get(scope) ?? [];
+    });
+    assert.deepEqual(oneFailed.unavailable.map((home) => home.label), ["@human"]);
+    const oneFailedText = renderBootBlock({
+        agentName: "root",
+        modelName: "default",
+        firstWindowId: "pcw:test:root",
+        currentWindowId: "pcw:test:next",
+        resetLine: true,
+        notes: oneFailed,
+    });
+    assert.ok(oneFailedText.includes("PROJECT_MAP_BODY") && oneFailedText.includes("notes_list can retry after recovery"), "healthy homes and the recovery notice survive one failure");
+    assert.equal(oneFailedText.includes("HUMAN_POCKET_BODY"), false, "the failed home's index is omitted");
+    const allFailed = loadNotesSnapshot(ctx, (_ctx, scope) => {
+        throw readFailure(scope === "session" ? "EACCES" : "EIO");
+    });
+    assert.equal(allFailed.unavailable.length, 5);
+    const allFailedText = renderBootBlock({
+        agentName: "root",
+        modelName: "default",
+        firstWindowId: "pcw:test:root",
+        currentWindowId: "pcw:test:next",
+        previousWindowId: "pcw:test:root",
+        resetLine: true,
+        notes: allFailed,
+    });
+    assert.ok(allFailedText.includes("pcw:test:root") && allFailedText.includes("pcw:test:next"), "identity survives an all-home failure");
+    assert.ok(allFailedText.includes("Your memory resets whenever the context window fills"), "protocol survives an all-home failure");
+    assert.equal(allFailedText.includes("scripted read failure"), false, "the model-facing notice does not expose OS/error details");
+    assert.throws(() => loadNotesSnapshot(ctx, () => { throw new TypeError("programmer failure"); }), (error) => error instanceof TypeError, "unrelated TypeError construction failures remain visible");
+    assert.throws(() => loadNotesSnapshot(ctx, () => { throw Object.assign(new Error("invalid argument"), { code: "ERR_INVALID_ARG_TYPE" }); }), (error) => error.code === "ERR_INVALID_ARG_TYPE", "Node ERR_* failures are not treated as filesystem errno failures");
+});
+test("the boot block gives awake agents the notes-home file layout", () => {
+    const session = manager();
+    const rendered = explicitBoot(context(session), "pcw:test:root", undefined, false);
+    assert.equal(rendered.includes(process.env.PI_NOTES_HOME ?? ""), false, "the absolute notes home is never exposed");
+    assert.match(rendered, /bare <vpath>.*@project\/<vpath>.*@human\/<vpath>/);
+});
+test("an over-budget note is delivered as a prefix and resumed by next_offset_chars", async () => {
+    const session = manager();
+    const captured = makeExtension(session);
+    const ctx = context(session);
+    const huge = `H${"x".repeat(TOOL_OUTPUT_MAX_BYTES * 2)}`;
+    const text = `${huge}\ntail line`;
+    await call(captured, "notes_write", { path: "huge.md", content: text }, ctx);
+    const rawFirst = await call(captured, "notes_read", { path: "huge.md" }, ctx);
+    assertWithinBudget(rawFirst, "single oversized note");
+    const first = resultRead(rawFirst);
+    assert.ok(first.content.length > 0, "the page is not empty");
+    assert.equal(first.content.includes("…"), false, "the payload is a plain prefix with no marker");
+    assert.ok(first.content.startsWith("---\n"), "the frontmatter is delivered first");
+    assert.equal(first.header, `--- READ WINDOW ---\naddress: huge.md\nchars: [0,${first.next_offset_chars}) of ${first.total_chars}\nnext_offset_chars: ${first.next_offset_chars}\n`, "the raw block names the address, half-open range, and resume cursor");
+    assert.deepEqual(Object.keys(first.details).sort(), ["address", "next_offset_chars", "offset_chars", "total_chars"], "notes_read details carries exactly the raw window address and cursor metadata");
+    assert.equal("content" in first.details, false, "details never duplicates the payload");
+    assert.equal(first.offset_chars, 0, "the default window starts at the resolved offset 0");
+    // Following the cursor reconstructs frontmatter + body by plain concatenation.
+    const parts = [first.content];
+    let offset = first.next_offset_chars;
+    while (offset !== null) {
+        const rawChunk = await call(captured, "notes_read", { path: "huge.md", offset_chars: offset }, ctx);
+        assertWithinBudget(rawChunk, `huge note chunk at ${offset}`);
+        const chunk = resultRead(rawChunk);
+        assert.equal(chunk.offset_chars, offset, "the response echoes the resolved absolute offset");
+        parts.push(chunk.content);
+        offset = chunk.next_offset_chars;
+    }
+    assert.ok(parts.join("").endsWith(text), "the cursors reconstruct the body exactly");
+    // A success carries structured details; an error stays a JSON envelope with no details.
+    const missingResult = await call(captured, "notes_read", { path: "no-such.md" }, ctx);
+    const missing = resultJson(missingResult);
+    assert.deepEqual(Object.keys(missing).sort(), ["address", "error"], "the read error carries exactly error and address");
+    assert.equal(missing.error, "note not found");
+    assert.equal(missingResult.details, undefined, "a JSON error carries no details metadata");
+});
+test("an over-budget note search match is a named prefix with an honest line address", async () => {
+    const session = manager();
+    const captured = makeExtension(session);
+    const ctx = context(session);
+    // The query sits behind a prefix, so its address is a real body-absolute offset, not line 1.
+    const hugeLine = `${'p'.repeat(500)}needle ${"y".repeat(TOOL_OUTPUT_MAX_BYTES * 2)}`;
+    await call(captured, "notes_write", { path: "a.md", content: "needle small" }, ctx);
+    await call(captured, "notes_write", { path: "search.md", content: hugeLine }, ctx);
+    const pages = [];
+    let cursor = 0;
+    let next = 0;
+    while (next !== null) {
+        const found = resultJson(await call(captured, "notes_search", { query: "needle", cursor }, ctx));
+        assert.ok(Buffer.byteLength(JSON.stringify(found), "utf8") <= TOOL_OUTPUT_MAX_BYTES, "match result stays within budget");
+        pages.push(...found.files);
+        next = found.next_cursor;
+        if (next !== null)
+            cursor = next;
+    }
+    assert.deepEqual(pages.map((file) => file.path), ["a.md", "search.md"], "pagination reaches the oversized file instead of looping");
+    const oversized = pages[1];
+    assert.equal(oversized.matches_total, 1, "the file's full match count is named even though the line was cut");
+    assert.equal(oversized.matches.length, 1);
+    const match = oversized.matches[0];
+    assert.equal(match.truncated, true, "the oversized match line is flagged as truncated");
+    assert.ok(hugeLine.startsWith(match.text), "the match text is a plain prefix of the line");
+    assert.equal(match.text.includes("…"), false, "no marker is appended to the match text");
+    assert.equal(match.line, 1, "the informational line number survives");
+    const atMatch = resultRead(await call(captured, "notes_read", { path: "search.md", offset_chars: match.offset_chars }, ctx));
+    assert.ok(atMatch.content.startsWith("needle"), "the search offset starts a read at the matched substring");
+    // The body is reconstructible by following notes_read's cursor from the start of the file.
+    const parts = [];
+    let offset = 0;
+    while (offset !== null) {
+        const rawChunk = await call(captured, "notes_read", { path: "search.md", offset_chars: offset }, ctx);
+        assertWithinBudget(rawChunk, `search.md chunk at ${offset}`);
+        const chunk = resultRead(rawChunk);
+        assert.equal(chunk.offset_chars, offset, "the read echoes the resolved address");
+        parts.push(chunk.content);
+        offset = chunk.next_offset_chars;
+    }
+    assert.ok(parts.join("").endsWith(hugeLine), "resuming across pages reconstructs the matched body line");
+});
+test("notes_search scopes by glob pattern; a non-matching pattern is an empty page, not an error", async () => {
+    const session = manager();
+    const captured = makeExtension(session);
+    const ctx = context(session);
+    await call(captured, "notes_write", { path: "deep/nested/a.md", content: "needle here" }, ctx);
+    await call(captured, "notes_write", { path: "top.md", content: "needle there" }, ctx);
+    const scoped = resultJson(await call(captured, "notes_search", { query: "needle", pattern: "deep/**" }, ctx));
+    assert.deepEqual(scoped.files.map((file) => file.path), ["deep/nested/a.md"], "a glob scopes the search to the subtree");
+    const none = resultJson(await call(captured, "notes_search", { query: "needle", pattern: "absent/**" }, ctx));
+    assert.equal(none.error, undefined, "a non-matching pattern is not an error");
+    assert.deepEqual(none.files, [], "a non-matching pattern is an empty page");
+});