@astrosheep/pi-context 0.18.0 → 0.20.0

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

@@ -0,0 +1,212 @@
+import assert from "node:assert/strict";
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { createAssistantMessageEventStream } from "@earendil-works/pi-ai";
+import { createAgentSession, DefaultResourceLoader, ModelRuntime, SessionManager, SettingsManager } from "@earendil-works/pi-coding-agent";
+import piContext from "../src/index.js";
+import { WARNING_TYPE, GUIDANCE_TYPE } from "../src/protocol.js";
+for (const mode of ["golden", "write-error", "ignored-warning", "explicit", "uncompactable", "followup", "steering", "repeat", "abort"]) {
+    test(`real Pi loop: ${mode} reset preserves history and handles completion`, { timeout: 15000 }, async () => {
+        const dir = mkdtempSync(join(tmpdir(), "pi-context-loop-"));
+        const previousDir = process.env.PI_CODING_AGENT_DIR;
+        const previousNotesRoot = process.env.PI_NOTES_HOME;
+        process.env.PI_CODING_AGENT_DIR = dir;
+        const notesRoot = mkdtempSync(join(tmpdir(), "pi-context-loop-notes-"));
+        process.env.PI_NOTES_HOME = notesRoot;
+        let session;
+        try {
+            const runtime = await ModelRuntime.create({ authPath: join(dir, "auth.json"), modelsPath: null, modelsStorePath: join(dir, "models"), refreshOnCreate: false });
+            await runtime.setRuntimeApiKey("openai", "scripted-test-key");
+            const base = runtime.getModels("openai")[0];
+            assert.ok(base);
+            const model = { ...base, contextWindow: 100000, maxTokens: 4096 };
+            const usageMode = mode === "golden" || mode === "write-error" || mode === "ignored-warning";
+            const expectedResets = mode === "abort" || mode === "uncompactable" ? 0 : 1;
+            const settings = { compaction: { enabled: usageMode, reserveTokens: 32768, keepRecentTokens: mode === "uncompactable" ? 1 : 200 }, retry: { enabled: false } };
+            writeFileSync(join(dir, "settings.json"), JSON.stringify(settings));
+            const settingsManager = SettingsManager.create(dir, dir);
+            let resets = 0;
+            let settled = 0;
+            let targetResets = expectedResets;
+            let activeSentinel = "OLD_CONTEXT_SENTINEL";
+            let finish;
+            let failFinish;
+            const finished = new Promise((resolve, reject) => { finish = resolve; failFinish = reject; });
+            const finishTimeout = setTimeout(() => failFinish(new Error(`timed out waiting for ${mode} agent settlement`)), 5000);
+            const loader = new DefaultResourceLoader({ cwd: dir, agentDir: dir, settingsManager,
+                noExtensions: true, noSkills: true, noThemes: true, noPromptTemplates: true,
+                systemPromptOverride: () => "Use the tools as requested.", agentsFilesOverride: () => ({ agentsFiles: [] }),
+                extensionFactories: [piContext, (pi) => {
+                        pi.on("session_compact", () => { resets++; });
+                        pi.on("agent_settled", () => {
+                            settled++;
+                            if (mode === "abort") {
+                                if (settled === 1)
+                                    finish();
+                                return;
+                            }
+                            if (resets >= targetResets && requests.length > 0 && !requests.at(-1).includes(activeSentinel))
+                                finish();
+                        });
+                        pi.on("tool_result", () => {
+                            if (mode === "abort")
+                                void session.abort();
+                        });
+                        pi.on("tool_call", async () => {
+                            if (mode === "followup")
+                                await session.followUp("QUEUED_INPUT_SENTINEL");
+                            if (mode === "steering")
+                                await session.steer("QUEUED_INPUT_SENTINEL");
+                        });
+                    }],
+            });
+            await loader.reload();
+            const sm = SessionManager.inMemory(dir);
+            sm.appendMessage({ role: "user", content: "Earlier work to retain in durable history.", timestamp: Date.now() });
+            sm.appendMessage({ role: "assistant", api: model.api, provider: model.provider, model: model.id,
+                content: [{ type: "text", text: "Earlier result. ".repeat(100) }], stopReason: "stop", timestamp: Date.now(),
+                usage: { input: 100, output: 100, cacheRead: 0, cacheWrite: 0, totalTokens: 200, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } } });
+            ({ session } = await createAgentSession({ cwd: dir, agentDir: dir, modelRuntime: runtime, model, settingsManager, sessionManager: sm, resourceLoader: loader, tools: ["new_context", "notes_write", "get_context_remaining"] }));
+            const requests = [];
+            let checkpointed = false;
+            let freshTurns = 0;
+            session.agent.streamFunction = (_model, context) => {
+                requests.push(JSON.stringify(context.messages));
+                const n = requests.length;
+                const request = requests[n - 1];
+                const fresh = !request.includes("OLD_CONTEXT_SENTINEL");
+                if (fresh)
+                    freshTurns++;
+                const sawWarning = request.includes("Your memory is about to be erased");
+                const sawGuidance = request.includes("Your brain is almost out of room");
+                const explicitReset = (n === 1 && !usageMode && mode !== "uncompactable") || (mode === "repeat" && (n === 1 || n === 3));
+                const checkpoint = usageMode && sawWarning && !checkpointed && mode !== "ignored-warning";
+                if (checkpoint)
+                    checkpointed = true;
+                // The warning is chosen from the previous turn's usage, so a scripted run has to
+                // keep taking turns until it sees the warning (first window) or the next
+                // window's reminder. "ignored-warning" keeps working instead of checkpointing.
+                const probe = usageMode && !checkpoint && ((!fresh && !sawWarning) || (mode === "ignored-warning" && sawWarning) || (fresh && freshTurns === 2 && !sawGuidance));
+                const tokens = usageMode ? (fresh ? (freshTurns === 1 ? 100 : 50000) : sawWarning ? 70000 : n === 1 ? 50000 : 60000) : 100;
+                const tool = explicitReset || (mode === "uncompactable" && n === 1);
+                const call = probe ? "get_context_remaining" : checkpoint ? "notes_write" : tool ? "new_context" : undefined;
+                const message = { role: "assistant", api: model.api, provider: model.provider, model: model.id,
+                    content: probe ? [{ type: "toolCall", id: "probe-call", name: "get_context_remaining", arguments: {} }]
+                        : checkpoint ? [{ type: "toolCall", id: "checkpoint-call", name: "notes_write", arguments: { path: mode === "write-error" ? "../invalid.md" : "checkpoint.md", content: "CHECKPOINT_SENTINEL" } }]
+                            : tool ? [{ type: "toolCall", id: "reset-call", name: "new_context", arguments: {} }]
+                                : [{ type: "text", text: fresh ? "Resumed." : "Working." }],
+                    stopReason: call ? "toolUse" : "stop", timestamp: Date.now(),
+                    usage: { input: tokens, output: 1, cacheRead: 0, cacheWrite: 0, totalTokens: tokens + 1, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+                };
+                const stream = createAssistantMessageEventStream();
+                stream.push({ type: "done", reason: message.stopReason, message });
+                stream.end();
+                return stream;
+            };
+            await session.bindExtensions({});
+            let failure;
+            session.subscribe((event) => {
+                if (mode === "uncompactable" && event.type === "compaction_end" && event.errorMessage) {
+                    failure = event.errorMessage;
+                    finish();
+                }
+            });
+            await session.prompt("OLD_CONTEXT_SENTINEL: save progress and continue the task.");
+            await finished;
+            clearTimeout(finishTimeout);
+            await session.waitForIdle();
+            if (mode === "abort") {
+                assert.equal(resets, 0, "user cancellation clears pending rollover");
+                assert.equal(requests.length, 1, "no continuation resurrects the cancelled run");
+                await session.prompt("Resume explicitly after cancellation.");
+                assert.equal(requests.length, 2);
+                assert.ok(requests[1].includes("Resume explicitly after cancellation."));
+                assert.ok(requests[1].includes("OLD_CONTEXT_SENTINEL"), "no reset happened: history is intact");
+                return;
+            }
+            if (mode === "uncompactable") {
+                assert.match(failure ?? "", /Nothing to compact/);
+                assert.equal(resets, 0);
+                assert.equal(requests.length, 1, "failed reset does not loop or resume automatically");
+                await session.prompt("Continue after the failed reset.");
+                assert.equal(requests.length, 2);
+                assert.ok(requests[1].includes("OLD_CONTEXT_SENTINEL"));
+                return;
+            }
+            assert.equal(resets, expectedResets);
+            if (mode === "golden" || mode === "write-error" || mode === "ignored-warning") {
+                const branch = sm.getBranch();
+                const guidanceIndices = branch.flatMap((entry, i) => entry.type === "custom_message" && entry.customType === GUIDANCE_TYPE ? [i] : []);
+                const warningIndices = branch.flatMap((entry, i) => entry.type === "custom_message" && entry.customType === WARNING_TYPE ? [i] : []);
+                const noteFile = join(notesRoot, "pi", "session", sm.getSessionId(), "checkpoint.md");
+                const resetIndex = branch.findIndex((entry) => entry.type === "compaction");
+                assert.equal(guidanceIndices.length, 1, "one early reminder");
+                assert.equal(warningIndices.length, 1, "one final warning steer");
+                assert.ok(warningIndices[0] > guidanceIndices[0], "the reminder precedes the warning");
+                if (mode === "ignored-warning") {
+                    assert.equal(existsSync(noteFile), false, "an ignored warning leaves no checkpoint");
+                }
+                else if (mode === "write-error") {
+                    assert.equal(existsSync(noteFile), false, "failed write creates no checkpoint");
+                    assert.ok(branch.some((entry) => entry.type === "message" && entry.message.role === "toolResult" && entry.message.toolName === "notes_write" && entry.message.isError));
+                    assert.ok(!requests.at(-1).includes("CHECKPOINT_SENTINEL"), "fresh context must not invent a saved note");
+                }
+                else {
+                    assert.ok(existsSync(noteFile), "the checkpoint is a real file on disk");
+                    assert.ok(resetIndex > warningIndices[0], "the warning precedes the wipe");
+                    assert.ok(requests.at(-1).includes("CHECKPOINT_SENTINEL"), "fresh boot carries the saved checkpoint");
+                }
+                assert.ok(!requests.at(-1).includes("Your brain is almost out of room"), "new window excludes old guidance");
+            }
+            if (mode === "followup" || mode === "steering") {
+                assert.ok(requests[1].includes("QUEUED_INPUT_SENTINEL"), "queued user work is delivered before rollover");
+                assert.ok(requests[1].includes("OLD_CONTEXT_SENTINEL"), "queue drains in the existing window");
+                assert.ok(!requests[2].includes("QUEUED_INPUT_SENTINEL"), "queue is not replayed after rollover");
+                const queuedEntries = sm.getBranch().filter((entry) => entry.type === "message" && JSON.stringify(entry.message).includes("QUEUED_INPUT_SENTINEL"));
+                assert.equal(queuedEntries.length, 1, "one durable user input");
+            }
+            if (mode === "repeat") {
+                const nextFinished = new Promise((resolve) => { finish = resolve; });
+                targetResets = 2;
+                activeSentinel = "SECOND_WINDOW_SENTINEL";
+                await session.prompt("SECOND_WINDOW_SENTINEL: " + "Additional work. ".repeat(100));
+                await nextFinished;
+                await session.waitForIdle();
+                assert.equal(resets, 2);
+                assert.ok(!requests.at(-1).includes("SECOND_WINDOW_SENTINEL"));
+                const boundaries = sm.getBranch().filter((entry) => entry.type === "compaction");
+                assert.equal(new Set(boundaries.map((entry) => JSON.stringify(entry.details))).size, 2);
+            }
+            assert.ok(requests[0].includes("OLD_CONTEXT_SENTINEL"));
+            assert.ok(!requests.at(-1).includes("OLD_CONTEXT_SENTINEL"));
+            assert.ok(requests.at(-1).includes("context_window"));
+            assert.ok(JSON.stringify(session.sessionManager.getBranch()).includes("OLD_CONTEXT_SENTINEL"));
+            if (mode === "golden") {
+                await session.prompt("Keep working in the new window until its reminder threshold.");
+                assert.equal(resets, 1);
+                const branch = sm.getBranch();
+                const boundary = branch.findIndex((entry) => entry.type === "compaction");
+                const reminders = branch.flatMap((entry, i) => entry.type === "custom_message" && entry.customType === GUIDANCE_TYPE ? [i] : []);
+                assert.equal(reminders.length, 2, "the next window gets its own reminder");
+                assert.ok(reminders[1] > boundary, "old messages cannot suppress a new window's reminder");
+                const warnings = branch.flatMap((entry, i) => entry.type === "custom_message" && entry.customType === WARNING_TYPE ? [i] : []);
+                assert.equal(warnings.length, 1, "the next window has no warning yet");
+            }
+        }
+        finally {
+            session?.dispose();
+            if (previousDir === undefined)
+                delete process.env.PI_CODING_AGENT_DIR;
+            else
+                process.env.PI_CODING_AGENT_DIR = previousDir;
+            if (previousNotesRoot === undefined)
+                delete process.env.PI_NOTES_HOME;
+            else
+                process.env.PI_NOTES_HOME = previousNotesRoot;
+            rmSync(dir, { recursive: true, force: true });
+            rmSync(notesRoot, { recursive: true, force: true });
+        }
+    });
+}

package/dist/test/coherence.test.js

@@ -0,0 +1,371 @@
+/**
+ * OWNER: pi-context (adopted).
+ * STATUS: tracked acceptance spec for the history and notes read/search tools. No skip.
+ * CLAIM: following the cursors these tools return must reconstruct the original text exactly,
+ *   or the result must name the skipped range. Both read tools are one character window over two
+ *   stores (notes_read and history_read share the cursor walk below). In v2 this failed
+ *   at 13 sites; the rows that demanded an over-budget line in a single call are rebuilt as
+ *   cursor-walking rows below (the CLAIM explicitly licenses that: reconstruct exactly by
+ *   following cursors, or name the skipped range).
+ * HERMETIC: this file reads only its own in-memory session. Corpus replays of real sessions
+ *   are NOT hermetic, must be single-pass, and belong in a dev script, not npm test.
+ */
+import assert from "node:assert/strict";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+import piContext, { historyFromSession } from "../src/index.js";
+import { TOOL_OUTPUT_MAX_BYTES } from "../src/tool-output.js";
+import { stripLeadingFrontmatter } from "../src/memory/frontmatter.js";
+process.env.PI_CODING_AGENT_DIR = mkdtempSync(join(tmpdir(), "pc-coherence-agent-"));
+process.env.PI_NOTES_HOME = mkdtempSync(join(tmpdir(), "pc-coherence-notes-"));
+function makeExtension(sessionManager) {
+    const captured = { tools: new Map() };
+    const api = {
+        registerFlag() { },
+        registerTool(tool) { captured.tools.set(tool.name, tool); },
+        registerCommand() { },
+        on() { },
+        appendEntry(customType, data) { sessionManager.appendCustomEntry(customType, data); },
+        sendMessage(message) {
+            sessionManager.appendCustomMessageEntry(message.customType, message.content, message.display, message.details);
+        },
+    };
+    piContext(api);
+    return captured;
+}
+function context(sessionManager) {
+    const fake = {
+        sessionManager,
+        getContextUsage: () => undefined,
+        compact: () => { },
+        isIdle: () => true,
+        hasPendingMessages: () => false,
+        cwd: "/private/tmp/pi-context-test",
+        isProjectTrusted: () => true,
+        ui: { notify: () => { } },
+    };
+    return fake;
+}
+async function call(captured, name, params, ctx) {
+    const tool = captured.tools.get(name);
+    assert.ok(tool, `registered ${name}`);
+    return tool.execute("call-1", params, new AbortController().signal, () => { }, ctx);
+}
+function resultJson(result) {
+    const text = result.content[0];
+    assert.ok(text && text.type === "text");
+    return JSON.parse(text.text);
+}
+function assertWithinBudget(result, label) {
+    const bytes = Buffer.byteLength(result.content[0] && result.content[0].type === "text" ? result.content[0].text : "", "utf8");
+    if (bytes > TOOL_OUTPUT_MAX_BYTES)
+        failures.push(`${label}: response is ${bytes} bytes, over the ${TOOL_OUTPUT_MAX_BYTES}-byte budget`);
+}
+function appendText(sessionManager, text) {
+    return sessionManager.appendMessage({ role: "user", content: [{ type: "text", text }], timestamp: Date.now() });
+}
+/**
+ * Decode a raw read (notes_read / history_read): a one-line bracketed header, then
+ * the payload verbatim (which may itself contain newlines), so split on the first newline only.
+ */
+function resultRead(result) {
+    const text = result.content[0];
+    assert.ok(text && text.type === "text", "read result carries text");
+    const newline = text.text.indexOf("\n");
+    assert.ok(newline !== -1, "raw read carries a header line and a payload");
+    const header = text.text.slice(0, newline);
+    const content = text.text.slice(newline + 1);
+    assert.match(header, /^\[/, "the header is bracketed");
+    assert.match(header, /\]$/, "the header closes its bracket");
+    const match = header.match(/ · chars (\d+)-(\d+) of (\d+) · (end|continue at offset_chars=(\d+))/);
+    assert.ok(match, `read header names the char range and resume cursor: ${header}`);
+    const offset_chars = Number(match[1]);
+    const total_chars = Number(match[3]);
+    const next_offset_chars = match[4] === "end" ? null : Number(match[5]);
+    assert.equal([...content].length, Number(match[2]) - offset_chars, "the header range matches the delivered payload");
+    return { header, content, offset_chars, total_chars, next_offset_chars };
+}
+const PROFILES = [
+    { name: "cjk", unit: "历" },
+    { name: "emoji", unit: "🕷" },
+    { name: "ascii", unit: "x" },
+];
+const failures = [];
+const report = [];
+const codePoints = (text) => [...text].length;
+const codePointSlice = (text, start, end) => [...text].slice(start, end).join("");
+/**
+ * Follow either read tool's cursor exactly as the protocol tells the model to, asserting the
+ * cursor law on every page. Both tools are the same character window over two stores, so one
+ * walker serves both; `address` carries the tool's own identity parameters, and `options.start`
+ * lets a walk begin at a resolved address (a search hit's offset, or a negative tail read).
+ */
+async function walkWindow(captured, ctx, tool, address, label, options = {}) {
+    const parts = [];
+    let offset = options.start ?? 0;
+    let next = 0;
+    let calls = 0;
+    let total = 0;
+    while (next !== null && calls < 400) {
+        const params = { ...address, offset_chars: offset };
+        if (options.limitChars !== undefined)
+            params.limit_chars = options.limitChars;
+        const result = await call(captured, tool, params, ctx);
+        assertWithinBudget(result, `${label} offset=${offset}`);
+        const page = resultRead(result);
+        total = page.total_chars;
+        const delivered = codePoints(page.content);
+        if (page.offset_chars !== offset)
+            failures.push(`cursor law: ${label} echoed offset_chars=${page.offset_chars} for request offset ${offset}`);
+        if (page.next_offset_chars !== null && page.next_offset_chars !== offset + delivered) {
+            failures.push(`cursor law: ${label} next_offset_chars=${page.next_offset_chars} but offset ${offset} + delivered ${delivered}`);
+        }
+        if (page.next_offset_chars === null && offset + delivered !== page.total_chars) {
+            failures.push(`false exhaustion: ${label} returned next_offset_chars=null with ${page.total_chars - (offset + delivered)} characters undelivered`);
+        }
+        if (page.content.includes("…") || page.content.includes("[truncated"))
+            failures.push(`honest payload: ${label} appended a marker at offset ${offset}`);
+        parts.push(page.content);
+        next = page.next_offset_chars;
+        if (next !== null)
+            offset = next;
+        calls++;
+    }
+    if (offset !== total && calls >= 400)
+        failures.push(`${label} never terminated`);
+    return parts.join("");
+}
+const walkHistory = (captured, ctx, windowId, itemId, limitChars) => walkWindow(captured, ctx, "history_read", { window_id: windowId, item_id: itemId }, `history_read ${itemId}`, { limitChars });
+const walkNote = (captured, ctx, path, start = 0) => walkWindow(captured, ctx, "notes_read", { path }, `notes_read ${path}`, { start });
+test("coherence: following the returned cursors reconstructs the original text exactly", async () => {
+    const session = SessionManager.inMemory("/private/tmp/pi-context-test");
+    const captured = makeExtension(session);
+    const ctx = context(session);
+    const windowId = historyFromSession(ctx)[0].windowId;
+    // --- history_read: every profile x length reconstructs; cursor law holds per page ---
+    for (const profile of PROFILES) {
+        for (const length of [12_000, 12_001, 20_000, 30_000]) {
+            const original = profile.unit.repeat(length);
+            const itemId = appendText(session, original);
+            const reconstructed = await walkHistory(captured, ctx, windowId, itemId);
+            const missing = codePoints(original) - codePoints(reconstructed);
+            const line = `history_read default: ${profile.name} ${length} chars (${Buffer.byteLength(original, "utf8")} bytes) -> delivered ${codePoints(reconstructed)} chars, missing ${missing}, marker=${reconstructed.includes("[truncated")}`;
+            report.push(line);
+            if (reconstructed !== original)
+                failures.push(line);
+            session.appendMessage({ role: "assistant", content: [{ type: "text", text: `ack ${length}` }], timestamp: Date.now() });
+        }
+    }
+    // --- notes_read: a 40,000-code-point single line plus a tail, three profiles ---
+    for (const profile of PROFILES) {
+        const hugeLine = profile.unit.repeat(40_000);
+        const text = `${hugeLine}\ntail line`;
+        const path = `huge-${profile.name}.md`;
+        await call(captured, "notes_write", { path, content: text }, ctx);
+        const reconstructed = stripLeadingFrontmatter(await walkNote(captured, ctx, path));
+        const missing = codePoints(text) - codePoints(reconstructed);
+        const line = `notes_read: ${profile.name} single line ${codePoints(hugeLine)} chars (${Buffer.byteLength(hugeLine, "utf8")} bytes) -> delivered ${codePoints(reconstructed)} chars, missing ${missing}, marker=${reconstructed.includes("[truncated")}`;
+        report.push(line);
+        if (reconstructed !== text)
+            failures.push(line);
+    }
+    // --- The terminator itself can lie. A single line with no trailing newline is exactly what
+    // notes_write { content } produces; the returned cursor must not be null while text remains.
+    for (const profile of PROFILES) {
+        const hugeLine = profile.unit.repeat(40_000);
+        const path = `solo-${profile.name}.md`;
+        await call(captured, "notes_write", { path, content: hugeLine }, ctx);
+        const first = resultRead(await call(captured, "notes_read", { path }, ctx));
+        const deliveredBody = first.content.startsWith("---\n") ? stripLeadingFrontmatter(first.content) : first.content;
+        const undelivered = codePoints(hugeLine) - codePoints(deliveredBody);
+        report.push(`notes_read no trailing newline: ${profile.name} ${codePoints(hugeLine)} chars -> first page delivered ${codePoints(deliveredBody)} body chars, undelivered ${undelivered}, offset_chars=${first.offset_chars}, next_offset_chars=${String(first.next_offset_chars)}, marker=${first.content.includes("[truncated")}`);
+        if (first.offset_chars !== 0)
+            failures.push(`window echo: ${profile.name} first page echoed offset_chars=${first.offset_chars}, expected 0`);
+        if (first.total_chars < codePoints(hugeLine))
+            failures.push(`window total: ${profile.name} total_chars=${first.total_chars}, expected at least the body length`);
+        if (!first.content.startsWith("---\n"))
+            failures.push(`frontmatter first: ${profile.name} first page does not open with frontmatter`);
+        if (first.next_offset_chars === null && undelivered > 0)
+            failures.push(`false exhaustion: ${profile.name} returns next_offset_chars=null while ${undelivered} characters were never delivered`);
+        if (!hugeLine.startsWith(deliveredBody))
+            failures.push(`prefix law: ${profile.name} first page body is not a prefix of the line`);
+        const reconstructed = stripLeadingFrontmatter(await walkNote(captured, ctx, path));
+        if (reconstructed !== hugeLine)
+            failures.push(`notes_read single line is not reconstructible: ${profile.name}, ${codePoints(hugeLine) - codePoints(reconstructed)} chars missing`);
+    }
+    // --- The empty note must terminate: no self-feeding cursor, and a frontmatter-only window from 0.
+    await call(captured, "notes_write", { path: "empty.md", content: "" }, ctx);
+    const empty = resultRead(await call(captured, "notes_read", { path: "empty.md" }, ctx));
+    report.push(`notes_read empty note: offset_chars=${empty.offset_chars} total_chars=${empty.total_chars} next_offset_chars=${String(empty.next_offset_chars)} content=${JSON.stringify(empty.content)}`);
+    if (empty.offset_chars !== 0 || !empty.content.startsWith("---\n") || !empty.content.endsWith("---\n\n"))
+        failures.push("the empty note is not a frontmatter-only window from 0");
+    if (empty.next_offset_chars !== null)
+        failures.push("pagination hole: the empty note is never exhausted");
+    // --- notes_search: an over-budget matched line is named, then read back with cursors ---
+    const hugeCjkLine = "历".repeat(40_000);
+    const searched = resultJson(await call(captured, "notes_search", { query: "历", pattern: "huge-cjk.md" }, ctx));
+    const matchedFile = searched.files[0];
+    const matched = matchedFile?.matches[0];
+    report.push(`notes_search: matches_total=${String(matchedFile?.matches_total)} returned=${String(matchedFile?.matches.length)} first match delivered ${codePoints(matched?.text ?? "")} of ${String(matched?.total_chars)} chars, truncated=${String(matched?.truncated)}`);
+    if (!matched)
+        failures.push("notes_search dropped the over-budget matched line entirely");
+    else {
+        if (matched.truncated !== true)
+            failures.push("notes_search does not flag the over-budget matched line as truncated");
+        if (matched.total_chars !== codePoints(hugeCjkLine))
+            failures.push(`notes_search match total_chars=${matched.total_chars}, expected ${codePoints(hugeCjkLine)}`);
+        if (!hugeCjkLine.startsWith(matched.text))
+            failures.push("notes_search delivered a non-prefix of the matched line");
+        if (codePoints(matched.text) >= matched.total_chars)
+            failures.push("notes_search claims the over-budget line fits in one response");
+        const walked = stripLeadingFrontmatter(await walkNote(captured, ctx, "huge-cjk.md"));
+        if (walked !== `${hugeCjkLine}\ntail line`)
+            failures.push(`notes_search match line is not reconstructible from the note read: missing ${codePoints(`${hugeCjkLine}\ntail line`) - codePoints(walked)} chars`);
+    }
+    // --- history_search: a hit's visible text may be cut, but the offset it carries
+    // must resolve to the query through history_read (addresses-only mode).
+    const searchItemContent = `${"padding ".repeat(400)}历史内容${" trailing".repeat(400)}`;
+    const searchItemId = appendText(session, searchItemContent);
+    const hit = resultJson(await call(captured, "history_search", { query: "历史内容", max_chars_per_item: 400, window_id: windowId }, ctx));
+    const first = hit.items.find((item) => item.item_id === searchItemId);
+    report.push(`history_search: hit present=${Boolean(first)}, fields=${JSON.stringify(Object.keys(first ?? {}))}, match_offset_chars=${String(first?.match_offset_chars)}, truncated=${String(first?.truncated)}`);
+    if (!first)
+        failures.push("history_search did not return the matching item");
+    else {
+        if (first.truncated !== true)
+            failures.push("history_search does not flag the capped item as truncated");
+        if (first.total_chars !== codePoints(searchItemContent))
+            failures.push(`history_search total_chars=${first.total_chars}, expected ${codePoints(searchItemContent)}`);
+        if (!searchItemContent.startsWith(first.truncated_content))
+            failures.push("history_search delivered a non-prefix of the item");
+        if (first.truncated_content.includes("…"))
+            failures.push("history_search appended a marker to the payload");
+        if (!Number.isInteger(first.match_offset_chars))
+            failures.push("history_search carries no match_offset_chars");
+        else {
+            const at = resultRead(await call(captured, "history_read", { window_id: windowId, item_id: searchItemId, offset_chars: first.match_offset_chars, limit_chars: 8 }, ctx));
+            if (!at.content.includes("历史内容"))
+                failures.push(`history_read at match_offset_chars=${first.match_offset_chars} does not show the query`);
+        }
+    }
+    // max_chars_per_item: 1 is a real address page for both history tools.
+    const addresses = resultJson(await call(captured, "history_search", { query: "历史内容", max_chars_per_item: 1, window_id: windowId }, ctx));
+    const address = addresses.items.find((item) => item.item_id === searchItemId);
+    report.push(`history_search max_chars_per_item=1: address=${JSON.stringify(address)}`);
+    if (!address)
+        failures.push("history_search max_chars_per_item=1 dropped the hit");
+    else {
+        if (codePoints(address.truncated_content) !== 1)
+            failures.push(`max_chars_per_item=1 delivered ${codePoints(address.truncated_content)} code points`);
+        if (address.truncated !== true || address.total_chars !== codePoints(searchItemContent))
+            failures.push("max_chars_per_item=1 does not name the full length");
+        if (!Number.isInteger(address.match_offset_chars))
+            failures.push("max_chars_per_item=1 carries no address");
+    }
+    const listed = resultJson(await call(captured, "history_list", { window_id: windowId, max_chars_per_item: 1, recent_first: false, limit: 500 }, ctx));
+    const listedAddress = listed.items.find((item) => item.item_id === searchItemId);
+    report.push(`history_list max_chars_per_item=1: ${JSON.stringify(listedAddress)}`);
+    if (!listedAddress)
+        failures.push("history_list max_chars_per_item=1 dropped the item");
+    else if (codePoints(listedAddress.truncated_content) !== 1 || listedAddress.truncated !== true || listedAddress.total_chars !== codePoints(searchItemContent)) {
+        failures.push("history_list max_chars_per_item=1 is not an honest address page");
+    }
+    // --- brain-04: capping a file's matches to fit the wire budget must be named, never silent.
+    const manyLines = Array.from({ length: 8_000 }, (_, index) => `needle ${index}`);
+    await call(captured, "notes_write", { path: "many.md", content: manyLines.join("\n") }, ctx);
+    const many = resultJson(await call(captured, "notes_search", { query: "needle", pattern: "many.md" }, ctx));
+    const manyEntry = many.files[0];
+    report.push(`brain-04: matches_total=${String(manyEntry?.matches_total)} returned=${String(manyEntry?.matches.length)}, next_cursor=${String(many.next_cursor)}`);
+    if (!manyEntry)
+        failures.push("brain-04: the many-match file is absent from the search result");
+    else {
+        if (manyEntry.matches_total !== manyLines.length)
+            failures.push(`brain-04: matches_total=${manyEntry.matches_total}, expected ${manyLines.length}`);
+        if (!(manyEntry.matches_total > manyEntry.matches.length))
+            failures.push("brain-04: budget-capped matches were silently dropped (matches_total === matches.length)");
+        if (manyEntry.matches_total - manyEntry.matches.length <= 0)
+            failures.push("brain-04: the response names no dropped matches");
+    }
+    // A file whose first match alone is over budget with more matches behind it: dropping trailing
+    // matches and cutting the kept line must still leave the whole response inside the wire budget.
+    const manyHugeLines = Array.from({ length: 4 }, (_, index) => `needle ${index} ${"w".repeat(45_000)}`);
+    await call(captured, "notes_write", { path: "huge-many.md", content: manyHugeLines.join("\n") }, ctx);
+    const hugeManyResult = await call(captured, "notes_search", { query: "needle", pattern: "huge-many.md" }, ctx);
+    assertWithinBudget(hugeManyResult, "notes_search huge-many");
+    const hugeEntry = resultJson(hugeManyResult).files[0];
+    report.push(`huge-many: matches_total=${String(hugeEntry?.matches_total)} returned=${String(hugeEntry?.matches.length)} truncated=${String(hugeEntry?.matches[0]?.truncated)}`);
+    if (!hugeEntry)
+        failures.push("huge-many: the many-huge-match file is absent from the search result");
+    else {
+        if (!(hugeEntry.matches_total > hugeEntry.matches.length))
+            failures.push("huge-many: dropped matches are not named");
+        if (hugeEntry.matches[0]?.truncated !== true)
+            failures.push("huge-many: the kept match is not flagged as a prefix");
+    }
+    // --- notes_search addresses: a match's offset_chars is the body-absolute code-point
+    // position of the earliest query occurrence in its line, so search → read composes exactly like
+    // history's match_offset_chars two-stage.
+    const addressLine1 = "pad ".repeat(50);
+    const addressLine3 = `${"历".repeat(20)}needle-address here`;
+    const addressLine4 = "zeta 历 needle-address";
+    await call(captured, "notes_write", { path: "address.md", content: `${addressLine1}\nsecond\n${addressLine3}\n${addressLine4}` }, ctx);
+    const expectedAddress = codePoints(addressLine1) + 1 + codePoints("second") + 1 + 20;
+    const addressHit = resultJson(await call(captured, "notes_search", { query: "needle-address", pattern: "address.md" }, ctx)).files[0]?.matches.find((match) => match.line === 3);
+    report.push(`notes_search address: line=${String(addressHit?.line)} offset_chars=${String(addressHit?.offset_chars)} expected=${expectedAddress}`);
+    const addressOffset = addressHit?.offset_chars;
+    if (typeof addressOffset !== "number")
+        failures.push("notes_search carries no offset_chars");
+    else if (addressOffset !== expectedAddress)
+        failures.push(`notes_search offset_chars=${addressOffset}, expected ${expectedAddress} (body-absolute, at the query)`);
+    // Multi-query OR: a line's address is the earliest occurrence of any query inside that line.
+    const line4Base = expectedAddress - 20 + codePoints(addressLine3) + 1;
+    const orLine4 = resultJson(await call(captured, "notes_search", { query: ["needle-address", "zeta"], pattern: "address.md" }, ctx)).files[0]?.matches.find((match) => match.line === 4);
+    report.push(`notes_search OR address: offset_chars=${String(orLine4?.offset_chars)} expected=${line4Base}`);
+    if (orLine4?.offset_chars !== line4Base)
+        failures.push(`notes_search OR offset_chars=${String(orLine4?.offset_chars)}, expected ${line4Base} (earliest of any query)`);
+    // --- Negative offsets on both stores: a tail read reaches the end in one call, the response
+    // echoes the resolved absolute offset, N >= total_chars reads from the start, and the cursor
+    // law still holds when a negative-start page is cut short.
+    for (const profile of PROFILES) {
+        const tailText = `head${profile.unit.repeat(20)}TAIL${profile.unit.repeat(20)}`;
+        const path = `tail-${profile.name}.md`;
+        await call(captured, "notes_write", { path, content: tailText }, ctx);
+        const full = resultRead(await call(captured, "notes_read", { path }, ctx));
+        const total = full.total_chars;
+        const bodyChars = codePoints(tailText);
+        const tail = resultRead(await call(captured, "notes_read", { path, offset_chars: -10 }, ctx));
+        report.push(`notes_read negative offset: ${profile.name} total=${total} -> offset_chars=${tail.offset_chars} next=${String(tail.next_offset_chars)} content=${JSON.stringify(tail.content)}`);
+        if (tail.offset_chars !== total - 10)
+            failures.push(`negative offset: notes_read ${profile.name} echoed ${tail.offset_chars}, expected ${total - 10}`);
+        if (tail.content !== codePointSlice(tailText, bodyChars - 10))
+            failures.push(`negative offset: notes_read ${profile.name} did not reach the body tail in one call`);
+        if (tail.next_offset_chars !== null)
+            failures.push(`negative offset: notes_read ${profile.name} tail read is not exhausted`);
+        const fromStart = resultRead(await call(captured, "notes_read", { path, offset_chars: -(total + 5), limit_chars: 8 }, ctx));
+        if (fromStart.offset_chars !== 0)
+            failures.push(`negative offset: notes_read ${profile.name} with N >= total_chars echoed ${fromStart.offset_chars}, expected 0`);
+        if (fromStart.content !== codePointSlice(full.content, 0, 8))
+            failures.push(`negative offset: notes_read ${profile.name} with N >= total_chars did not read from the start`);
+        const cut = resultRead(await call(captured, "notes_read", { path, offset_chars: -15, limit_chars: 4 }, ctx));
+        if (cut.next_offset_chars !== cut.offset_chars + codePoints(cut.content))
+            failures.push(`negative offset: notes_read ${profile.name} cut a negative-start read off the cursor law`);
+        const resumed = resultRead(await call(captured, "notes_read", { path, offset_chars: cut.next_offset_chars }, ctx));
+        if (resumed.offset_chars !== cut.next_offset_chars)
+            failures.push(`negative offset: notes_read ${profile.name} resume echoed ${resumed.offset_chars}, expected ${String(cut.next_offset_chars)}`);
+    }
+    // history_read gains the identical sugar over a durable item.
+    const historyTailText = `${"h".repeat(50)}END`;
+    const historyTailId = appendText(session, historyTailText);
+    const historyTail = resultRead(await call(captured, "history_read", { window_id: windowId, item_id: historyTailId, offset_chars: -3 }, ctx));
+    report.push(`history_read negative offset: offset_chars=${historyTail.offset_chars} next=${String(historyTail.next_offset_chars)} content=${JSON.stringify(historyTail.content)}`);
+    if (historyTail.offset_chars !== 50 || historyTail.content !== "END" || historyTail.next_offset_chars !== null)
+        failures.push(`negative offset: history_read returned ${JSON.stringify(historyTail)}`);
+    const historyFromStart = resultRead(await call(captured, "history_read", { window_id: windowId, item_id: historyTailId, offset_chars: -500, limit_chars: 4 }, ctx));
+    if (historyFromStart.offset_chars !== 0 || historyFromStart.content !== "hhhh")
+        failures.push(`negative offset: history_read with N >= total_chars returned ${JSON.stringify(historyFromStart)}`);
+    console.log(report.map((line) => `  ${line}`).join("\n"));
+    assert.deepEqual(failures, [], `cursor-following lost text at ${failures.length} site(s)`);
+});