@astrosheep/pi-context 0.26.0 → 0.26.1

package/dist/test/budget-settings.integration.test.js

@@ -1,11 +1,9 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 import { internal } from "../src/index.js";
-import { appendText, call, commitTurnEndBoundary, context, installExtensionTestEnvironment, makeExtension, manager, noticesOf, resultJson, runContextHook, runHandlers, sentOf, settingsFixture, } from "./helpers/extension.js";
-const testEnvironment = installExtensionTestEnvironment("pi-context-integration");
-test.beforeEach(() => testEnvironment.beforeEach());
-test.afterEach(() => testEnvironment.afterEach());
-test.after(() => testEnvironment.dispose());
+import { appendText, call, commitTurnEndBoundary, context, makeExtension, manager, noticesOf, resultJson, runContextHook, runHandlers, sentOf, settingsFixture, } from "./helpers/extension.js";
+import { installExtensionTestHooks } from "./helpers/extension-test-environment.js";
+const testEnvironment = installExtensionTestHooks("pi-context-integration");
 test("low-budget guidance and warning persist at turn_end, once per active window", async () => {
     const sessionManager = manager();
     const captured = makeExtension(sessionManager);
@@ -24,6 +22,23 @@ test("low-budget guidance and warning persist at turn_end, once per active windo
     assert.equal(warningBoundary.entries.filter((entry) => entry.type === "custom_message" && entry.customType === internal.WARNING_TYPE).length, 1);
     assert.equal(sessionManager.getBranch().filter((entry) => entry.type === "custom_message" && entry.customType === internal.WARNING_TYPE).length, 1);
 });
+test("early guidance stays silent and the committed final warning notifies once", async () => {
+    const sm = manager();
+    const captured = makeExtension(sm);
+    const early = context(sm, undefined, { tokens: 165_000, percent: 82.5, contextWindow: 200_000 });
+    assert.equal(await runContextHook(captured, early), undefined, "early guidance is persisted at turn_end, not injected immediately");
+    await commitTurnEndBoundary(captured, sm, early);
+    await runHandlers(captured, "agent_settled", {}, early);
+    assert.equal(noticesOf(early).filter((notice) => notice.message.includes("Context running low") || notice.message.includes("Context almost full")).length, 0, "early model guidance has no UI toast");
+    assert.equal(sm.getBranch().filter((entry) => entry.type === "custom_message" && entry.customType === internal.GUIDANCE_TYPE).length, 1, "early guidance remains durable for the model");
+    const final = context(sm, undefined, { tokens: 181_000, percent: 90.5, contextWindow: 200_000 });
+    const warning = await runContextHook(captured, final);
+    assert.equal(warning?.messages[0]?.customType, internal.WARNING_TYPE);
+    await commitTurnEndBoundary(captured, sm, final);
+    await runHandlers(captured, "turn_start", {}, final);
+    await runHandlers(captured, "agent_settled", {}, final);
+    assert.equal(noticesOf(final).filter((notice) => notice.message === "pi-context: Context almost full; close out the current memory window.").length, 1, "only the committed final warning notifies, exactly once");
+});
 test("the visible countdown ends at the warning line, clamps at zero, and preserves unknown usage", async () => {
     const fixture = settingsFixture({
         reserveTokens: 16_384,

package/dist/test/helpers/extension-test-environment.d.ts

@@ -0,0 +1 @@
+export declare function installExtensionTestHooks(prefix: string): import("./extension.js").ExtensionTestEnvironment;

package/dist/test/helpers/extension-test-environment.js

@@ -0,0 +1,9 @@
+import test from "node:test";
+import { installExtensionTestEnvironment } from "./extension.js";
+export function installExtensionTestHooks(prefix) {
+    const environment = installExtensionTestEnvironment(prefix);
+    test.beforeEach(() => environment.beforeEach());
+    test.afterEach(() => environment.afterEach());
+    test.after(() => environment.dispose());
+    return environment;
+}

package/dist/test/helpers/extension.d.ts

@@ -88,19 +88,8 @@ export type ReadWindow = {
 };
 /** Decode either raw read without including its shared metadata block in the payload. */
 export declare function resultRead(result: AgentToolResult<unknown>): ReadWindow;
-/**
- * Assert a value is a local-time ISO 8601 string with an explicit numeric offset (never "Z")
- * and that Date.parse restores the stored epoch milliseconds. No time zone is assumed.
- */
-export declare function assertLocalIso(value: unknown, epochMs: number, message: string): void;
-/** Assert the text contains a well-formed local ISO timestamp and return it, without pinning surrounding wording. */
-export declare function assertIsoTimestamp(text: string, message: string): string;
-/** Assert `actual` is a middle-truncation of `original`: same head, same tail, strictly fewer characters. */
-export declare function assertTruncationOf(original: string, actual: string): void;
 export declare function runManualCompact(captured: Captured, ctx: ExtensionContext): Promise<CompactionHookResult>;
 export declare function runHandlers(captured: Captured, name: string, event: unknown, ctx: ExtensionContext): Promise<void>;
-export declare function runHandlersAsync(captured: Captured, name: string, event: unknown, ctx: ExtensionContext): Promise<unknown[]>;
-export declare function completeRequestedCompaction(ctx: ExtensionContext): void;
 export declare function runCommand(captured: Captured, name: string, args: string, ctx: ExtensionContext): Promise<Notice[]>;
 export type ContextHookResult = {
     messages: unknown[];

package/dist/test/helpers/extension.js

@@ -166,41 +166,12 @@ export function sentOf(captured, customType) {
 export async function call(captured, name, params, ctx) {
     const tool = captured.tools.get(name);
     assert.ok(tool, `registered ${name}`);
-    // Most pre-redesign coverage names session notes by their bare address. Keep these old
-    // fixture call sites readable while routing the direct tool invocation through its new
-    // address-shaped input; contract-specific tests below pass address themselves.
-    const noteCall = name === "notes_write" || name === "notes_edit" || name === "notes_read";
-    if (noteCall && "path" in params && !("address" in params)) {
-        const { path, scope, ...rest } = params;
-        assert.equal(typeof path, "string", "legacy note fixture path is a string");
-        const address = scope === "project" ? `@project/${path}` : scope === "human" ? `@human/${path}` : path;
-        return tool.execute("call-1", { ...rest, address }, new AbortController().signal, () => { }, ctx);
-    }
-    if ((name === "notes_list" || name === "notes_search") && params.scope === "human") {
-        const { scope: _scope, pattern, ...rest } = params;
-        return tool.execute("call-1", { ...rest, pattern: `@human/${typeof pattern === "string" ? pattern : "**"}` }, new AbortController().signal, () => { }, ctx);
-    }
-    if ((name === "notes_list" || name === "notes_search") && params.scope === "session") {
-        const { scope: _scope, pattern, ...rest } = params;
-        return tool.execute("call-1", { ...rest, pattern: typeof pattern === "string" ? pattern : "*.md" }, new AbortController().signal, () => { }, ctx);
-    }
     return tool.execute("call-1", params, new AbortController().signal, () => { }, ctx);
 }
 export function resultJson(result) {
     const text = result.content[0];
     assert.ok(text && text.type === "text", "tool result carries text");
-    const value = JSON.parse(text.text);
-    const suffix = (address) => address.startsWith("@project/") ? address.slice("@project/".length) : address.startsWith("@human/") ? address.slice("@human/".length) : address;
-    const legacyPath = (row) => {
-        if (typeof row.address === "string" && row.path === undefined)
-            Object.defineProperty(row, "path", { value: suffix(row.address), enumerable: false });
-    };
-    legacyPath(value);
-    if (Array.isArray(value.files))
-        for (const file of value.files)
-            if (file && typeof file === "object")
-                legacyPath(file);
-    return value;
+    return JSON.parse(text.text);
 }
 /** Assert the delivered wire text fits the tool-output budget, header included for raw reads. */
 export function assertWithinBudget(result, message) {
@@ -223,32 +194,6 @@ export function resultRead(result) {
     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 ?? {}) };
 }
-/**
- * Assert a value is a local-time ISO 8601 string with an explicit numeric offset (never "Z")
- * and that Date.parse restores the stored epoch milliseconds. No time zone is assumed.
- */
-export function assertLocalIso(value, epochMs, message) {
-    assert.equal(typeof value, "string", message);
-    assert.match(value, /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}[+-]\d{2}:\d{2}$/, message);
-    assert.equal(Date.parse(value), epochMs, `${message}: Date.parse restores the stored epoch ms`);
-}
-/** Assert the text contains a well-formed local ISO timestamp and return it, without pinning surrounding wording. */
-export function assertIsoTimestamp(text, message) {
-    const match = text.match(/\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}[+-]\d{2}:\d{2}/);
-    assert.ok(match, message);
-    assert.equal(Number.isNaN(Date.parse(match[0])), false, `${message}: timestamp parses`);
-    return match[0];
-}
-/** Assert `actual` is a middle-truncation of `original`: same head, same tail, strictly fewer characters. */
-export function assertTruncationOf(original, actual) {
-    const match = actual.match(/^([\s\S]*)…\[truncated \d+ chars\]…([\s\S]*)$/);
-    assert.ok(match, "truncated value carries the middle-truncation marker");
-    const head = match[1];
-    const tail = match[2];
-    assert.ok(original.startsWith(head), "truncation keeps the original head");
-    assert.ok(original.endsWith(tail), "truncation keeps the original tail");
-    assert.ok(head.length + tail.length < original.length, "truncation actually removes characters");
-}
 export async function runManualCompact(captured, ctx) {
     const handler = captured.handlers.get("session_before_compact")?.[0];
     assert.ok(handler, "session_before_compact handler registered");
@@ -282,25 +227,6 @@ export async function runHandlers(captured, name, event, ctx) {
         ctx.isIdle = isIdle;
     }
 }
-export async function runHandlersAsync(captured, name, event, ctx) {
-    const results = [];
-    for (const handler of captured.handlers.get(name) ?? [])
-        results.push(await handler(event, ctx));
-    return results;
-}
-export function completeRequestedCompaction(ctx) {
-    const requests = ctx.compactionRequests;
-    const options = requests.shift();
-    assert.ok(options?.onComplete, "a reset request has a completion callback");
-    const isIdle = ctx.isIdle;
-    ctx.isIdle = () => true;
-    try {
-        options.onComplete({});
-    }
-    finally {
-        ctx.isIdle = isIdle;
-    }
-}
 export async function runCommand(captured, name, args, ctx) {
     const command = captured.commands.get(name);
     assert.ok(command, `${name} command registered`);

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

@@ -2,11 +2,9 @@ import assert from "node:assert/strict";
 import test from "node:test";
 import { historyFromSession } from "../src/index.js";
 import { TOOL_OUTPUT_MAX_BYTES } from "../src/tool-output.js";
-import { appendText, assertWithinBudget, call, context, installExtensionTestEnvironment, makeExtension, manager, objectSchema, resultJson, resultRead, } from "./helpers/extension.js";
-const testEnvironment = installExtensionTestEnvironment("pi-context-integration");
-test.beforeEach(() => testEnvironment.beforeEach());
-test.afterEach(() => testEnvironment.afterEach());
-test.after(() => testEnvironment.dispose());
+import { appendText, assertWithinBudget, call, context, makeExtension, manager, objectSchema, resultJson, resultRead, } from "./helpers/extension.js";
+import { installExtensionTestHooks } from "./helpers/extension-test-environment.js";
+const testEnvironment = installExtensionTestHooks("pi-context-integration");
 test("schemas cover the History/Notes actions plus reset controls", () => {
     const captured = makeExtension(manager());
     for (const name of [
@@ -94,7 +92,7 @@ test("paged tool outputs stay bounded and cursors reconstruct history and notes"
     }
     assert.equal(readParts.join(""), historyText);
     for (let index = 0; index < 100; index++) {
-        await call(captured, "notes_write", { path: `page-${"x".repeat(120)}-${index}.md`, content: Array.from({ length: 1000 }, (_, line) => `needle ${line} ${"z".repeat(30)}`).join("\n") }, ctx);
+        await call(captured, "notes_write", { address: `page-${"x".repeat(120)}-${index}.md`, content: Array.from({ length: 1000 }, (_, line) => `needle ${line} ${"z".repeat(30)}`).join("\n") }, ctx);
     }
     const listPages = [];
     let listOffset = 0;
@@ -102,7 +100,7 @@ test("paged tool outputs stay bounded and cursors reconstruct history and notes"
     while (listNext !== null) {
         const result = resultJson(await call(captured, "notes_list", { max_results: 300, cursor: listOffset }, ctx));
         assert.ok(Buffer.byteLength(JSON.stringify(result), "utf8") <= TOOL_OUTPUT_MAX_BYTES);
-        listPages.push(...result.files.map((file) => file.path));
+        listPages.push(...result.files.map((file) => file.address));
         listNext = result.next_cursor;
         if (listNext !== null)
             listOffset = listNext;
@@ -127,7 +125,7 @@ test("paged tool outputs stay bounded and cursors reconstruct history and notes"
     let noteOffset = 0;
     let noteNext = 0;
     while (noteNext !== null) {
-        const raw = await call(captured, "notes_read", { path: `page-${"x".repeat(120)}-0.md`, offset_chars: noteOffset }, ctx);
+        const raw = await call(captured, "notes_read", { address: `page-${"x".repeat(120)}-0.md`, offset_chars: noteOffset }, ctx);
         assertWithinBudget(raw, `notes_read page at ${noteOffset}`);
         const result = resultRead(raw);
         // The window is a plain prefix of the file, so the pages join by plain concatenation.
@@ -172,7 +170,7 @@ test("a page cap limits the page, not the enumerable set: cursors stay truthful
     assert.equal(searchTail.next_cursor, null);
     // notes_search: max_files caps the page, not the matched files.
     for (let index = 0; index < 7; index++)
-        await call(captured, "notes_write", { path: `needle-${index}.md`, content: "needle" }, ctx);
+        await call(captured, "notes_write", { address: `needle-${index}.md`, content: "needle" }, ctx);
     const notes = async (params) => resultJson(await call(captured, "notes_search", params, ctx));
     const notesFirst = await notes({ query: "needle", max_files: 3 });
     assert.equal(notesFirst.files.length, 3);
@@ -200,18 +198,18 @@ test("multi-query search: OR semantics, dedupe, and bare-string backward compati
     assert.deepEqual(await historyIds({ query: ["alpha"] }), [bothId, alphaId], "history: a one-element array searches that literal");
     assert.deepEqual(await historyIds({ query: "alpha" }), orIds.filter((id) => id !== betaId), "history: a bare string still behaves exactly as before");
     assert.deepEqual(await historyIds({ query: "alpha" }), await historyIds({ query: ["alpha"] }), "history: bare string equals the single-element list");
-    await call(captured, "notes_write", { path: "both.md", content: "alpha beta\nunrelated" }, ctx);
-    await call(captured, "notes_write", { path: "alpha.md", content: "alpha only" }, ctx);
-    await call(captured, "notes_write", { path: "beta.md", content: "beta only" }, ctx);
-    await call(captured, "notes_write", { path: "gamma.md", content: "gamma only" }, ctx);
+    await call(captured, "notes_write", { address: "both.md", content: "alpha beta\nunrelated" }, ctx);
+    await call(captured, "notes_write", { address: "alpha.md", content: "alpha only" }, ctx);
+    await call(captured, "notes_write", { address: "beta.md", content: "beta only" }, ctx);
+    await call(captured, "notes_write", { address: "gamma.md", content: "gamma only" }, ctx);
     const notesSearch = async (params) => resultJson(await call(captured, "notes_search", params, ctx)).files;
     const orFiles = await notesSearch({ query: ["alpha", "beta"] });
-    assert.deepEqual(orFiles.map((file) => file.path), ["alpha.md", "beta.md", "both.md"], "notes: a file matching any query is returned once, path-ordered");
-    assert.equal(orFiles.find((file) => file.path === "both.md")?.matches.length, 1, "notes: one line containing both queries is reported once");
-    assert.deepEqual((await notesSearch({ query: ["alpha"] })).map((file) => file.path), ["alpha.md", "both.md"], "notes: a one-element array searches that literal");
-    assert.deepEqual((await notesSearch({ query: "alpha" })).map((file) => file.path), ["alpha.md", "both.md"], "notes: a bare string still behaves exactly as before");
-    assert.deepEqual((await notesSearch({ query: "alpha" })).map((file) => file.path), (await notesSearch({ query: ["alpha"] })).map((file) => file.path), "notes: bare string equals the single-element list");
-    assert.deepEqual((await notesSearch({ query: ["gamma"] })).map((file) => file.path), ["gamma.md"]);
+    assert.deepEqual(orFiles.map((file) => file.address), ["alpha.md", "beta.md", "both.md"], "notes: a file matching any query is returned once, address-ordered");
+    assert.equal(orFiles.find((file) => file.address === "both.md")?.matches.length, 1, "notes: one line containing both queries is reported once");
+    assert.deepEqual((await notesSearch({ query: ["alpha"] })).map((file) => file.address), ["alpha.md", "both.md"], "notes: a one-element array searches that literal");
+    assert.deepEqual((await notesSearch({ query: "alpha" })).map((file) => file.address), ["alpha.md", "both.md"], "notes: a bare string still behaves exactly as before");
+    assert.deepEqual((await notesSearch({ query: "alpha" })).map((file) => file.address), (await notesSearch({ query: ["alpha"] })).map((file) => file.address), "notes: bare string equals the single-element list");
+    assert.deepEqual((await notesSearch({ query: ["gamma"] })).map((file) => file.address), ["gamma.md"]);
     // An empty array is an argument error, not a silently empty result set.
     await assert.rejects(() => call(captured, "history_search", { query: [] }, ctx), /non-empty array of strings/, "history: empty query array is refused");
     await assert.rejects(() => call(captured, "notes_search", { query: [] }, ctx), /non-empty array of strings/, "notes: empty query array is refused");

package/dist/test/notes-library.test.js

@@ -91,6 +91,23 @@ test("stores snapshot explicit identity and do not leak homes across instances",
     assert.equal((await notes.read("@agents/visitor/hello"))?.body, "visiting");
     await assert.rejects(() => notes.write("@agents/visitor/hello", "overwrite"), (error) => error instanceof NoteError && error.code === "invalid_scope");
 });
+test("list and search share scoped pattern scans and search offsets count Unicode code points", async (t) => {
+    const { notes } = fixture(t);
+    await notes.write("shared.md", "😀 needle in session");
+    await notes.write("@project/shared.md", "needle in project");
+    await notes.write("@human/shared.md", "needle in human");
+    await notes.write("@project/elsewhere.md", "unrelated");
+    const pattern = "**/shared.md";
+    const listed = await notes.list({ pattern });
+    const searched = await notes.search(["needle"], { pattern });
+    const listedAddresses = listed.map((row) => row.address).sort();
+    const searchedAddresses = searched.map((row) => row.address).sort();
+    assert.deepEqual(searchedAddresses, ["@human/shared.md", "@project/shared.md", "shared.md"]);
+    assert.deepEqual(searchedAddresses, listedAddresses, "list and search traverse the same filtered homes and files");
+    const sessionMatch = searched.find((row) => row.address === "shared.md").matches[0];
+    const serialized = (await notes.read("shared.md")).text;
+    assert.ok(Array.from(serialized).slice(sessionMatch.offsetChars).join("").startsWith("needle"), "the absolute offset counts the emoji as one code point");
+});
 test("invalid addressing and failed edits leave stored bytes untouched without poisoning the queue", async (t) => {
     const { home, context, notes } = fixture(t);
     assert.throws(() => createNotesStore({ ...context, sessionId: "../escape" }));

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

@@ -7,11 +7,9 @@ import { renderBootBlock } from "../src/context/prompts.js";
 import { localIso } from "../src/notes/frontmatter.js";
 import { listNotes, physicalPath, scopeDir } from "./helpers/notes.js";
 import { TOOL_OUTPUT_MAX_BYTES } from "../src/tool-output.js";
-import { assertWithinBudget, call, context, explicitBoot, installExtensionTestEnvironment, makeExtension, manager, resultJson, resultRead, } from "./helpers/extension.js";
-const testEnvironment = installExtensionTestEnvironment("pi-context-integration");
-test.beforeEach(() => testEnvironment.beforeEach());
-test.afterEach(() => testEnvironment.afterEach());
-test.after(() => testEnvironment.dispose());
+import { assertWithinBudget, call, context, explicitBoot, makeExtension, manager, resultJson, resultRead, } from "./helpers/extension.js";
+import { installExtensionTestHooks } from "./helpers/extension-test-environment.js";
+const testEnvironment = installExtensionTestHooks("pi-context-integration");
 test("notes_list is most-recently-updated first across merged scopes", async () => {
     const session = manager();
     const captured = makeExtension(session);
@@ -37,47 +35,47 @@ test("notes are real files that persist across sessions and round-trip Unicode",
     const original = manager();
     const captured = makeExtension(original);
     const ctx = context(original);
-    await call(captured, "notes_write", { path: "checkpoint/进度.md", content: "第一行\nneedle Café", scope: "human" }, ctx);
+    await call(captured, "notes_write", { address: "@human/checkpoint/进度.md", content: "第一行\nneedle Café" }, ctx);
     // A brand-new session over the same physical root sees the human note: nothing is replayed
     // from session entries, the file itself is the durable artifact.
     const restored = manager();
     const restoredCaptured = makeExtension(restored);
     const restoredCtx = context(restored);
-    const rawRead = await call(restoredCaptured, "notes_read", { path: "checkpoint/进度.md", scope: "human", offset_chars: -4 }, restoredCtx);
+    const rawRead = await call(restoredCaptured, "notes_read", { address: "@human/checkpoint/进度.md", offset_chars: -4 }, restoredCtx);
     const read = resultRead(rawRead);
     assert.equal(read.details.address, "@human/checkpoint/进度.md");
     assert.equal(read.content, "Café", "a negative offset reads the body tail in one call");
-    const searched = resultJson(await call(restoredCaptured, "notes_search", { query: "Café", scope: "human" }, restoredCtx));
+    const searched = resultJson(await call(restoredCaptured, "notes_search", { pattern: "@human/**", query: "Café" }, restoredCtx));
     assert.equal(searched.files[0]?.matches[0]?.line, 2);
-    const listedFiles = resultJson(await call(restoredCaptured, "notes_list", { pattern: "checkpoint/**", scope: "human" }, restoredCtx));
+    const listedFiles = resultJson(await call(restoredCaptured, "notes_list", { pattern: "@human/checkpoint/**" }, restoredCtx));
     assert.equal(listedFiles.files.length, 1, "glob ** crosses into the checkpoint directory");
-    assert.equal(listedFiles.files[0]?.path, "checkpoint/进度.md");
+    assert.equal(listedFiles.files[0]?.address, "@human/checkpoint/进度.md");
     // A single-segment * never crosses `/`, so a nested-only store matches nothing at the root.
-    const rootOnly = resultJson(await call(restoredCaptured, "notes_list", { pattern: "*", scope: "human" }, restoredCtx));
+    const rootOnly = resultJson(await call(restoredCaptured, "notes_list", { pattern: "@human/*" }, restoredCtx));
     assert.equal(rootOnly.files.length, 0, "glob * stays within one segment");
     assert.equal(searched.files[0]?.updated_at, listedFiles.files[0]?.updated_at);
-    await assert.rejects(() => call(captured, "notes_write", { path: "../escape", content: "x" }, ctx), /unsupported component/);
+    await assert.rejects(() => call(captured, "notes_write", { address: "../escape", content: "x" }, ctx), /unsupported component/);
 });
 test("stale lifecycle: writes and metadata-only edits close and revive a note", async () => {
     const sm = manager();
     const captured = makeExtension(sm);
     const ctx = context(sm);
-    await call(captured, "notes_write", { path: "journal.md", content: "log line" }, ctx);
+    await call(captured, "notes_write", { address: "journal.md", content: "log line" }, ctx);
     // metadata-only: content unchanged, flag set, applied 0
-    const markOnly = resultJson(await call(captured, "notes_edit", { path: "journal.md", stale: true }, ctx));
+    const markOnly = resultJson(await call(captured, "notes_edit", { address: "journal.md", stale: true }, ctx));
     assert.equal(markOnly.applied, 0);
     assert.equal((await 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");
+    assert.equal(resultRead(await call(captured, "notes_read", { address: "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));
+    const revived = resultJson(await call(captured, "notes_edit", { address: "journal.md", stale: false }, ctx));
     assert.equal((await 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);
+    await call(captured, "notes_write", { address: "journal.md", content: "final", stale: true }, ctx);
     assert.equal((await listNotes(ctx, { scope: "session" }))[0]?.meta.stale, true);
-    await call(captured, "notes_write", { path: "journal.md", content: "reopened" }, ctx);
+    await call(captured, "notes_write", { address: "journal.md", content: "reopened" }, ctx);
     assert.equal((await listNotes(ctx, { scope: "session" }))[0]?.meta.stale, false, "writing without stale revives");
     // metadata-only on a missing path is the typed not-found arm
-    const missing = resultJson(await call(captured, "notes_edit", { path: "missing.md", stale: true }, ctx));
+    const missing = resultJson(await call(captured, "notes_edit", { address: "missing.md", stale: true }, ctx));
     assert.equal(missing.error, "note not found");
 });
 test("the filesystem notes loader treats an absent home as empty but surfaces a real directory read failure", async () => {
@@ -181,8 +179,8 @@ test("an over-budget note is delivered as a prefix and resumed by next_offset_ch
     const ctx = context(session);
     const huge = `H${"x".repeat(TOOL_OUTPUT_MAX_BYTES * 2)}`;
     const text = `${huge}\ntail line`;
-    await call(captured, "notes_write", { path: "huge.md", content: text }, ctx);
-    const rawFirst = await call(captured, "notes_read", { path: "huge.md" }, ctx);
+    await call(captured, "notes_write", { address: "huge.md", content: text }, ctx);
+    const rawFirst = await call(captured, "notes_read", { address: "huge.md" }, ctx);
     assertWithinBudget(rawFirst, "single oversized note");
     const first = resultRead(rawFirst);
     assert.ok(first.content.length > 0, "the page is not empty");
@@ -196,7 +194,7 @@ test("an over-budget note is delivered as a prefix and resumed by next_offset_ch
     const parts = [first.content];
     let offset = first.next_offset_chars;
     while (offset !== null) {
-        const rawChunk = await call(captured, "notes_read", { path: "huge.md", offset_chars: offset }, ctx);
+        const rawChunk = await call(captured, "notes_read", { address: "huge.md", offset_chars: offset }, ctx);
         assertWithinBudget(rawChunk, `huge note chunk at ${offset}`);
         const chunk = resultRead(rawChunk);
         assert.equal(chunk.offset_chars, offset, "the response echoes the resolved absolute offset");
@@ -205,7 +203,7 @@ test("an over-budget note is delivered as a prefix and resumed by next_offset_ch
     }
     assert.ok(parts.join("").endsWith(text), "the cursors reconstruct the body exactly");
     // A success carries structured details; an error stays a JSON envelope with no details.
-    const missingResult = await call(captured, "notes_read", { path: "no-such.md" }, ctx);
+    const missingResult = await call(captured, "notes_read", { address: "no-such.md" }, ctx);
     const missing = resultJson(missingResult);
     assert.deepEqual(Object.keys(missing).sort(), ["address", "error"], "the read error carries exactly error and address");
     assert.equal(missing.error, "note not found");
@@ -217,8 +215,8 @@ test("an over-budget note search match is a named prefix with an honest line add
     const ctx = context(session);
     // The query sits behind a prefix, so its address is a real body-absolute offset, not line 1.
     const hugeLine = `${'p'.repeat(500)}needle ${"y".repeat(TOOL_OUTPUT_MAX_BYTES * 2)}`;
-    await call(captured, "notes_write", { path: "a.md", content: "needle small" }, ctx);
-    await call(captured, "notes_write", { path: "search.md", content: hugeLine }, ctx);
+    await call(captured, "notes_write", { address: "a.md", content: "needle small" }, ctx);
+    await call(captured, "notes_write", { address: "search.md", content: hugeLine }, ctx);
     const pages = [];
     let cursor = 0;
     let next = 0;
@@ -230,7 +228,7 @@ test("an over-budget note search match is a named prefix with an honest line add
         if (next !== null)
             cursor = next;
     }
-    assert.deepEqual(pages.map((file) => file.path), ["a.md", "search.md"], "pagination reaches the oversized file instead of looping");
+    assert.deepEqual(pages.map((file) => file.address), ["a.md", "search.md"], "pagination reaches the oversized file instead of looping");
     const oversized = pages[1];
     assert.equal(oversized.matches_total, 1, "the file's full match count is named even though the line was cut");
     assert.equal(oversized.matches.length, 1);
@@ -239,13 +237,13 @@ test("an over-budget note search match is a named prefix with an honest line add
     assert.ok(hugeLine.startsWith(match.text), "the match text is a plain prefix of the line");
     assert.equal(match.text.includes("…"), false, "no marker is appended to the match text");
     assert.equal(match.line, 1, "the informational line number survives");
-    const atMatch = resultRead(await call(captured, "notes_read", { path: "search.md", offset_chars: match.offset_chars }, ctx));
+    const atMatch = resultRead(await call(captured, "notes_read", { address: "search.md", offset_chars: match.offset_chars }, ctx));
     assert.ok(atMatch.content.startsWith("needle"), "the search offset starts a read at the matched substring");
     // The body is reconstructible by following notes_read's cursor from the start of the file.
     const parts = [];
     let offset = 0;
     while (offset !== null) {
-        const rawChunk = await call(captured, "notes_read", { path: "search.md", offset_chars: offset }, ctx);
+        const rawChunk = await call(captured, "notes_read", { address: "search.md", offset_chars: offset }, ctx);
         assertWithinBudget(rawChunk, `search.md chunk at ${offset}`);
         const chunk = resultRead(rawChunk);
         assert.equal(chunk.offset_chars, offset, "the read echoes the resolved address");
@@ -258,10 +256,10 @@ test("notes_search scopes by glob pattern; a non-matching pattern is an empty pa
     const session = manager();
     const captured = makeExtension(session);
     const ctx = context(session);
-    await call(captured, "notes_write", { path: "deep/nested/a.md", content: "needle here" }, ctx);
-    await call(captured, "notes_write", { path: "top.md", content: "needle there" }, ctx);
+    await call(captured, "notes_write", { address: "deep/nested/a.md", content: "needle here" }, ctx);
+    await call(captured, "notes_write", { address: "top.md", content: "needle there" }, ctx);
     const scoped = resultJson(await call(captured, "notes_search", { query: "needle", pattern: "deep/**" }, ctx));
-    assert.deepEqual(scoped.files.map((file) => file.path), ["deep/nested/a.md"], "a glob scopes the search to the subtree");
+    assert.deepEqual(scoped.files.map((file) => file.address), ["deep/nested/a.md"], "a glob scopes the search to the subtree");
     const none = resultJson(await call(captured, "notes_search", { query: "needle", pattern: "absent/**" }, ctx));
     assert.equal(none.error, undefined, "a non-matching pattern is not an error");
     assert.deepEqual(none.files, [], "a non-matching pattern is an empty page");