@astrosheep/pi-context 0.22.1 → 0.23.1

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/dream.test.js

@@ -1,7 +1,7 @@
 import test from "node:test";
 import assert from "node:assert/strict";
-import { execFile, execFileSync } from "node:child_process";
-import { existsSync, linkSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, symlinkSync, unlinkSync, utimesSync, writeFileSync } from "node:fs";
+import { execFile, execFileSync, spawnSync } from "node:child_process";
+import { cpSync, existsSync, linkSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, symlinkSync, unlinkSync, utimesSync, writeFileSync } from "node:fs";
 import { mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -225,14 +225,34 @@ test("dreamer session has exactly the jailed file-tool allowlist", async () => {
         session.dispose();
     }
 });
-test("playbook describes plain files and the retained frontmatter", () => {
+test("playbook describes plain files, retained frontmatter, and the read-only session WAL", () => {
     const playbook = readFileSync(join(process.cwd(), "playbook.md"), "utf8");
     assert.equal(playbook.includes("notes_"), false);
     for (const field of ["origin", "status", "stale", "created_at", "updated_at", "last_accessed", "access_count"])
         assert.match(playbook, new RegExp(`^${field}:`, "m"));
     assert.equal(/^scope:/m.test(playbook), false, "scope is derived from the address rather than persisted");
+    assert.match(playbook, /`pi\/session\/\*\*` is a live agent's write-ahead log/);
+    assert.match(playbook, /never write or edit anything there/);
+    assert.match(playbook, /Session notes remain untouched even when promoted/);
     assert.match(playbook, /Nothing is physically deleted/);
 });
+test("CLI finds its package root when the installed file URL contains spaces", () => {
+    const install = mkdtempSync(join(tmpdir(), "dream install "));
+    const home = fixture();
+    try {
+        cpSync(join(process.cwd(), "dist/src"), join(install, "dist/src"), { recursive: true });
+        symlinkSync(join(process.cwd(), "node_modules"), join(install, "node_modules"), process.platform === "win32" ? "junction" : "dir");
+        cpSync(join(process.cwd(), "playbook.md"), join(install, "playbook.md"));
+        writeFileSync(join(install, "package.json"), JSON.stringify({ type: "module" }));
+        const result = spawnSync(process.execPath, [join(install, "dist/src/dream/cli.js"), "--notes-home", home, "--force", "--dreamer", "definitely-not-a-real-model"], { encoding: "utf8" });
+        assert.equal(result.status, 1, result.stderr);
+        assert.doesNotMatch(result.stderr, /could not locate installed package root/);
+        assert.match(result.stderr, /definitely-not-a-real-model/);
+    }
+    finally {
+        rmSync(install, { recursive: true, force: true });
+    }
+});
 test("provider errors are reported with partial writes instead of parsing a response", async () => {
     const factory = scriptedSession((handler) => {
         handler({ type: "tool_execution_start", toolName: "write", args: { path: "global/partial.md", content: "half" } });

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");

package/dist/test/notes.test.js

@@ -26,6 +26,20 @@ function setUpdatedAt(scope, path, ctx, timestamp) {
     const raw = readFileSync(file, "utf8");
     writeFileSync(file, raw.replace(/^updated_at: .*$/m, `updated_at: ${new Date(timestamp).toISOString()}`));
 }
+function assertNoPublicScope(value, label) {
+    if (Array.isArray(value)) {
+        for (const item of value)
+            assertNoPublicScope(item, label);
+        return;
+    }
+    if (!value || typeof value !== "object")
+        return;
+    for (const [key, child] of Object.entries(value)) {
+        assert.notEqual(key, "scope", `${label} does not expose scope`);
+        assert.notEqual(key, "resolved_scope", `${label} does not expose resolved_scope`);
+        assertNoPublicScope(child, label);
+    }
+}
 test("exactly the five notes tools are registered; the legacy five are gone", () => {
     const captured = makeExtension(manager());
     for (const name of ["notes_write", "notes_edit", "notes_read", "notes_list", "notes_search"]) {
@@ -34,6 +48,10 @@ test("exactly the five notes tools are registered; the legacy five are gone", ()
     for (const legacy of ["notes_write_file", "notes_append_to_file", "notes_read_file", "notes_search_contents", "notes_list_files"]) {
         assert.equal(captured.tools.get(legacy), undefined, `${legacy} is unregistered`);
     }
+    for (const name of ["notes_write", "notes_edit", "notes_read", "notes_list", "notes_search"]) {
+        const description = captured.tools.get(name)?.description ?? "";
+        assert.equal(/resolved_scope|\bscope\b/.test(description), false, `${name} describes home identity through address only`);
+    }
     assert.equal(captured.tools.get("notes_write")?.executionMode, "sequential");
     assert.equal(captured.tools.get("notes_edit")?.executionMode, "sequential");
     assert.equal(captured.tools.get("notes_read")?.executionMode, undefined);
@@ -45,8 +63,7 @@ test("write lands a real markdown file with harness frontmatter and a pure body"
     const ctx = context(session);
     const sessionId = session.getSessionId();
     const result = resultJson(await call(captured, "notes_write", { path: "a/b.md", content: "hello" }, ctx));
-    assert.equal(result.scope, "session");
-    assert.equal(result.size_bytes, 5);
+    assert.deepEqual(Object.keys(result).sort(), ["address", "written"]);
     const file = physicalPath("session", "a/b.md", ctx);
     assert.equal(file, join(root, "pi", "session", sessionId, "a", "b.md"));
     assert.ok(existsSync(file), "the note is a real file under the session scope dir");
@@ -60,7 +77,8 @@ test("write lands a real markdown file with harness frontmatter and a pure body"
     for (const key of ["created_at", "updated_at", "last_accessed"]) {
         assert.match(raw, new RegExp(`^${key}: \\d{4}-\\d{2}-\\d{2}T`, "m"), `frontmatter renders ${key} via localIso`);
     }
-    assert.equal(typeof result.meta.created_at, "string", "wire meta renders timestamps as ISO strings");
+    assert.equal(result.address, "a/b.md");
+    assert.equal(result.written, true);
     // A leading YAML block in user content is stripped from the body.
     await call(captured, "notes_write", { path: "stripped.md", content: "---\nscope: personal\nnonsense: true\n---\nreal body" }, ctx);
     const stripped = readFileSync(physicalPath("session", "stripped.md", ctx), "utf8");
@@ -83,7 +101,7 @@ test("overwrite preserves created_at and unknown keys, bumps updated_at, and cle
     assert.equal(after.includes("sleep_shift_key: keep-me"), true, "an unknown key survives a rewrite");
     assert.equal(after.includes("recurrence_count: 4"), true, "a known sleep-shift key survives a rewrite");
     assert.match(after, /\n---\n\nsecond$/, "the body is replaced");
-    assert.equal(rewrite.meta.origin, "self");
+    assert.deepEqual(Object.keys(rewrite).sort(), ["address", "written"]);
     const listed = listNotes(ctx, { scope: "session" })[0];
     assert.equal(listed.meta.created_at, created, "created_at is preserved across an overwrite");
     assert.ok(listed.meta.updated_at >= created, "updated_at is bumped");
@@ -111,7 +129,8 @@ test("edit is body-scoped with named failures and a replace_all escape hatch", a
     assert.equal(missing.edit_index, 0, "a zero-match anchor names the failing edit index");
     const all = resultJson(await call(captured, "notes_edit", { path: "edit.md", edits: [{ oldText: "beta", newText: "B" }], replace_all: true }, ctx));
     assert.equal(all.applied, 1);
-    assert.equal(all.resolved_scope, "session", "the success return names the layer the file was resolved from");
+    assert.equal(all.address, "edit.md");
+    assertNoPublicScope(all, "notes_edit");
     assert.equal(resultRead(await call(captured, "notes_read", { path: "edit.md" }, ctx)).content.endsWith("alpha\nB\nB\ngamma"), true, "replace_all replaces every occurrence");
     // An anchor that occurs only in frontmatter is not matched: edits are body-only.
     const frontmatterOnly = resultJson(await call(captured, "notes_edit", { path: "edit.md", edits: [{ oldText: "scope", newText: "x" }] }, ctx));
@@ -149,11 +168,13 @@ test("metadata-only edit updates setters without touching the body", async () =>
     await call(captured, "notes_write", { path: "journal.md", content: "log line" }, ctx);
     const bare = resultJson(await call(captured, "notes_edit", { path: "journal.md", stale: true }, ctx));
     assert.equal(bare.applied, 0, "a metadata-only update applies no edits");
-    assert.equal(bare.resolved_scope, "session");
-    assert.equal(bare.meta.stale, true, "stale is set without a body edit");
+    assert.equal(bare.address, "journal.md");
+    assert.deepEqual(Object.keys(bare).sort(), ["address", "applied", "diff"]);
+    assert.equal(listNotes(ctx, { scope: "session" })[0].meta.stale, true, "stale is set without a body edit");
     assert.equal(resultRead(await call(captured, "notes_read", { path: "journal.md" }, ctx)).content.endsWith("log line"), true, "the body is untouched");
     const revived = resultJson(await call(captured, "notes_edit", { path: "journal.md", stale: false }, ctx));
-    assert.equal(revived.meta.stale, false, "a later metadata-only update revives the note");
+    assert.deepEqual(Object.keys(revived).sort(), ["address", "applied", "diff"]);
+    assert.equal(listNotes(ctx, { scope: "session" })[0].meta.stale, false, "a later metadata-only update revives the note");
 });
 test("notes_edit returns a pi-edit-style diff of what changed", async () => {
     freshRoot();
@@ -234,7 +255,39 @@ test.skip("scope resolution and movement are superseded by explicit address test
     assert.match(refusal.error, /already exists/);
     assert.equal(readFileSync(physicalPath("personal", "clash.md", ctx), "utf8"), beforePersonal, "the target survives a refused move");
 });
-test("list and search merge scopes and carry scope; the path jail rejects escapes", async () => {
+test("all notes tool results use address as the only home identity", async () => {
+    freshRoot();
+    const session = manager();
+    const captured = makeExtension(session);
+    const ctx = context(session);
+    const notes = [
+        { address: "session.md", body: "session needle" },
+        { address: "@project/project.md", body: "project needle" },
+        { address: "@personal/personal.md", body: "personal needle" },
+    ];
+    for (const note of notes) {
+        const written = resultJson(await call(captured, "notes_write", { address: note.address, content: note.body }, ctx));
+        assert.equal(written.address, note.address, `notes_write returns ${note.address}`);
+        assertNoPublicScope(written, `notes_write ${note.address}`);
+        const edited = resultJson(await call(captured, "notes_edit", { address: note.address, edits: [{ oldText: "needle", newText: "match" }] }, ctx));
+        assert.equal(edited.address, note.address, `notes_edit returns ${note.address}`);
+        assertNoPublicScope(edited, `notes_edit ${note.address}`);
+        const rawRead = await call(captured, "notes_read", { address: note.address }, ctx);
+        const read = resultRead(rawRead);
+        assert.equal(read.details.address, note.address, `notes_read details returns ${note.address}`);
+        assert.equal(read.header.startsWith("--- READ WINDOW ---\naddress: "), true, `notes_read starts a READ WINDOW block for ${note.address}`);
+        assert.equal(read.header.includes("scope"), false, `notes_read header omits scope for ${note.address}`);
+        assert.equal(read.header.includes("resolved_scope"), false, `notes_read header omits resolved_scope for ${note.address}`);
+        assertNoPublicScope(read.details, `notes_read ${note.address}`);
+    }
+    const listed = resultJson(await call(captured, "notes_list", { pattern: "**" }, ctx));
+    assert.deepEqual(listed.files.map((file) => file.address).sort(), notes.map((note) => note.address).sort(), "notes_list returns each full address");
+    assertNoPublicScope(listed, "notes_list");
+    const searched = resultJson(await call(captured, "notes_search", { query: "match", pattern: "**" }, ctx));
+    assert.deepEqual(searched.files.map((file) => file.address), notes.map((note) => note.address).sort(), "notes_search returns each full address");
+    assertNoPublicScope(searched, "notes_search");
+});
+test("list and search merge scopes and carry addresses; the path jail rejects escapes", async () => {
     freshRoot();
     const session = manager();
     const captured = makeExtension(session);
@@ -243,24 +296,24 @@ test("list and search merge scopes and carry scope; the path jail rejects escape
     await call(captured, "notes_write", { path: "two.md", content: "needle two", scope: "project" }, ctx);
     await call(captured, "notes_write", { path: "three.md", content: "needle three", scope: "personal" }, ctx);
     const listed = resultJson(await call(captured, "notes_list", {}, ctx));
-    assert.deepEqual([...listed.files].map((file) => file.scope).sort(), ["personal", "project", "session"], "every merged row carries its scope");
+    assert.deepEqual([...listed.files].map((file) => file.address).sort(), ["@personal/three.md", "@project/two.md", "one.md"], "every merged row carries its full address");
     for (const row of listed.files) {
-        assert.equal(typeof row.size_bytes, "number");
-        assert.equal(row.origin, "self");
-        assert.equal(row.status, "active");
+        assert.deepEqual(Object.keys(row).sort(), ["address", "stale", "updated_at"]);
         assert.equal(row.stale, false);
     }
     const scoped = resultJson(await call(captured, "notes_list", { scope: "personal" }, ctx));
-    assert.deepEqual(scoped.files.map((file) => file.path), ["three.md"], "a scope filter narrows the set");
+    assert.deepEqual(scoped.files.map((file) => file.address), ["@personal/three.md"], "an address-pattern filter narrows the set");
     const searched = resultJson(await call(captured, "notes_search", { query: "needle" }, ctx));
     assert.equal(searched.files.length, 3, "literal search finds matches in every scope");
-    assert.deepEqual([...searched.files].map((file) => file.scope).sort(), ["personal", "project", "session"]);
+    assert.deepEqual([...searched.files].map((file) => file.address).sort(), ["@personal/three.md", "@project/two.md", "one.md"]);
+    for (const row of [...listed.files, ...searched.files])
+        assertNoPublicScope(row, "notes_list/search");
     assert.equal(searched.files.every((file) => file.matches_total === 1), true);
     const hit = searched.files[0].matches[0];
     assert.equal(hit.line, 1);
-    assert.equal(hit.offset_chars, 0);
+    assert.ok(hit.offset_chars > 0, "the offset includes serialized frontmatter");
     assert.equal(hit.truncated, false);
-    assert.equal(hit.total_chars, searched.files[0].path === "three.md" ? "needle three".length : hit.text.length, "total_chars names the real line length");
+    assert.deepEqual(Object.keys(hit).sort(), ["line", "offset_chars", "text", "truncated"]);
     const escaped = ["../evil", "/abs", "a\\b"];
     for (const tool of ["notes_write", "notes_edit", "notes_read"]) {
         for (const path of escaped) {
@@ -291,6 +344,38 @@ test("the boot index reads the physical store across scopes and excludes stale n
         assert.equal(PROTOCOL_BLOCK.includes(legacy), false, `the protocol block no longer names ${legacy}`);
     }
 });
+test("search offsets start reads at Unicode matches across homes without mutating search results", async () => {
+    freshRoot();
+    const session = manager();
+    const captured = makeExtension(session);
+    const ctx = context(session);
+    const notes = [
+        { address: "session.md", scope: "session", body: "first line\n前置 🐉 needle-session\nend", needle: "needle-session" },
+        { address: "@project/crossing.md", scope: "project", body: "prefix\nneedle-project 😀", needle: "needle-project" },
+        { address: "@personal/legacy.md", scope: "personal", body: "legacy 😺 needle-personal", needle: "needle-personal" },
+    ];
+    for (const note of notes)
+        await call(captured, "notes_write", { address: note.address, content: note.body }, ctx);
+    const crossing = physicalPath("project", "crossing.md", ctx);
+    writeFileSync(crossing, readFileSync(crossing, "utf8").replace(/^access_count: 0$/m, "access_count: 9"));
+    const legacy = physicalPath("personal", "legacy.md", ctx);
+    writeFileSync(legacy, notes[2].body);
+    const before = new Map(notes.map((note) => [note.address, readFileSync(physicalPath(note.scope, note.address.replace(/^@(?:project|personal)\//, ""), ctx), "utf8")]));
+    const searched = resultJson(await call(captured, "notes_search", { query: notes.map((note) => note.needle), pattern: "**" }, ctx));
+    for (const note of notes) {
+        assert.equal(readFileSync(physicalPath(note.scope, note.address.replace(/^@(?:project|personal)\//, ""), ctx), "utf8"), before.get(note.address), `search leaves ${note.address} byte-identical`);
+        const file = searched.files.find((candidate) => candidate.address === note.address);
+        assert.ok(file, `search returns ${note.address}`);
+        assert.deepEqual(Object.keys(file).sort(), ["address", "matches", "matches_total", "stale", "updated_at"]);
+        const hit = file.matches[0];
+        assert.deepEqual(Object.keys(hit).sort(), ["line", "offset_chars", "text", "truncated"]);
+        const read = resultRead(await call(captured, "notes_read", { address: note.address, offset_chars: hit.offset_chars }, ctx));
+        assert.ok(read.content.startsWith(note.needle), `search offset starts notes_read at ${note.needle}`);
+        assert.deepEqual(Object.keys(read.details).sort(), ["address", "next_offset_chars", "offset_chars", "total_chars"]);
+    }
+    assert.match(readFileSync(crossing, "utf8"), /^access_count: 10$/m, "the predicted read crosses access_count from 9 to 10");
+    assert.match(resultRead(await call(captured, "notes_read", { address: "@personal/legacy.md" }, ctx)).content, /^---\n/, "a missing-frontmatter note is normalized only by read");
+});
 test("notes_read surfaces frontmatter and search reports body lines", async () => {
     freshRoot();
     const session = manager();
@@ -303,7 +388,7 @@ test("notes_read surfaces frontmatter and search reports body lines", async () =
     const searched = resultJson(await call(captured, "notes_search", { query: "needle" }, ctx));
     const match = searched.files[0].matches[0];
     assert.equal(match.line, 2, "search reports the body line number");
-    assert.equal(match.offset_chars, Array.from("line one\n").length, "offset_chars addresses the query within the body");
+    assert.equal(match.offset_chars, read.content.indexOf("needle"), "offset_chars addresses the query in the serialized read stream");
 });
 test("mutations are atomic, leave no temp files, and a read bumps only the access keys", async () => {
     freshRoot();
@@ -443,11 +528,12 @@ test("full addresses drive outputs and patterns; on-disk scope is read then drop
     assert.deepEqual(resultJson(await call(captured, "notes_list", { pattern: "*.md" }, ctx)).files.map((file) => file.address), ["root.md"]);
     assert.deepEqual(resultJson(await call(captured, "notes_search", { query: "needle", pattern: "@project/**" }, ctx)).files.map((file) => file.address), ["@project/project.md"]);
     const read = resultRead(await call(captured, "notes_read", { address: "@personal/personal.md" }, ctx));
-    assert.match(read.header, /^\[@personal\/personal\.md /, "the raw read header echoes the full address");
+    assert.equal(read.header, "--- READ WINDOW ---\naddress: @personal/personal.md\nchars: [0," + read.total_chars + ") of " + read.total_chars + "\nnext_offset_chars: null\n", "the raw READ WINDOW block echoes the full address");
     const legacy = physicalPath("project", "legacy.md", ctx);
     writeFileSync(legacy, "---\nscope: personal\norigin: self\nstatus: active\nstale: false\ncreated_at: 2026-01-01T00:00:00.000+00:00\nupdated_at: 2026-01-01T00:00:00.000+00:00\nlast_accessed: 2026-01-01T00:00:00.000+00:00\naccess_count: 0\n---\n\nlegacy");
     const legacyRead = resultRead(await call(captured, "notes_read", { address: "@project/legacy.md" }, ctx));
-    assert.equal(legacyRead.details.scope, "project", "scope is derived from the file location");
+    assert.equal(legacyRead.details.address, "@project/legacy.md", "the read keeps the requested address while deriving its home internally");
+    assertNoPublicScope(legacyRead.details, "legacy notes_read");
     await call(captured, "notes_edit", { address: "@project/legacy.md", stale: true }, ctx);
     assert.equal(/^scope:/m.test(readFileSync(legacy, "utf8")), false, "the next write removes legacy scope frontmatter");
 });