@astrosheep/pi-context 0.22.0 → 0.23.0

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

@@ -7,7 +7,7 @@ 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"]) {
+for (const mode of ["golden", "write-error", "ignored-warning", "explicit", "uncompactable", "followup", "steering", "repeat", "nested", "immediate-dispose", "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;
@@ -16,6 +16,7 @@ for (const mode of ["golden", "write-error", "ignored-warning", "explicit", "unc
         const notesRoot = mkdtempSync(join(tmpdir(), "pi-context-loop-notes-"));
         process.env.PI_NOTES_HOME = notesRoot;
         let session;
+        let disposed = false;
         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");
@@ -23,7 +24,7 @@ for (const mode of ["golden", "write-error", "ignored-warning", "explicit", "unc
             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 expectedResets = mode === "abort" || mode === "uncompactable" ? 0 : mode === "nested" ? 2 : 1;
             // 0.86 split-turn cut can still summarize a turn prefix, so keepRecentTokens: 1 no longer
             // makes a reset uncompactable; a keep larger than the whole session keeps everything and does.
             const settings = { compaction: { enabled: usageMode, reserveTokens: 32768, keepRecentTokens: mode === "uncompactable" ? 1_000_000 : 200 }, retry: { enabled: false } };
@@ -36,7 +37,7 @@ for (const mode of ["golden", "write-error", "ignored-warning", "explicit", "unc
             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 finishTimeout = setTimeout(() => failFinish(new Error(`timed out waiting for ${mode} agent settlement (resets=${resets}, settled=${settled}, requests=${requests.length})`)), 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: [] }),
@@ -83,7 +84,8 @@ for (const mode of ["golden", "write-error", "ignored-warning", "explicit", "unc
                     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 explicitReset = (n === 1 && !usageMode && mode !== "uncompactable") || (mode === "repeat" && (n === 1 || n === 3)) || (mode === "nested" && n === 3);
+                const nestedCheckpoint = mode === "nested" && n === 2;
                 const checkpoint = usageMode && sawWarning && !checkpointed && mode !== "ignored-warning";
                 if (checkpoint)
                     checkpointed = true;
@@ -92,11 +94,11 @@ for (const mode of ["golden", "write-error", "ignored-warning", "explicit", "unc
                 // 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 tool = explicitReset || nestedCheckpoint || (mode === "uncompactable" && n === 1);
+                const call = probe ? "get_context_remaining" : checkpoint || nestedCheckpoint ? "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: { address: mode === "write-error" ? "../invalid.md" : "checkpoint.md", content: "CHECKPOINT_SENTINEL" } }]
+                        : checkpoint || nestedCheckpoint ? [{ type: "toolCall", id: "checkpoint-call", name: "notes_write", arguments: { address: mode === "write-error" ? "../invalid.md" : "checkpoint.md", content: nestedCheckpoint ? "NESTED_RESET_PADDING ".repeat(300) : "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(),
@@ -116,9 +118,18 @@ for (const mode of ["golden", "write-error", "ignored-warning", "explicit", "unc
                 }
             });
             await session.prompt("OLD_CONTEXT_SENTINEL: save progress and continue the task.");
+            if (mode === "immediate-dispose") {
+                // prompt() must not resolve after compaction merely because sendMessage is
+                // detached: by this point the continuation has settled and answered.
+                session.dispose();
+                disposed = true;
+                assert.ok(settled >= 2, "the continuation settles before the originating prompt resolves");
+                assert.ok(requests.length >= 2 && !requests.at(-1).includes("OLD_CONTEXT_SENTINEL"), "the resumed answer exists before immediate disposal");
+            }
             await finished;
             clearTimeout(finishTimeout);
-            await session.waitForIdle();
+            if (!disposed)
+                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");
@@ -169,6 +180,10 @@ for (const mode of ["golden", "write-error", "ignored-warning", "explicit", "unc
                 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 === "nested") {
+                assert.equal(resets, 2, "a continuation-requested reset forms a second completed handoff");
+                assert.equal(new Set(sm.getBranch().filter((entry) => entry.type === "compaction").map((entry) => JSON.stringify(entry.details))).size, 2);
+            }
             if (mode === "repeat") {
                 const nextFinished = new Promise((resolve) => { finish = resolve; });
                 targetResets = 2;
@@ -198,7 +213,8 @@ for (const mode of ["golden", "write-error", "ignored-warning", "explicit", "unc
             }
         }
         finally {
-            session?.dispose();
+            if (!disposed)
+                session?.dispose();
             if (previousDir === undefined)
                 delete process.env.PI_CODING_AGENT_DIR;
             else

package/dist/test/coherence.test.js

@@ -71,25 +71,19 @@ function assertWithinBudget(result, label) {
 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.
- */
+/** Decode either raw read through the shared READ WINDOW grammar without including metadata in the payload. */
 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");
+    const block = /^(--- READ WINDOW ---\n(?:[a-z_]+: [^\n]*\n)+chars: \[(\d+),(\d+)\) of (\d+)\nnext_offset_chars: (null|\d+)\n)\n/.exec(text.text);
+    assert.ok(block, "raw read carries one READ WINDOW block followed by exactly one blank line");
+    const header = block[1];
+    const content = text.text.slice(block[0].length);
+    const offset_chars = Number(block[2]);
+    const end = Number(block[3]);
+    const total_chars = Number(block[4]);
+    const next_offset_chars = block[5] === "null" ? null : Number(block[5]);
+    assert.equal([...content].length, end - offset_chars, "READ WINDOW range matches the delivered payload");
     return { header, content, offset_chars, total_chars, next_offset_chars };
 }
 const PROFILES = [
@@ -213,18 +207,17 @@ test("coherence: following the returned cursors reconstructs the original text e
     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)}`);
+    report.push(`notes_search: matches_total=${String(matchedFile?.matches_total)} returned=${String(matchedFile?.matches.length)} first match delivered ${codePoints(matched?.text ?? "")} 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 atMatch = resultRead(await call(captured, "notes_read", { path: "huge-cjk.md", offset_chars: matched.offset_chars }, ctx));
+        if (!atMatch.content.startsWith("历"))
+            failures.push("notes_search offset does not start notes_read at the matched substring");
         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`);
@@ -309,27 +302,30 @@ test("coherence: following the returned cursors reconstructs the original text e
         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.
+    // --- notes_search addresses: each match offset directly starts notes_read at the earliest
+    // query occurrence in its line, including multi-query OR.
     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;
+    report.push(`notes_search address: line=${String(addressHit?.line)} offset_chars=${String(addressHit?.offset_chars)}`);
+    if (addressHit === undefined)
+        failures.push("notes_search carries no line-three match");
+    else {
+        const atMatch = resultRead(await call(captured, "notes_read", { path: "address.md", offset_chars: addressHit.offset_chars }, ctx));
+        if (!atMatch.content.startsWith("needle-address"))
+            failures.push(`notes_search offset_chars=${addressHit.offset_chars} does not start at the line-three query`);
+    }
     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)`);
+    report.push(`notes_search OR address: offset_chars=${String(orLine4?.offset_chars)}`);
+    if (orLine4 === undefined)
+        failures.push("notes_search carries no line-four OR match");
+    else {
+        const atMatch = resultRead(await call(captured, "notes_read", { path: "address.md", offset_chars: orLine4.offset_chars }, ctx));
+        if (!atMatch.content.startsWith("zeta"))
+            failures.push(`notes_search OR offset_chars=${orLine4.offset_chars} does not start at the earliest line-four 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.

package/dist/test/doctor.test.js

@@ -0,0 +1,44 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, symlinkSync, readdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { doctor } from "../src/dream/doctor.js";
+import { main } from "../src/dream/cli.js";
+const note = (body = "") => `---\norigin: self\nstatus: active\nstale: false\ncreated_at: 2026-01-01T00:00:00Z\nupdated_at: 2026-01-01T00:00:00Z\nlast_accessed: 2026-01-01T00:00:00Z\naccess_count: 0\n---\n\n${body}`;
+const home = () => mkdtempSync(join(tmpdir(), "dream-doctor-"));
+test("doctor validates note homes and references without changing files", async () => {
+    const root = home();
+    mkdirSync(join(root, "personal"));
+    writeFileSync(join(root, "personal/a.md"), note());
+    writeFileSync(join(root, "personal/MAP.md"), note("- `a.md`\n- `@personal/a.md`"));
+    const before = readFileSync(join(root, "personal/a.md"));
+    assert.deepEqual(doctor(root), []);
+    assert.equal(await main(["doctor", "--notes-home", root], { runDreamer: async () => { throw new Error("must not run"); } }), 0);
+    assert.deepEqual(readFileSync(join(root, "personal/a.md")), before);
+    assert.deepEqual(readdirSync(root), ["personal"]);
+});
+test("doctor reports layout, metadata, links and locks; never repairs", () => {
+    const root = home();
+    mkdirSync(join(root, "global"));
+    mkdirSync(join(root, "project/bad"), { recursive: true });
+    writeFileSync(join(root, "project/bad/MAP.md"), note("`missing.md` `@global/old.md`"));
+    writeFileSync(join(root, "project/bad/broken.md"), "---\norigin: nope\n---\n");
+    writeFileSync(join(root, ".dream.lock"), "garbage");
+    symlinkSync(join(root, "project"), join(root, "project/bad/link"));
+    const output = doctor(root).join("\n");
+    for (const expected of ["legacy home", "invalid project key", "target missing", "invalid address", "invalid origin", "invalid created_at", "malformed lock", "symlink"])
+        assert.ok(output.includes(expected), expected);
+    assert.equal(readFileSync(join(root, ".dream.lock"), "utf8"), "garbage");
+    assert.ok(existsSync(join(root, "global")));
+});
+test("doctor reports missing homes without creating them, including CLI", async () => {
+    const missing = join(home(), "absent");
+    assert.equal(await main(["doctor", "--notes-home", missing]), 1);
+    assert.equal(existsSync(missing), false);
+});
+test("doctor reports valid lock presence without claiming it is stale", () => {
+    const root = home();
+    writeFileSync(join(root, ".dream.lock"), "123 12345678-1234-1234-1234-123456789abc");
+    assert.match(doctor(root).join("\n"), /lock present.*liveness not inferred/);
+});

package/dist/test/integration.test.js

@@ -152,26 +152,19 @@ export function assertWithinBudget(result, message) {
     const bytes = text && text.type === "text" ? Buffer.byteLength(text.text, "utf8") : 0;
     assert.ok(bytes <= TOOL_OUTPUT_MAX_BYTES, `${message}: ${bytes} bytes over the ${TOOL_OUTPUT_MAX_BYTES}-byte budget`);
 }
-/**
- * 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.
- */
+/** Decode either raw read without including its shared metadata block in the payload. */
 export 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 end = Number(match[2]);
-    const total_chars = Number(match[3]);
-    const next_offset_chars = match[4] === "end" ? null : Number(match[5]);
-    assert.equal(Array.from(content).length, end - offset_chars, "the header range matches the delivered payload");
+    const block = /^(--- READ WINDOW ---\n(?:[a-z_]+: [^\n]*\n)+chars: \[(\d+),(\d+)\) of (\d+)\nnext_offset_chars: (null|\d+)\n)\n/.exec(text.text);
+    assert.ok(block, "raw read carries one READ WINDOW block followed by exactly one blank line");
+    const header = block[1];
+    const content = text.text.slice(block[0].length);
+    const offset_chars = Number(block[2]);
+    const end = Number(block[3]);
+    const total_chars = Number(block[4]);
+    const next_offset_chars = block[5] === "null" ? null : Number(block[5]);
+    assert.equal(Array.from(content).length, end - offset_chars, "READ WINDOW range matches the delivered payload");
     return { header, content, offset_chars, total_chars, next_offset_chars, details: (result.details ?? {}) };
 }
 /**
@@ -328,7 +321,7 @@ test("notes_list is most-recently-updated first across merged scopes", async ()
     assert.deepEqual((await files({})).map((file) => file.address), ["@personal/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("personal", "a.md", base + 10);
-    assert.deepEqual((await files({})).filter((file) => file.address.endsWith("a.md")).map((file) => file.scope), ["personal", "session"], "equal timestamps tie-break by full address");
+    assert.deepEqual((await files({})).filter((file) => file.address.endsWith("a.md")).map((file) => file.address), ["@personal/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 () => {
@@ -345,7 +338,6 @@ test("notes are real files that persist across sessions and round-trip Unicode",
     const read = resultRead(rawRead);
     assert.equal(read.details.address, "@personal/checkpoint/进度.md");
     assert.equal(read.content, "Café", "a negative offset reads the body tail in one call");
-    assert.equal(read.details.scope, "personal");
     const searched = resultJson(await call(restoredCaptured, "notes_search", { query: "Café", scope: "personal" }, restoredCtx));
     assert.equal(searched.files[0]?.matches[0]?.line, 2);
     const listedFiles = resultJson(await call(restoredCaptured, "notes_list", { pattern: "checkpoint/**", scope: "personal" }, restoredCtx));
@@ -366,11 +358,11 @@ test("stale lifecycle: writes and metadata-only edits close and revive a note",
     // 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(markOnly.meta.stale, true);
+    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(revived.meta.stale, false, "stale:false revives");
+    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);
@@ -705,8 +697,8 @@ test("an over-budget note is delivered as a prefix and resumed by next_offset_ch
     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, `[huge.md · chars 0-${first.next_offset_chars} of ${first.total_chars} · continue at offset_chars=${first.next_offset_chars} · session · created ${String(first.details.created_at)} · updated ${String(first.details.updated_at)}]`, "the raw header names the address, delivered range, resume cursor, scope and timestamps");
-    assert.deepEqual(Object.keys(first.details).sort(), ["address", "created_at", "limit_chars", "next_offset_chars", "offset_chars", "scope", "total_chars", "updated_at"], "notes_read details carries exactly the slim window metadata plus scope");
+    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.
@@ -753,11 +745,11 @@ test("an over-budget note search match is a named prefix with an honest line add
     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.equal(match.total_chars, Array.from(hugeLine).length, "total_chars names the full line length");
     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.offset_chars, 500, "the match carries the body-absolute offset of the query");
     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;
@@ -784,7 +776,9 @@ test("history_read delivers a prefix and next_offset_chars names the delivered c
     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.deepEqual(Object.keys(read.details), ["window_id", "item_id", "offset_chars", "total_chars", "next_offset_chars", "limit_chars"], "history_read details carries exactly the slim window metadata");
+    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");
@@ -794,6 +788,7 @@ test("history_read delivers a prefix and next_offset_chars names the delivered c
     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;
@@ -813,6 +808,7 @@ test("an empty body is a frontmatter-only file that terminates cleanly", async (
     assert.ok(empty.content.endsWith("---\n\n"), "an empty body leaves frontmatter and the blank separator only");
     assert.ok(empty.total_chars > 0, "the file is not zero-length once the harness frontmatter is written");
     assert.equal(empty.next_offset_chars, null, "a note that fits terminates instead of self-feeding");
+    assert.equal(empty.header, `--- READ WINDOW ---\naddress: empty.md\nchars: [0,${empty.total_chars}) of ${empty.total_chars}\nnext_offset_chars: null\n`, "an exhausted window writes literal null");
     // An offset beyond the file is an addressing error that names the real length,
     // not a silent empty page.
     const beyond = resultJson(await call(captured, "notes_read", { path: "empty.md", offset_chars: empty.total_chars + 9 }, ctx));
@@ -1727,13 +1723,16 @@ test("argument footguns die loudly and tool-run metadata surfaces (A1/A2/A3/B4/B
     const noteEnd = resultRead(await call(captured, "notes_read", { path: "a.md", offset_chars: noteTotal }, ctx));
     assert.equal(noteEnd.content, "", "notes: offset == total is the legal empty end-read");
     assert.equal(noteEnd.next_offset_chars, null, "notes: the end-read terminates");
+    assert.equal(noteEnd.header, `--- READ WINDOW ---\naddress: a.md\nchars: [${noteTotal},${noteTotal}) of ${noteTotal}\nnext_offset_chars: null\n`, "notes: empty end-read retains the exact READ WINDOW block");
+    const itemFull = resultRead(await call(captured, "history_read", { window_id: windowId, item_id: target.item_id }, ctx));
+    assert.equal(itemFull.header, `--- READ WINDOW ---\nwindow_id: ${windowId}\nitem_id: ${target.item_id}\nchars: [0,11) of 11\nnext_offset_chars: null\n`, "history: a fitting read retains the exact shared READ WINDOW block");
     const itemPastEnd = resultJson(await call(captured, "history_read", { window_id: windowId, item_id: target.item_id, offset_chars: 12 }, ctx));
     assert.match(itemPastEnd.error ?? "", /past the end/, "history: past-end offset is a named error");
     assert.equal(itemPastEnd.total_chars, 11, "history: the error names the real length");
     assert.equal(itemPastEnd.item_id, target.item_id, "history: the error echoes the item_id");
     const itemEnd = resultRead(await call(captured, "history_read", { window_id: windowId, item_id: target.item_id, offset_chars: 11 }, ctx));
     assert.equal(itemEnd.content, "", "history: offset == total is the legal empty end-read");
-    assert.equal(itemEnd.next_offset_chars, null, "history: the end-read terminates");
+    assert.equal(itemEnd.header, `--- READ WINDOW ---\nwindow_id: ${windowId}\nitem_id: ${target.item_id}\nchars: [11,11) of 11\nnext_offset_chars: null\n`, "history: empty end-read retains the exact READ WINDOW block");
     // A3: editing a missing note is the typed not-found arm; write still creates it.
     const editMissing = resultJson(await call(captured, "notes_edit", { path: "missing.md", stale: true }, ctx));
     assert.equal(editMissing.error, "note not found", "an edit of a missing note is named");