@astrosheep/pi-context 0.26.0 → 0.26.2

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 () => {
@@ -135,6 +133,24 @@ test("boot note acquisition is one closed snapshot and isolates one or all faile
     assert.ok(rendered.includes("PROJECT_MAP_BODY") && rendered.includes("AGENT_MAP_BODY"), "MAP residency comes from the snapshot");
     assert.ok(rendered.includes("session.md") && rendered.includes("@human/human.md"), "pocket rows come from the same snapshot");
     assert.equal(rendered.includes("SESSION_POCKET_BODY"), false, "pocket bodies stay excluded");
+    assert.match(rendered, /- session\.md  ·  19 chars  ·  \d+s ago/);
+    assert.equal(rendered.includes("UTF-8 bytes"), false, "pocket rows omit implementation-oriented byte counts");
+    const expanded = await loadNotesSnapshot(ctx, (_ctx, scope) => {
+        if (scope === "project" || scope === "human" || scope === "agent" || scope === "model") {
+            return Array.from({ length: 6 }, (_, i) => note(scope, `note-${i}.md`, `@${scope === "agent" ? "agents/root" : scope === "model" ? "models/default" : scope}/note-${i}.md`, `body ${i}`));
+        }
+        return rows.get(scope) ?? [];
+    });
+    const expandedText = renderBootBlock({ ...renderData, notes: expanded });
+    for (const prefix of ["@project", "@human", "@agents/root"]) {
+        for (let i = 0; i < 5; i++)
+            assert.ok(expandedText.includes(`- ${prefix}/note-${i}.md  ·  `), `${prefix} includes note ${i}`);
+        assert.equal(expandedText.includes(`- ${prefix}/note-5.md  ·  `), false, `${prefix} is capped at five`);
+    }
+    for (let i = 0; i < 3; i++)
+        assert.ok(expandedText.includes(`- @models/default/note-${i}.md  ·  `), `@model includes note ${i}`);
+    assert.equal(expandedText.includes("- @models/default/note-3.md  ·  "), false, "@model is capped at three");
+    assert.match(expandedText, /5 from @project, 5 from @human, 5 from @self, 3 from @model/);
     const readFailure = (code) => Object.assign(new Error("scripted read failure"), { code });
     const oneFailed = await loadNotesSnapshot(ctx, (_ctx, scope) => {
         if (scope === "human")
@@ -181,8 +197,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 +212,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 +221,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 +233,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 +246,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 +255,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 +274,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");

package/dist/test/notes.test.js

@@ -14,11 +14,9 @@ import test from "node:test";
 import { parseNote } from "../src/notes/frontmatter.js";
 import { projectKey } from "../src/notes/paths.js";
 import { listNotes, physicalPath, scopeDir } from "./helpers/notes.js";
-import { call, context, explicitBoot, installExtensionTestEnvironment, makeExtension, manager, resultJson, resultRead } from "./helpers/extension.js";
-const testEnvironment = installExtensionTestEnvironment("pi-context-notes");
-test.beforeEach(() => testEnvironment.beforeEach());
-test.afterEach(() => testEnvironment.afterEach());
-test.after(() => testEnvironment.dispose());
+import { call, context, explicitBoot, makeExtension, manager, resultJson, resultRead } from "./helpers/extension.js";
+import { installExtensionTestHooks } from "./helpers/extension-test-environment.js";
+const testEnvironment = installExtensionTestHooks("pi-context-notes");
 function freshRoot() {
     return testEnvironment.newNotesRoot();
 }
@@ -59,7 +57,7 @@ test("write lands a real markdown file with harness frontmatter and a pure body"
     const captured = makeExtension(session);
     const ctx = context(session);
     const sessionId = session.getSessionId();
-    const result = resultJson(await call(captured, "notes_write", { path: "a/b.md", content: "hello" }, ctx));
+    const result = resultJson(await call(captured, "notes_write", { address: "a/b.md", content: "hello" }, ctx));
     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"));
@@ -79,7 +77,7 @@ test("write lands a real markdown file with harness frontmatter and a pure body"
     assert.equal(result.written, true);
     assert.equal(existsSync(join(scopeDir("session", ctx), ".session.json")), false, "ownership is stored in note frontmatter, not a sidecar");
     // A leading YAML block in user content is stripped from the body.
-    await call(captured, "notes_write", { path: "stripped.md", content: "---\nscope: human\nnonsense: true\n---\nreal body" }, ctx);
+    await call(captured, "notes_write", { address: "stripped.md", content: "---\nscope: human\nnonsense: true\n---\nreal body" }, ctx);
     const stripped = readFileSync(physicalPath("session", "stripped.md", ctx), "utf8");
     assert.match(stripped, /\n---\n\nreal body$/, "the injected block is not part of the body");
     assert.equal(stripped.includes("nonsense"), false, "the injected block never reaches the file");
@@ -96,33 +94,33 @@ test("session-note project ownership is per note, persistent across sessions, an
     const firstSession = manager();
     const firstCaptured = makeExtension(firstSession);
     const firstCtx = context(firstSession, undefined, undefined, true, cwdA);
-    await call(firstCaptured, "notes_write", { path: "first.md", content: "first project session" }, firstCtx);
+    await call(firstCaptured, "notes_write", { address: "first.md", content: "first project session" }, firstCtx);
     const firstFile = physicalPath("session", "first.md", firstCtx);
     assert.equal(parseNote(readFileSync(firstFile, "utf8")).meta.project, projectA);
     const secondSession = manager();
     const secondCaptured = makeExtension(secondSession);
     const secondCtx = context(secondSession, undefined, undefined, true, cwdA);
-    await call(secondCaptured, "notes_write", { path: "second.md", content: "same project, another session" }, secondCtx);
+    await call(secondCaptured, "notes_write", { address: "second.md", content: "same project, another session" }, secondCtx);
     const secondFile = physicalPath("session", "second.md", secondCtx);
     assert.equal(parseNote(readFileSync(secondFile, "utf8")).meta.project, projectA, "another session in the same project carries the matching key");
     const thirdSession = manager();
     const thirdCaptured = makeExtension(thirdSession);
     const thirdCtx = context(thirdSession, undefined, undefined, true, cwdB);
-    await call(thirdCaptured, "notes_write", { path: "third.md", content: "different project" }, thirdCtx);
+    await call(thirdCaptured, "notes_write", { address: "third.md", content: "different project" }, thirdCtx);
     const thirdFile = physicalPath("session", "third.md", thirdCtx);
     assert.equal(parseNote(readFileSync(thirdFile, "utf8")).meta.project, projectB);
     const projectASessions = [firstFile, secondFile, thirdFile].filter((file) => parseNote(readFileSync(file, "utf8")).meta.project === projectA);
     assert.deepEqual(projectASessions.sort(), [firstFile, secondFile].sort(), "exact frontmatter project matching recognizes only sessions from the same project");
     const movedContext = context(firstSession, undefined, undefined, true, cwdB);
-    await call(firstCaptured, "notes_write", { path: "first.md", content: "overwritten from another cwd" }, movedContext);
+    await call(firstCaptured, "notes_write", { address: "first.md", content: "overwritten from another cwd" }, movedContext);
     assert.equal(parseNote(readFileSync(firstFile, "utf8")).meta.project, projectA, "overwriting an existing note does not silently reassign it");
-    await call(firstCaptured, "notes_edit", { path: "first.md", edits: [{ oldText: "overwritten", newText: "edited" }] }, movedContext);
+    await call(firstCaptured, "notes_edit", { address: "first.md", edits: [{ oldText: "overwritten", newText: "edited" }] }, movedContext);
     assert.equal(parseNote(readFileSync(firstFile, "utf8")).meta.project, projectA, "editing an existing note preserves its original project key");
-    await call(firstCaptured, "notes_read", { path: "first.md" }, movedContext);
+    await call(firstCaptured, "notes_read", { address: "first.md" }, movedContext);
     assert.equal(parseNote(readFileSync(firstFile, "utf8")).meta.project, projectA, "reading preserves existing project ownership");
-    await call(firstCaptured, "notes_write", { path: "new-from-project-b.md", content: "new note", scope: "session" }, movedContext);
+    await call(firstCaptured, "notes_write", { address: "new-from-project-b.md", content: "new note" }, movedContext);
     assert.equal(parseNote(readFileSync(physicalPath("session", "new-from-project-b.md", movedContext), "utf8")).meta.project, projectB, "only a newly-created session note uses the current project key");
-    await call(firstCaptured, "notes_write", { path: "project-note.md", content: "project home note", scope: "project" }, movedContext);
+    await call(firstCaptured, "notes_write", { address: "@project/project-note.md", content: "project home note" }, movedContext);
     assert.equal(parseNote(readFileSync(physicalPath("project", "project-note.md", movedContext), "utf8")).meta.project, undefined, "project-home notes do not receive session ownership metadata");
     assert.equal((await listNotes(movedContext, { scope: "session" })).length, 2, "project ownership remains frontmatter, not a separate note");
 });
@@ -144,7 +142,7 @@ test("linked git worktrees share the main checkout's project key", () => {
     assert.equal(projectKey(join(worktree, "gone", "deeper")), projectKey(main), "a nonexistent subdirectory still resolves through its worktree");
     assert.equal(scopeDir("project", context(manager(), undefined, undefined, true, worktree)), scopeDir("project", context(manager(), undefined, undefined, true, main)), "@project uses the same physical home from both checkouts");
 });
-test("legacy metadata is refused for explicit manual migration; invalid project ownership stays unknown", async () => {
+test("unrecognized metadata remains ordinary frontmatter; invalid project ownership stays unknown", async () => {
     freshRoot();
     const session = manager();
     const captured = makeExtension(session);
@@ -159,15 +157,24 @@ created_at: 2026-01-01T00:00:00.000+00:00
 updated_at: 2026-01-01T00:00:00.000+00:00
 last_accessed: 2026-01-01T00:00:00.000+00:00
 access_count: 0
+source_window: old-window
+recurrence_count: 2
+recurrence_windows: old-window
 ---
 
 legacy body`);
-    assert.throws(() => parseNote(readFileSync(legacyFile, "utf8")), /legacy note metadata .*requires manual migration/);
-    const legacyBytes = readFileSync(legacyFile, "utf8");
-    await assert.rejects(() => listNotes(ctx, { scope: "session" }), /requires manual migration/);
-    await assert.rejects(() => call(captured, "notes_read", { path: "legacy.md" }, ctx), /requires manual migration/);
-    await assert.rejects(() => call(captured, "notes_write", { path: "legacy.md", content: "legacy overwritten" }, ctx), /requires manual migration/);
-    assert.equal(readFileSync(legacyFile, "utf8"), legacyBytes, "refusal preserves the unmigrated file byte-for-byte");
+    const parsed = parseNote(readFileSync(legacyFile, "utf8"), Date.parse("2026-02-01T00:00:00Z"));
+    assert.equal(parsed.meta.createdAt, Date.parse("2026-02-01T00:00:00Z"), "missing canonical timestamp takes the normal default");
+    assert.equal(parsed.meta.created_at, "2026-01-01T00:00:00.000+00:00", "unrecognized fields remain ordinary extras");
+    assert.equal((await listNotes(ctx, { scope: "session" }))[0]?.address, "legacy.md");
+    assert.match(resultRead(await call(captured, "notes_read", { address: "legacy.md" }, ctx)).content, /legacy body$/);
+    await call(captured, "notes_edit", { address: "legacy.md", edits: [{ oldText: "legacy body", newText: "edited body" }] }, ctx);
+    await call(captured, "notes_write", { address: "legacy.md", content: "overwritten body" }, ctx);
+    const rewritten = parseNote(readFileSync(legacyFile, "utf8"));
+    assert.equal(rewritten.body, "overwritten body");
+    for (const key of ["created_at", "updated_at", "last_accessed", "access_count", "source_window", "recurrence_count", "recurrence_windows"]) {
+        assert.deepEqual(rewritten.meta[key], parsed.meta[key], `${key} is preserved as unrecognized frontmatter, not migrated`);
+    }
     const invalidFile = physicalPath("session", "invalid.md", ctx);
     writeFileSync(invalidFile, `---
 origin: self
@@ -183,7 +190,7 @@ project: 17
 invalid owner`);
     assert.equal(parseNote(readFileSync(invalidFile, "utf8")).meta.project, 17);
     assert.notEqual(parseNote(readFileSync(invalidFile, "utf8")).meta.project, projectKey(ctx.cwd), "invalid ownership does not match the current project key");
-    await call(captured, "notes_write", { path: "invalid.md", content: "still invalid" }, ctx);
+    await call(captured, "notes_write", { address: "invalid.md", content: "still invalid" }, ctx);
     assert.equal(parseNote(readFileSync(invalidFile, "utf8")).meta.project, 17, "an invalid value remains unknown and is not replaced with cwd-derived ownership");
     assert.equal(existsSync(join(scopeDir("session", ctx), ".session.json")), false, "new notes use no ownership sidecar");
 });
@@ -192,19 +199,19 @@ test("edit is body-scoped with named failures and a replace_all escape hatch", a
     const session = manager();
     const captured = makeExtension(session);
     const ctx = context(session);
-    await call(captured, "notes_write", { path: "edit.md", content: "alpha\nbeta\nbeta\ngamma" }, ctx);
-    const ambiguous = resultJson(await call(captured, "notes_edit", { path: "edit.md", edits: [{ oldText: "beta", newText: "B" }] }, ctx));
+    await call(captured, "notes_write", { address: "edit.md", content: "alpha\nbeta\nbeta\ngamma" }, ctx);
+    const ambiguous = resultJson(await call(captured, "notes_edit", { address: "edit.md", edits: [{ oldText: "beta", newText: "B" }] }, ctx));
     assert.match(ambiguous.error, /occurs 2 times/);
     assert.deepEqual(ambiguous.line_numbers, [2, 3], "the multi-match error carries every match line number");
-    const missing = resultJson(await call(captured, "notes_edit", { path: "edit.md", edits: [{ oldText: "absent", newText: "x" }] }, ctx));
+    const missing = resultJson(await call(captured, "notes_edit", { address: "edit.md", edits: [{ oldText: "absent", newText: "x" }] }, ctx));
     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));
+    const all = resultJson(await call(captured, "notes_edit", { address: "edit.md", edits: [{ oldText: "beta", newText: "B" }], replace_all: true }, ctx));
     assert.equal(all.applied, 1);
     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");
+    assert.equal(resultRead(await call(captured, "notes_read", { address: "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));
+    const frontmatterOnly = resultJson(await call(captured, "notes_edit", { address: "edit.md", edits: [{ oldText: "scope", newText: "x" }] }, ctx));
     assert.equal(frontmatterOnly.edit_index, 0, "a frontmatter-only anchor is not a body match");
 });
 test("nothing-to-do, not-found, atomic batches, and replace_all zero-match are named", async () => {
@@ -212,25 +219,25 @@ test("nothing-to-do, not-found, atomic batches, and replace_all zero-match are n
     const session = manager();
     const captured = makeExtension(session);
     const ctx = context(session);
-    const nameOnly = resultJson(await call(captured, "notes_edit", { path: "edit.md" }, ctx));
+    const nameOnly = resultJson(await call(captured, "notes_edit", { address: "edit.md" }, ctx));
     assert.match(nameOnly.error, /nothing to do/, "neither edits nor setters is a named error");
-    await call(captured, "notes_write", { path: "edit.md", content: "alpha\nbeta" }, ctx);
-    const empty = resultJson(await call(captured, "notes_edit", { path: "edit.md", edits: [] }, ctx));
+    await call(captured, "notes_write", { address: "edit.md", content: "alpha\nbeta" }, ctx);
+    const empty = resultJson(await call(captured, "notes_edit", { address: "edit.md", edits: [] }, ctx));
     assert.match(empty.error, /nothing to do/, "an empty edits list with no setters is also nothing to do");
-    const editMissing = resultJson(await call(captured, "notes_edit", { path: "missing.md", stale: true }, ctx));
+    const editMissing = resultJson(await call(captured, "notes_edit", { address: "missing.md", stale: true }, ctx));
     assert.equal(editMissing.error, "note not found");
-    const readMissing = resultJson(await call(captured, "notes_read", { path: "missing.md" }, ctx));
+    const readMissing = resultJson(await call(captured, "notes_read", { address: "missing.md" }, ctx));
     assert.equal(readMissing.error, "note not found");
-    assert.equal(readMissing.path, "missing.md");
+    assert.equal(readMissing.address, "missing.md");
     const file = physicalPath("session", "edit.md", ctx);
     const before = readFileSync(file, "utf8");
-    const failed = resultJson(await call(captured, "notes_edit", { path: "edit.md", edits: [{ oldText: "alpha", newText: "A" }, { oldText: "absent", newText: "x" }] }, ctx));
+    const failed = resultJson(await call(captured, "notes_edit", { address: "edit.md", edits: [{ oldText: "alpha", newText: "A" }, { oldText: "absent", newText: "x" }] }, ctx));
     assert.equal(failed.edit_index, 1, "the failing edit is named");
     assert.equal(readFileSync(file, "utf8"), before, "a failing batch leaves the file byte-identical, frontmatter included");
-    const applied = resultJson(await call(captured, "notes_edit", { path: "edit.md", edits: [{ oldText: "alpha", newText: "A" }, { oldText: "beta", newText: "B" }] }, ctx));
+    const applied = resultJson(await call(captured, "notes_edit", { address: "edit.md", edits: [{ oldText: "alpha", newText: "A" }, { oldText: "beta", newText: "B" }] }, ctx));
     assert.equal(applied.applied, 2);
-    assert.equal(resultRead(await call(captured, "notes_read", { path: "edit.md" }, ctx)).content.endsWith("A\nB"), true);
-    const zero = resultJson(await call(captured, "notes_edit", { path: "edit.md", edits: [{ oldText: "zzz", newText: "y" }], replace_all: true }, ctx));
+    assert.equal(resultRead(await call(captured, "notes_read", { address: "edit.md" }, ctx)).content.endsWith("A\nB"), true);
+    const zero = resultJson(await call(captured, "notes_edit", { address: "edit.md", edits: [{ oldText: "zzz", newText: "y" }], replace_all: true }, ctx));
     assert.equal(zero.edit_index, 0, "replace_all with zero matches is the same zero-match error, not a silent no-op");
 });
 test("all notes tool results use address as the only home identity", async () => {
@@ -270,16 +277,16 @@ test("list and search merge scopes and carry addresses; the path jail rejects es
     const session = manager();
     const captured = makeExtension(session);
     const ctx = context(session);
-    await call(captured, "notes_write", { path: "one.md", content: "needle one", scope: "session" }, ctx);
-    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: "human" }, ctx);
+    await call(captured, "notes_write", { address: "one.md", content: "needle one" }, ctx);
+    await call(captured, "notes_write", { address: "@project/two.md", content: "needle two" }, ctx);
+    await call(captured, "notes_write", { address: "@human/three.md", content: "needle three" }, ctx);
     const listed = resultJson(await call(captured, "notes_list", {}, ctx));
     assert.deepEqual([...listed.files].map((file) => file.address).sort(), ["@human/three.md", "@project/two.md", "one.md"], "every merged row carries its full address");
     for (const row of listed.files) {
         assert.deepEqual(Object.keys(row).sort(), ["address", "stale", "updated_at"]);
         assert.equal(row.stale, false);
     }
-    const scoped = resultJson(await call(captured, "notes_list", { scope: "human" }, ctx));
+    const scoped = resultJson(await call(captured, "notes_list", { pattern: "@human/**" }, ctx));
     assert.deepEqual(scoped.files.map((file) => file.address), ["@human/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");
@@ -295,7 +302,7 @@ test("list and search merge scopes and carry addresses; the path jail rejects es
     const escaped = ["../evil", "/abs", "a\\b"];
     for (const tool of ["notes_write", "notes_edit", "notes_read"]) {
         for (const path of escaped) {
-            await assert.rejects(() => call(captured, tool, { path, content: "x", edits: [{ oldText: "a", newText: "b" }] }, ctx), `${tool} rejects ${path}`);
+            await assert.rejects(() => call(captured, tool, { address: path, content: "x", edits: [{ oldText: "a", newText: "b" }] }, ctx), `${tool} rejects ${path}`);
         }
     }
     await assert.rejects(() => call(captured, "notes_list", { pattern: "bad\\glob" }, ctx), /backslash/);

package/docs/architecture.md

@@ -43,7 +43,7 @@ Boot is a fixed snapshot for its window, stored as an extension custom message a
 
 History reads reconstruct the selected session branch on demand without a cache, so branch navigation cannot expose history from a sibling.
 
-The boot notes index in `pi/notes/snapshot.ts` is a closed snapshot: the current session, project, human, agent, and model homes are each loaded at most once while constructing a boot. `context/prompts.ts` then renders that explicit snapshot without reading the filesystem or consulting the clock. MAP bodies and pocket metadata are derived from the same snapshot, so a boot cannot mix two filesystem reads. Note storage and home traversal use `node:fs/promises`; same-file operations queue by absolute physical filename across store instances in this process, without promising symlink/case-alias or cross-process locking. Known persisted metadata is camelCase, and a known legacy snake_case key refuses use until the root-coordinated manual migration; startup does not migrate notes. A missing home (`ENOENT`) is normal. A real read failure omits only that home's index, preserves healthy homes, adds a model-facing `notes_list` recovery notice, and notifies the human once for that window. Boot/reset construction captures session, agent, and model identity before awaiting the snapshot, then checks lifecycle generation, active window, enabled state, and abort status before sending or returning artifacts; stale completions cannot commit into a switched or shut-down session. Note reads never mutate files or create fallback state.
+The boot notes index in `pi/notes/snapshot.ts` is a closed snapshot: the current session, project, human, agent, and model homes are each loaded at most once while constructing a boot. `context/prompts.ts` then renders that explicit snapshot without reading the filesystem or consulting the clock. MAP bodies and pocket metadata are derived from the same snapshot, so a boot cannot mix two filesystem reads. Note storage and home traversal use `node:fs/promises`; same-file operations queue by absolute physical filename across store instances in this process, without promising symlink/case-alias or cross-process locking. Known persisted metadata is camelCase. Old snake_case keys are unrecognized extras, not interpreted or migrated; startup does not migrate notes. A missing home (`ENOENT`) is normal. A real read failure omits only that home's index, preserves healthy homes, adds a model-facing `notes_list` recovery notice, and notifies the human once for that window. Boot/reset construction captures session, agent, and model identity before awaiting the snapshot, then checks lifecycle generation, active window, enabled state, and abort status before sending or returning artifacts; stale completions cannot commit into a switched or shut-down session. Note reads never mutate files or create fallback state.
 
 `notes/session-replay.ts` accepts only supported operations, safe virtual paths, representable timestamps and results within the UTF-8 size limit. Invalid operations are ignored; they cannot replace a valid note. Notes remain in their filesystem-backed homes, unchanged by session branch navigation.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/pi-context",
-  "version": "0.26.0",
+  "version": "0.26.2",
   "type": "module",
   "main": "./dist/src/index.js",
   "types": "./dist/src/index.d.ts",

package/src/context/budget.ts

@@ -2,7 +2,7 @@ import { Type } from "@earendil-works/pi-ai";
 import { defineTool, type ExtensionAPI, type ExtensionContext, type SessionBoundaryDraft, type SettingsManager } from "@earendil-works/pi-coding-agent";
 import { GUIDANCE_TYPE, WARNING_CONTENT, WARNING_TYPE } from "../protocol.js";
 import { readThresholdSettings, type ResolvedThresholds, type ThresholdSettingsResolution } from "./thresholds.js";
-import { currentWindowId, hasWindowMessage, windowUsage } from "./context-window.js";
+import { currentWindowId, hasWindowMessage, isWindowMarker, rootWindowId, windowUsage } from "./context-window.js";
 import { tokenBudgetGuidance } from "./prompts.js";
 import { output } from "../tool-output.js";
 
@@ -45,16 +45,30 @@ export function registerBudget(
 	const invalidateThresholds = () => { cachedPolicy = undefined; };
 	let pendingGuidance: { windowId: string; content: string; remaining: number } | undefined;
 	let pendingWarning: { windowId: string; content: string; remaining: number } | undefined;
-	let pendingNotices: Array<{ windowId: string; customType: string; remaining: number }> = [];
-	const notifyCommittedReminders = (ctx: ExtensionContext) => {
-		const windowId = currentWindowId(ctx);
-		for (const notice of pendingNotices) {
-			if (notice.windowId !== windowId || !hasWindowMessage(ctx, notice.customType)) continue;
-			ctx.ui.notify(notice.customType === WARNING_TYPE
-				? "pi-context: Context almost full; close out the current memory window."
-				: "pi-context: Context running low; checkpoint your notes soon.", "warning");
+	let pendingNotices = new Map<string, { sessionId: string; windowId: string }>();
+	const noticeKey = (sessionId: string, windowId: string) => `${sessionId}:${windowId}`;
+	const warningCommittedInWindow = (ctx: ExtensionContext, notice: { sessionId: string; windowId: string }): boolean => {
+		if (ctx.sessionManager.getSessionId() !== notice.sessionId) return false;
+		let windowId = rootWindowId(notice.sessionId);
+		for (const entry of ctx.sessionManager.getBranch()) {
+			if (isWindowMarker(entry)) {
+				windowId = entry.data.windowId;
+				continue;
+			}
+			if (windowId === notice.windowId && entry.type === "custom_message" && entry.customType === WARNING_TYPE) return true;
+		}
+		return false;
+	};
+	const notifyCommittedWarnings = (ctx: ExtensionContext, settled = false) => {
+		for (const [key, notice] of pendingNotices) {
+			if (warningCommittedInWindow(ctx, notice)) {
+				pendingNotices.delete(key);
+				ctx.ui.notify("pi-context: Context almost full; close out the current memory window.", "warning");
+			} else if (settled) {
+				// An uncommitted draft must not be matched to a later manual warning.
+				pendingNotices.delete(key);
+			}
 		}
-		pendingNotices = [];
 	};
 
 	const clearStaged = () => {
@@ -63,7 +77,7 @@ export function registerBudget(
 	};
 	const resetForTransition = () => {
 		clearStaged();
-		pendingNotices = [];
+		pendingNotices.clear();
 		invalidateThresholds();
 		notifiedWarnings.clear();
 	};
@@ -76,7 +90,10 @@ export function registerBudget(
 		clearStaged();
 		const windowId = currentWindowId(ctx);
 		const drafts = staged.filter((draft): draft is NonNullable<typeof draft> => draft !== undefined && draft.windowId === windowId);
-		pendingNotices = drafts.map(({ windowId, customType, remaining }) => ({ windowId, customType, remaining }));
+		if (drafts.some((draft) => draft.customType === WARNING_TYPE)) {
+			const sessionId = ctx.sessionManager.getSessionId();
+			pendingNotices.set(noticeKey(sessionId, windowId), { sessionId, windowId });
+		}
 		return drafts.map((draft) => ({
 			type: "custom_message" as const,
 			customType: draft.customType,
@@ -89,12 +106,12 @@ export function registerBudget(
 	pi.on("session_tree", resetForTransition);
 	pi.on("model_select", resetForTransition);
 	pi.on("session_shutdown", resetForTransition);
-	// A request can fail before Pi emits turn_end. agent_settled is the public
-	// lifecycle point that must discard an uncommitted draft before the next prompt.
-	// UI notices follow committed reminders. Aborted requests can retry their drafts
-	// without showing the same low-budget notification twice.
+	// A warning can be committed at turn_end, before a tool turn or a reset changes the
+	// active window. Observe the active branch at public lifecycle boundaries and match
+	// the candidate against its originating window segment, not only the current window.
+	pi.on("turn_start", (_event, ctx) => notifyCommittedWarnings(ctx));
 	pi.on("agent_settled", (_event, ctx) => {
-		notifyCommittedReminders(ctx);
+		notifyCommittedWarnings(ctx, true);
 		clearStaged();
 	});
 	pi.on("context", (_event, ctx) => {
@@ -151,6 +168,6 @@ export function registerBudget(
 		automaticResetEnabled,
 		hardReserveDue,
 		consumeTurnEnd,
-		clear: () => { clearStaged(); pendingNotices = []; },
+		clear: () => { clearStaged(); pendingNotices.clear(); },
 	};
 }

package/src/context/prompts.ts

@@ -36,8 +36,8 @@ function notesUnavailableNotice(snapshot: NotesSnapshot): string | undefined {
  * per home, and the session home is never peeked — a session MAP.md is an ordinary note. The
  * pocket then lists recent fresh notes under per-home quotas (POCKET_SESSION_LIMIT /
  * POCKET_PROJECT_LIMIT / POCKET_HUMAN_LIMIT / POCKET_AGENT_LIMIT / POCKET_MODEL_LIMIT),
- * most-recently-updated first within each home, one metadata line each: address, line count,
- * UTF-8 byte count, relative update time at window open. Bodies never render
+ * most-recently-updated first within each home, one metadata line each: address, body character
+ * count, relative update time at window open. Bodies never render
  * in the pocket; stale notes are excluded; MAP.md itself never takes a pocket seat.
  */
 function notesIndex(snapshot: NotesSnapshot): string {
@@ -62,7 +62,7 @@ function notesIndex(snapshot: NotesSnapshot): string {
 	if (recentNotes.length > 0) {
 		const lines = [`You find ${recentNotes.length} crumpled note${recentNotes.length === 1 ? "" : "s"} in your pocket (by prefix, most recent first within each: up to ${POCKET_SESSION_LIMIT} from this session, ${POCKET_PROJECT_LIMIT} from @project, ${POCKET_HUMAN_LIMIT} from @human, ${POCKET_AGENT_LIMIT} from @self, ${POCKET_MODEL_LIMIT} from @model). A note's content never appears here, so its name has to say what the note is about:`];
 		for (const row of recentNotes) {
-			lines.push(`- ${row.address} (${row.body.split("\n").length} lines, ${row.sizeBytes} UTF-8 bytes, updated ${relativeTime(row.meta.updatedAt, snapshot.openedAt)})`);
+			lines.push(`- ${row.address}  ·  ${Array.from(row.body).length} chars  ·  ${relativeTime(row.meta.updatedAt, snapshot.openedAt)}`);
 		}
 		sections.push(lines.join("\n"));
 	}

package/src/dream/doctor.ts

@@ -30,9 +30,6 @@ export function doctor(home: string): string[] {
 		for (const [key, valid] of Object.entries({ origin: /^(user|self|external)$/, status: /^(active|superseded|pending|archived)$/, stale: /^(true|false)$/, accessCount: /^\d+$/ })) {
 			if (!valid.test(fields.get(key) ?? "")) report(path, `missing/invalid ${key}; repair frontmatter`);
 		}
-		for (const [legacy, current] of [["created_at", "createdAt"], ["updated_at", "updatedAt"], ["last_accessed", "lastAccessed"], ["access_count", "accessCount"], ["source_window", "sourceWindow"], ["recurrence_count", "recurrenceCount"], ["recurrence_windows", "recurrenceWindows"]]) {
-			if (fields.has(legacy)) report(path, `legacy metadata key ${legacy}; manually migrate to ${current}`);
-		}
 		for (const key of ["createdAt", "updatedAt", "lastAccessed"]) {
 			const value = fields.get(key);
 			if (!value || !Number.isFinite(Date.parse(value))) report(path, `missing/invalid ${key}; use an ISO timestamp`);

package/src/notes/frontmatter.ts

@@ -30,7 +30,6 @@ const SCOPES: readonly Scope[] = ["session", "project", "human", "agent", "model
 const ORIGINS: readonly Origin[] = ["user", "self", "external"];
 const STATUSES: readonly NoteStatus[] = ["active", "superseded", "pending", "archived"];
 const TIMESTAMP_KEYS = ["createdAt", "updatedAt", "lastAccessed"] as const;
-const LEGACY_KNOWN_KEYS = ["created_at", "updated_at", "last_accessed", "access_count", "source_window", "recurrence_count", "recurrence_windows"] as const;
 /** Emission order, exactly the Design's key list. */
 const KNOWN_KEYS = ["origin", "status", "stale", "createdAt", "updatedAt", "lastAccessed", "accessCount", "sourceWindow", "supersedes", "recurrenceCount", "recurrenceWindows"] as const;
 
@@ -125,13 +124,10 @@ function parseFrontmatter(raw: string): { fields: Record<string, unknown>; body:
 
 /**
  * Parse a note file. Missing known keys take the Design defaults (status active, stale false,
- * accessCount 0, timestamps now); unknown keys are carried through untouched. Known
- * snake_case metadata is refused because it requires the explicit manual migration.
+ * accessCount 0, timestamps now); unknown keys are carried through untouched.
  */
 export function parseNote(raw: string, now = Date.now()): { meta: NoteMeta; body: string } {
 	const { fields, body } = parseFrontmatter(raw);
-	const legacyKeys = LEGACY_KNOWN_KEYS.filter((key) => Object.hasOwn(fields, key));
-	if (legacyKeys.length > 0) throw new Error(`legacy note metadata ${legacyKeys.join(", ")} requires manual migration to camelCase before this note can be used`);
 	const meta = { ...fields } as Record<string, unknown>;
 	// scope is a legacy on-disk field: store callers derive it from the file's home and
 	// overwrite it after parsing, so an absent or outdated value just falls back.