@astrosheep/pi-context 0.20.0 → 0.22.0

package/dist/test/{memory.test.js → notes.test.js}

@@ -11,16 +11,21 @@ import { existsSync, mkdtempSync, readdirSync, readFileSync, writeFileSync } fro
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
-import { physicalPath, projectKey, scopeDir } from "../src/memory/paths.js";
-import { listNotes } from "../src/memory/store.js";
+import { physicalPath, projectKey, scopeDir } from "../src/notes/paths.js";
+import { listNotes } from "../src/notes/store.js";
 import { MAX_NOTE_BYTES, MAX_NOTE_PATH_BYTES, PROTOCOL_BLOCK } from "../src/protocol.js";
 import { call, context, makeExtension, manager, resultJson, resultRead, runHandlers } from "./integration.test.js";
-process.env.PI_CODING_AGENT_DIR = mkdtempSync(join(tmpdir(), "pi-context-memory-agent-"));
+process.env.PI_CODING_AGENT_DIR = mkdtempSync(join(tmpdir(), "pi-context-notes-agent-"));
 function freshRoot() {
     const root = mkdtempSync(join(tmpdir(), "pi-context-notes-"));
     process.env.PI_NOTES_HOME = root;
     return root;
 }
+function setUpdatedAt(scope, path, ctx, timestamp) {
+    const file = physicalPath(scope, path, ctx);
+    const raw = readFileSync(file, "utf8");
+    writeFileSync(file, raw.replace(/^updated_at: .*$/m, `updated_at: ${new Date(timestamp).toISOString()}`));
+}
 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"]) {
@@ -48,15 +53,16 @@ test("write lands a real markdown file with harness frontmatter and a pure body"
     const raw = readFileSync(file, "utf8");
     assert.match(raw, /^---\n/, "the file opens with frontmatter");
     assert.match(raw, /\n---\n\nhello$/, "frontmatter is followed by a blank line and the exact body");
-    for (const [key, value] of [["scope", "session"], ["origin", "self"], ["status", "active"], ["stale", "false"], ["access_count", "0"]]) {
+    for (const [key, value] of [["origin", "self"], ["status", "active"], ["stale", "false"], ["access_count", "0"]]) {
         assert.match(raw, new RegExp(`^${key}: ${value}$`, "m"), `frontmatter carries ${key}=${value}`);
     }
+    assert.equal(/^scope:/m.test(raw), false, "scope is derived from the file home, never persisted");
     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");
     // A leading YAML block in user content is stripped from the body.
-    await call(captured, "notes_write", { path: "stripped.md", content: "---\nscope: global\nnonsense: true\n---\nreal body" }, ctx);
+    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");
     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");
@@ -84,6 +90,14 @@ test("overwrite preserves created_at and unknown keys, bumps updated_at, and cle
     assert.equal(listed.meta.stale, false, "a plain rewrite clears stale");
     assert.equal(listed.meta.status, "active");
 });
+test("listNotes retains each parsed body for MAP injection", async () => {
+    freshRoot();
+    const session = manager();
+    const captured = makeExtension(session);
+    const ctx = context(session);
+    await call(captured, "notes_write", { path: "retained.md", content: "parsed once" }, ctx);
+    assert.equal(listNotes(ctx, { scope: "session" })[0]?.body, "parsed once");
+});
 test("edit is body-scoped with named failures and a replace_all escape hatch", async () => {
     freshRoot();
     const session = manager();
@@ -103,6 +117,30 @@ test("edit is body-scoped with named failures and a replace_all escape hatch", a
     const frontmatterOnly = resultJson(await call(captured, "notes_edit", { path: "edit.md", edits: [{ oldText: "scope", newText: "x" }] }, ctx));
     assert.equal(frontmatterOnly.edit_index, 0, "a frontmatter-only anchor is not a body match");
 });
+test("a single edit inserts newText byte-for-byte: no $-pattern substitution", async () => {
+    freshRoot();
+    const session = manager();
+    const captured = makeExtension(session);
+    const ctx = context(session);
+    // Each pattern is a JS String.replace replacement token. With positional splicing the whole
+    // two-character (or two-dollar) sequence lands literally; with String.replace it would expand,
+    // and the prefix token ($`) would splice in the entire document prefix.
+    const cases = ["$&", "$`", "$'", "$1", "$$"];
+    for (const token of cases) {
+        const newText = `pre${token}post`;
+        await call(captured, "notes_write", { path: "literal.md", content: "alpha\nbeta\ngamma" }, ctx);
+        const edited = resultJson(await call(captured, "notes_edit", { path: "literal.md", edits: [{ oldText: "beta", newText }] }, ctx));
+        assert.equal(edited.applied, 1, `the single edit for ${JSON.stringify(token)} applied`);
+        const body = resultRead(await call(captured, "notes_read", { path: "literal.md" }, ctx)).content;
+        assert.equal(body.endsWith(`alpha\n${newText}\ngamma`), true, `${JSON.stringify(token)} is inserted literally`);
+        assert.equal(body.endsWith(`alpha\nalpha\npre${token}post\ngamma`), false, `${JSON.stringify(token)} does not splice in the document prefix`);
+    }
+    // The replace_all branch (split/join) is likewise literal, so both branches agree.
+    await call(captured, "notes_write", { path: "literal-all.md", content: "one X two X three" }, ctx);
+    await call(captured, "notes_edit", { path: "literal-all.md", edits: [{ oldText: "X", newText: "$`$&$1$$" }], replace_all: true }, ctx);
+    const allBody = resultRead(await call(captured, "notes_read", { path: "literal-all.md" }, ctx)).content;
+    assert.equal(allBody.endsWith("one $`$&$1$$ two $`$&$1$$ three"), true, "replace_all inserts $-patterns literally too");
+});
 test("metadata-only edit updates setters without touching the body", async () => {
     freshRoot();
     const session = manager();
@@ -134,12 +172,12 @@ test("notes_edit returns a pi-edit-style diff of what changed", async () => {
     assert.match(metaOnly.diff, /- *\d+ stale: false/);
     assert.match(metaOnly.diff, /\+ *\d+ stale: true/);
     assert.equal(metaOnly.diff.includes("alpha"), false, "a metadata-only diff does not drag the body in");
-    // Both → one combined diff naming body and frontmatter changes.
-    const combined = resultJson(await call(captured, "notes_edit", { path: "d.md", edits: [{ oldText: "alpha", newText: "ALPHA" }], scope: "project" }, ctx));
+    // Both → one combined diff naming body and frontmatter changes, without moving homes.
+    const combined = resultJson(await call(captured, "notes_edit", { path: "d.md", edits: [{ oldText: "alpha", newText: "ALPHA" }], stale: false }, ctx));
     assert.match(combined.diff, /- *\d+ alpha/);
     assert.match(combined.diff, /\+ *\d+ ALPHA/);
-    assert.match(combined.diff, /- *\d+ scope: session/);
-    assert.match(combined.diff, /\+ *\d+ scope: project/);
+    assert.match(combined.diff, /- *\d+ stale: true/);
+    assert.match(combined.diff, /\+ *\d+ stale: false/);
 });
 test("nothing-to-do, not-found, atomic batches, and replace_all zero-match are named", async () => {
     freshRoot();
@@ -167,22 +205,22 @@ test("nothing-to-do, not-found, atomic batches, and replace_all zero-match are n
     const zero = resultJson(await call(captured, "notes_edit", { path: "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("scope resolution, access counting, and movement with a typed refusal", async () => {
+test.skip("scope resolution and movement are superseded by explicit address tests", async () => {
     freshRoot();
     const session = manager();
     const captured = makeExtension(session);
     const ctx = context(session);
-    await call(captured, "notes_write", { path: "shared.md", content: "global body", scope: "global" }, ctx);
+    await call(captured, "notes_write", { path: "shared.md", content: "personal body", scope: "personal" }, ctx);
     await call(captured, "notes_write", { path: "shared.md", content: "session body", scope: "session" }, ctx);
     const first = resultRead(await call(captured, "notes_read", { path: "shared.md" }, ctx));
-    assert.equal(first.details.scope, "session", "session wins the precedence over global");
+    assert.equal(first.details.scope, "session", "session wins the precedence over personal");
     const readAgain = resultRead(await call(captured, "notes_read", { path: "shared.md", scope: "session" }, ctx));
     assert.ok(readAgain.content.includes("session body"));
     const sessionMeta = listNotes(ctx, { scope: "session" })[0].meta;
     assert.equal(sessionMeta.access_count, 2, "each read bumps access_count");
-    const globalMeta = listNotes(ctx, { scope: "global" })[0].meta;
-    assert.equal(globalMeta.access_count, 0, "the global copy is untouched");
-    // Move the session copy to project; the global copy is untouched.
+    const personalMeta = listNotes(ctx, { scope: "personal" })[0].meta;
+    assert.equal(personalMeta.access_count, 0, "the personal copy is untouched");
+    // Move the session copy to project; the personal copy is untouched.
     const moved = resultJson(await call(captured, "notes_edit", { path: "shared.md", edits: [{ oldText: "session", newText: "moved" }], scope: "project" }, ctx));
     assert.equal(moved.meta.scope, "project");
     assert.equal(moved.resolved_scope, "session", "resolved_scope names the layer the file moved from");
@@ -190,11 +228,11 @@ test("scope resolution, access counting, and movement with a typed refusal", asy
     assert.equal(existsSync(physicalPath("project", "shared.md", ctx)), true, "the file now lives in the project scope");
     // A move onto an existing target is refused and both files survive unchanged.
     await call(captured, "notes_write", { path: "clash.md", content: "session stay", scope: "session" }, ctx);
-    await call(captured, "notes_write", { path: "clash.md", content: "global stay", scope: "global" }, ctx);
-    const beforeGlobal = readFileSync(physicalPath("global", "clash.md", ctx), "utf8");
-    const refusal = resultJson(await call(captured, "notes_edit", { path: "clash.md", edits: [{ oldText: "stay", newText: "moved" }], scope: "global" }, ctx));
+    await call(captured, "notes_write", { path: "clash.md", content: "personal stay", scope: "personal" }, ctx);
+    const beforePersonal = readFileSync(physicalPath("personal", "clash.md", ctx), "utf8");
+    const refusal = resultJson(await call(captured, "notes_edit", { path: "clash.md", edits: [{ oldText: "stay", newText: "moved" }], scope: "personal" }, ctx));
     assert.match(refusal.error, /already exists/);
-    assert.equal(readFileSync(physicalPath("global", "clash.md", ctx), "utf8"), beforeGlobal, "the target survives a refused move");
+    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 () => {
     freshRoot();
@@ -203,20 +241,20 @@ test("list and search merge scopes and carry scope; the path jail rejects escape
     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: "global" }, 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(), ["global", "project", "session"], "every merged row carries its scope");
+    assert.deepEqual([...listed.files].map((file) => file.scope).sort(), ["personal", "project", "session"], "every merged row carries its scope");
     for (const row of listed.files) {
         assert.equal(typeof row.size_bytes, "number");
         assert.equal(row.origin, "self");
         assert.equal(row.status, "active");
         assert.equal(row.stale, false);
     }
-    const scoped = resultJson(await call(captured, "notes_list", { scope: "global" }, ctx));
+    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");
     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(), ["global", "project", "session"]);
+    assert.deepEqual([...searched.files].map((file) => file.scope).sort(), ["personal", "project", "session"]);
     assert.equal(searched.files.every((file) => file.matches_total === 1), true);
     const hit = searched.files[0].matches[0];
     assert.equal(hit.line, 1);
@@ -238,14 +276,14 @@ test("the boot index reads the physical store across scopes and excludes stale n
     const captured = makeExtension(session);
     const ctx = context(session);
     await call(captured, "notes_write", { path: "fresh.md", content: "fresh content" }, ctx);
-    await call(captured, "notes_write", { path: "global.md", content: "global content", scope: "global" }, ctx);
+    await call(captured, "notes_write", { path: "personal.md", content: "personal content", scope: "personal" }, ctx);
     await call(captured, "notes_write", { path: "old.md", content: "stale content", stale: true }, ctx);
     runHandlers(captured, "session_start", {}, ctx);
     const text = typeof captured.sent[0]?.message.content === "string" ? captured.sent[0].message.content : "";
     assert.ok(text.includes("fresh.md"), "a fresh session note is indexed");
-    assert.ok(text.includes("global.md"), "a fresh global note is indexed");
+    assert.ok(text.includes("personal.md"), "a fresh personal note is indexed");
     assert.equal(text.includes("old.md"), false, "a stale note leaves the index");
-    assert.equal(text.includes("stale content"), false, "a stale preview is not rendered");
+    assert.equal(text.includes("stale content"), false, "the stale note's body is absent from boot");
     for (const name of ["notes_write", "notes_edit", "notes_read", "notes_search", "notes_list"]) {
         assert.ok(PROTOCOL_BLOCK.includes(name), `the protocol block names ${name}`);
     }
@@ -318,46 +356,54 @@ test("write-time caps refuse an oversized vpath or serialized file, and edit ref
     const refusedEdit = resultJson(await call(captured, "notes_edit", { path: "small.md", edits: [{ oldText: "small", newText: "y".repeat(MAX_NOTE_BYTES) }] }, ctx));
     assert.match(refusedEdit.error, new RegExp(String(MAX_NOTE_BYTES)), "an edit that would exceed the cap is refused");
 });
-test("a global TOC.md body is injected ahead of the recent-notes list", async () => {
+test("fresh personal and project MAP.md bodies are both resident before the pocket", async () => {
     freshRoot();
     const session = manager();
     const captured = makeExtension(session);
     const ctx = context(session);
-    await call(captured, "notes_write", { path: "TOC.md", content: "MAP: global\nMAP: second", scope: "global" }, ctx);
+    await call(captured, "notes_write", { address: "MAP.md", content: "MAP: session" }, ctx);
+    await call(captured, "notes_write", { address: "@project/MAP.md", content: "MAP: project" }, ctx);
+    await call(captured, "notes_write", { address: "@personal/MAP.md", content: "MAP: personal\nMAP: second" }, ctx);
     await call(captured, "notes_write", { path: "recent.md", content: "recent body" }, ctx);
     runHandlers(captured, "session_start", {}, ctx);
     const boot = typeof captured.sent.at(-1)?.message.content === "string" ? captured.sent.at(-1).message.content : "";
-    assert.ok(boot.includes("MAP: global"), "a global TOC is injected");
-    assert.ok(boot.indexOf("MAP: global") < boot.indexOf("crumpled note"), "the TOC body precedes the recent-notes list");
+    assert.ok(boot.includes("MAP: personal"), "the personal map is injected");
+    assert.ok(boot.includes("MAP: project"), "the project map is injected");
+    assert.equal(boot.includes("MAP: session"), false, "the session map is never injected");
+    assert.ok(boot.indexOf("MAP: personal") < boot.indexOf("MAP: project"), "the personal map precedes the project map");
+    assert.ok(boot.indexOf("MAP: project") < boot.indexOf("crumpled note"), "both map bodies precede the pocket");
     assert.ok(PROTOCOL_BLOCK.includes("notes_write"), "the protocol text still rides along");
 });
-test("a session TOC.md wins precedence over the global map", async () => {
-    freshRoot();
-    const session = manager();
-    const captured = makeExtension(session);
-    const ctx = context(session);
-    await call(captured, "notes_write", { path: "TOC.md", content: "MAP: global", scope: "global" }, ctx);
-    await call(captured, "notes_write", { path: "TOC.md", content: "MAP: session", scope: "session" }, ctx);
-    runHandlers(captured, "session_start", {}, ctx);
-    const boot = typeof captured.sent.at(-1)?.message.content === "string" ? captured.sent.at(-1).message.content : "";
-    const injected = boot.slice(0, boot.indexOf("crumpled note") === -1 ? boot.length : boot.indexOf("crumpled note"));
-    assert.ok(injected.includes("MAP: session"), "the session TOC wins the precedence");
-    assert.equal(injected.includes("MAP: global"), false, "only the first-hit TOC is injected");
-});
-test("the boot index admits up to five fresh notes and the protocol carries the exact stale line", async () => {
+test("the boot pocket applies per-home quotas in session, project, personal order", async () => {
     freshRoot();
     const session = manager();
     const captured = makeExtension(session);
     const ctx = context(session);
-    for (let index = 0; index < 6; index++) {
-        await call(captured, "notes_write", { path: `fresh-${index}.md`, content: `body ${index}` }, ctx);
+    const base = Date.parse("2026-01-01T00:00:00.000Z");
+    for (const [scope, count] of [["session", 6], ["project", 3], ["personal", 3]]) {
+        for (let index = 0; index < count; index++) {
+            const path = `${scope}-${index}.md`;
+            await call(captured, "notes_write", { path, content: `${scope} body`, scope }, ctx);
+            setUpdatedAt(scope, path, ctx, base + index * 1_000);
+        }
     }
+    await call(captured, "notes_write", { address: "MAP.md", content: "MAP: session" }, ctx);
+    await call(captured, "notes_write", { address: "@project/MAP.md", content: "MAP: project" }, ctx);
+    await call(captured, "notes_write", { address: "@personal/MAP.md", content: "MAP: personal" }, ctx);
     runHandlers(captured, "session_start", {}, ctx);
     const boot = typeof captured.sent.at(-1)?.message.content === "string" ? captured.sent.at(-1).message.content : "";
-    assert.match(boot, /\(up to 5, most recent first\)/, "the pocket line says up to 5");
-    assert.equal((boot.match(/^- /gm) ?? []).length, 5, "exactly five fresh notes are indexed, not six");
-    assert.ok(PROTOCOL_BLOCK.includes("Mark outdated or unneeded notes stale — leave them, and they will keep misleading you."), "the protocol block carries the v2 stale line verbatim");
-    assert.equal(PROTOCOL_BLOCK.split("Mark outdated or unneeded notes stale — leave them, and they will keep misleading you.").length - 1, 1, "the stale line appears exactly once");
+    assert.ok(boot.includes("You find 9 crumpled notes in your pocket (by home, most recent first within each: up to 5 from this session, 2 from this project, 2 from personal). A note's content never appears here, so its name has to say what the note is about:"), "the pocket line matches the dictated copy");
+    for (const name of ["session-5.md", "session-4.md", "session-3.md", "session-2.md", "session-1.md", "@project/project-2.md", "@project/project-1.md", "@personal/personal-2.md", "@personal/personal-1.md"]) {
+        assert.ok(boot.includes(name), `${name} stays in the pocket`);
+    }
+    for (const name of ["session-0.md", "@project/project-0.md", "@personal/personal-0.md", "MAP.md", "MAP: session"]) {
+        assert.equal(boot.includes(name), false, `${name} is not a pocket entry`);
+    }
+    assert.ok(boot.indexOf("session-5.md") < boot.indexOf("session-4.md"), "session notes are most-recent-first");
+    assert.ok(boot.indexOf("@project/project-2.md") < boot.indexOf("@project/project-1.md"), "project notes are most-recent-first");
+    assert.ok(boot.indexOf("@personal/personal-2.md") < boot.indexOf("@personal/personal-1.md"), "personal notes are most-recent-first");
+    assert.ok(boot.indexOf("session-1.md") < boot.indexOf("@project/project-2.md"), "session notes precede project notes");
+    assert.ok(boot.indexOf("@project/project-1.md") < boot.indexOf("@personal/personal-2.md"), "project notes precede personal notes");
 });
 test("project scope keys off the git root basename and sha1 prefix", () => {
     const root = mkdtempSync(join(tmpdir(), "pi-context-proj-"));
@@ -368,3 +414,61 @@ test("project scope keys off the git root basename and sha1 prefix", () => {
     assert.match(key, /^pi-context-proj-[^-]+-[0-9a-f]{8}$/, "the project key is basename plus an 8-hex sha1 prefix");
     assert.equal(scopeDir("project", ctx), join(process.env.PI_NOTES_HOME, "project", key));
 });
+test("@ addresses select one home, reject illegal sigils, and never fall back", async () => {
+    const root = freshRoot();
+    const session = manager();
+    const captured = makeExtension(session);
+    const ctx = context(session);
+    await call(captured, "notes_write", { address: "same.md", content: "session" }, ctx);
+    await call(captured, "notes_write", { address: "@project/same.md", content: "project" }, ctx);
+    await call(captured, "notes_write", { address: "@personal/same.md", content: "personal" }, ctx);
+    assert.ok(existsSync(physicalPath("project", "same.md", ctx)), "@project writes to the current project home");
+    assert.ok(existsSync(physicalPath("personal", "same.md", ctx)), "@personal writes to the personal home");
+    assert.match(resultRead(await call(captured, "notes_read", { address: "same.md" }, ctx)).content, /session$/);
+    assert.equal(resultJson(await call(captured, "notes_read", { address: "@project/missing.md" }, ctx)).error, "note not found");
+    await assert.rejects(() => call(captured, "notes_read", { address: "@glboal/same.md" }, ctx), /@project\/.*@personal\/.*bare names are the session home/);
+    await assert.rejects(() => call(captured, "notes_write", { address: "bad@name.md", content: "no" }, ctx), /@project\/.*@personal\/.*bare names are the session home/);
+    assert.equal(existsSync(join(root, "personal", "bad@name.md")), false, "a bad sigil creates nothing anywhere");
+});
+test("full addresses drive outputs and patterns; on-disk scope is read then dropped", async () => {
+    freshRoot();
+    const session = manager();
+    const captured = makeExtension(session);
+    const ctx = context(session);
+    await call(captured, "notes_write", { address: "root.md", content: "needle" }, ctx);
+    await call(captured, "notes_write", { address: "@project/project.md", content: "needle" }, ctx);
+    await call(captured, "notes_write", { address: "@personal/personal.md", content: "needle" }, ctx);
+    const list = resultJson(await call(captured, "notes_list", { pattern: "**" }, ctx));
+    assert.deepEqual(list.files.map((file) => file.address).sort(), ["@personal/personal.md", "@project/project.md", "root.md"]);
+    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");
+    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");
+    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");
+});
+test("stale project and personal maps are skipped independently", async () => {
+    freshRoot();
+    const session = manager();
+    const captured = makeExtension(session);
+    const ctx = context(session);
+    await call(captured, "notes_write", { address: "@project/MAP.md", content: "project fresh" }, ctx);
+    await call(captured, "notes_write", { address: "@personal/MAP.md", content: "personal stale", stale: true }, ctx);
+    runHandlers(captured, "session_start", {}, ctx);
+    let boot = String(captured.sent.at(-1)?.message.content ?? "");
+    assert.ok(boot.includes("project fresh"), "a fresh project map survives a stale personal map");
+    assert.equal(boot.includes("personal stale"), false, "the stale personal map is skipped");
+    const second = manager();
+    const secondCaptured = makeExtension(second);
+    const secondCtx = context(second);
+    await call(secondCaptured, "notes_edit", { address: "@project/MAP.md", stale: true }, secondCtx);
+    await call(secondCaptured, "notes_edit", { address: "@personal/MAP.md", stale: false }, secondCtx);
+    runHandlers(secondCaptured, "session_start", {}, secondCtx);
+    boot = String(secondCaptured.sent.at(-1)?.message.content ?? "");
+    assert.equal(boot.includes("project fresh"), false, "the stale project map is skipped");
+    assert.ok(boot.includes("personal stale"), "a fresh personal map survives a stale project map");
+});

package/dist/test/pagination.property.test.js

@@ -21,7 +21,7 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 import { historyFromSession } from "../src/index.js";
-import { listNotes, searchNotes } from "../src/memory/store.js";
+import { listNotes, searchNotes } from "../src/notes/store.js";
 import { TOOL_OUTPUT_MAX_BYTES } from "../src/tool-output.js";
 import { MAX_NOTE_PATH_BYTES } from "../src/protocol.js";
 import { appendText, call, context, makeExtension, manager, resultJson } from "./integration.test.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/pi-context",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "type": "module",
   "description": "Codex-style context windows for Pi: reset-style compaction, durable session history tools, and persistent notes.",
   "license": "MIT",
@@ -30,7 +30,7 @@
     "dream": "dist/src/dream/cli.js"
   },
   "scripts": {
-    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json && node -e \"require('node:fs').chmodSync('dist/src/dream/cli.js', 0o755)\"",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "npm run build && node --test dist/test/*.test.js",
     "prepublishOnly": "npm run typecheck",
@@ -42,9 +42,9 @@
     "@earendil-works/pi-coding-agent": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "^0.85.1",
-    "@earendil-works/pi-ai": "^0.85.1",
-    "@earendil-works/pi-coding-agent": "^0.85.1",
+    "@earendil-works/pi-agent-core": "^0.86.0",
+    "@earendil-works/pi-ai": "^0.86.0",
+    "@earendil-works/pi-coding-agent": "^0.86.0",
     "@types/node": "^22.19.19",
     "typescript": "^5.9.3"
   },

package/playbook.md

@@ -1,5 +1,32 @@
-I am dreaming over my notes, speaking in my own first-person voice. I inspect the supplied notes and return exactly one JSON manifest, with no commentary outside it.
+I am dreaming over my notes. They are plain markdown files in three homes, addressed as:
 
-I do seven chores: merge genuinely repeated notes; preserve provenance and recurrence windows; propose (but never execute) global promotions; move only clearly obsolete notes to reversible trash; identify pending ambiguities; propose skill candidates without installing them; and write a concise report of my reasoning and choices. I anchor every temporal claim to an absolute calendar date (YYYY-MM-DD), never to vague words like “today”. I stay aware of the index budget: prefer compact, deduplicated durable notes and avoid swelling the index with repetition. Skill-promotion proposals are proposals only. Judgment belongs here, not in the harness.
+- bare `<vpath>` for this session
+- `@project/<vpath>` for this project
+- `@personal/<vpath>` for personal notes
 
-My final output is the manifest schema documented by the command: merge, promote, trash, pending, skillCandidates, and a required report string.
+Every note has this frontmatter block:
+
+```yaml
+---
+origin: user | self | external
+status: active
+stale: false
+created_at: <timestamp>
+updated_at: <timestamp>
+last_accessed: <timestamp>
+access_count: 0
+---
+```
+
+## Dream rules
+
+1. **Probe before you trust.** Before keeping or promoting a note, verify its world referents with read-only file tools: paths in the body — do they still exist? branches — still present? Dead referents are why a note gets merged away or marked stale, never promoted.
+2. **Merge threshold.** Supersede another note only when all three hold: same topic (name it in the survivor's body), same kind of note (checkpoint/design/log…), and the survivor is strictly newer or strictly more specific. Otherwise keep both and record the open conflict in the survivor.
+3. **Size budget.** Keep every note under ~200 lines / ~8KB. Oversized notes get split by topic with a one-line cross-link in each (`see also: @home/<vpath>`). Checkpoints may exceed the budget — trim prose, never facts.
+4. **Keep the maps.** Each home's `MAP.md` maps that home's durable notes: one line per entry — its address and a short gist in your own words, never a mechanical body slice. Project notes go on `@project/MAP.md`, cross-project knowledge on `@personal/MAP.md`; session notes are never mapped — the pocket covers them. When a note is promoted across homes, move its line to the destination map; when a note goes stale, drop its line. Maps obey the same size budget as any note.
+5. **Jurisdiction.** Your mandate is the whole store — every session home, every project home, personal. Nothing is skipped: notes are never physically deleted and every run is bracketed by git commits, so the human gate can audit and revert whatever you touch. Group your report by home so the gate can see what moved. In every home: map entry lines are yours to maintain, but prose that carries rules or guidance is not — flag it in your report instead of rewriting it.
+6. **Leave stable notes alone.** Change notes to incorporate new evidence, resolve verified errors, merge genuine duplicates, or split oversized files—not merely to shorten or rephrase them. Preserve facts, conditions, exceptions, and uncertainty. No change is a valid outcome.
+
+Read the files and merge genuinely duplicate notes by editing the survivor, then set `stale: true` in the absorbed note's frontmatter. Nothing is physically deleted; stale notes remain readable. Promote durable cross-project knowledge by writing or editing at `@personal/<vpath>`. Keep notes compact and preserve useful provenance in the body.
+
+Do not write skill ideas as files. Put skill ideas and unresolved questions in your final assistant message as proposals for the human. Your final message should be a concise report of what you inspected, changed, and left unresolved. If you made no file writes, say so.

package/src/budget.ts

@@ -1,12 +1,16 @@
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { GUIDANCE_TYPE, WARNING_TYPE } from "./protocol.js";
-import { thresholdsFor, resetThresholds, deriveThresholds, mergePiContextSettings } from "./thresholds.js";
+import { thresholdsFor, resetThresholds } from "./thresholds.js";
 import { currentWindowId, hasWindowMessage } from "./history.js";
 import { tokenBudgetGuidance } from "./prompts.js";
 import { output } from "./tool-output.js";
 
-export { deriveThresholds, mergePiContextSettings } from "./thresholds.js";
+/** Remaining tokens in the current context window, or null when Pi has no usage estimate. */
+export function remainingTokens(ctx: Pick<ExtensionContext, "getContextUsage">): number | null {
+	const usage = ctx.getContextUsage();
+	return !usage || usage.tokens === null ? null : Math.max(0, usage.contextWindow - usage.tokens);
+}
 
 export function registerBudget(pi: ExtensionAPI, isEnabled: () => boolean) {
 	let guidancePersistedInWindow: string | undefined;
@@ -17,16 +21,15 @@ export function registerBudget(pi: ExtensionAPI, isEnabled: () => boolean) {
 		if (!isEnabled() || hasWindowMessage(ctx, GUIDANCE_TYPE)) return undefined;
 		// The early reminder persists once per window the first time remaining crosses
 		// reserve+margin. It never edits the outgoing request.
-		const usage = ctx.getContextUsage();
-		if (!usage || usage.tokens === null) return undefined;
-		const remaining = Math.max(0, usage.contextWindow - usage.tokens);
+		const remaining = remainingTokens(ctx);
+		if (remaining === null) return undefined;
 		const windowId = currentWindowId(ctx);
 		const { reminder, reserve, warning } = thresholdsFor(ctx);
 		// The final warning owns the deep band: when it has fired (or is due now),
 		// the shallow reminder would only repeat the same instruction closer to
 		// the wipe, at a worse position. See warning.ts.
 		if (remaining <= warning || hasWindowMessage(ctx, WARNING_TYPE)) return undefined;
-		if (remaining <= reminder && guidancePersistedInWindow !== windowId && !hasWindowMessage(ctx, GUIDANCE_TYPE)) {
+		if (remaining <= reminder && guidancePersistedInWindow !== windowId) {
 			guidancePersistedInWindow = windowId;
 			// Persist once per window — no transient copy. A transient bridge would
 			// cover the crossing request, but history would record the reminder after
@@ -54,11 +57,10 @@ export function registerBudget(pi: ExtensionAPI, isEnabled: () => boolean) {
 		description: "Return estimated context tokens left before your memory is wiped; null when Pi cannot estimate usage.",
 		parameters: Type.Object({}, { additionalProperties: false }),
 		async execute(_id, _params, _signal, _update, ctx) {
-			const usage = ctx.getContextUsage();
 			// The countdown the model sees ends at the warning line (reserve + runway);
 			// the runway below it is overdraft the model never sees. See protocol.ts.
-			const remaining = usage?.tokens === null || usage === undefined ? null : Math.max(0, usage.contextWindow - usage.tokens - thresholdsFor(ctx as ExtensionContext).warning);
-			return output({ remaining_tokens: remaining });
+			const remaining = remainingTokens(ctx);
+			return output({ remaining_tokens: remaining === null ? null : Math.max(0, remaining - thresholdsFor(ctx as ExtensionContext).warning) });
 		},
 	}));
 

package/src/dream/cli.ts

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
-import { existsSync, mkdirSync, statSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
+import { appendFileSync, existsSync, mkdirSync, realpathSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
-import { acquireLock, failLock, releaseLock } from "./lock.js";
+import { fileURLToPath } from "node:url";
+import { acquireLock, failLock, lastRunPath, releaseLock } from "./lock.js";
 import { materialGate, timeGate } from "./gates.js";
-import { loadPlaybook, runDreamer } from "./runner.js";
-import { applyManifest } from "./apply.js";
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { loadPlaybook, runDreamer, type DreamerSessionFactory, type DreamResult, type DreamWrite } from "./runner.js";
+import { gitCommit } from "./git.js";
+import { readDreamerSettings, type DreamerSetting } from "../thresholds.js";
+import { notesRoot } from "../notes/paths.js";
 
 function args(argv: string[]) { const out: Record<string, string | boolean> = {}; for (let i=0;i<argv.length;i++) { const a=argv[i]!; if (a === "--force" || a === "--help") out[a.slice(2)] = true; else if (a.startsWith("--")) out[a.slice(2)] = argv[++i] ?? ""; } return out; }
 function packageRoot(): string {
@@ -14,20 +15,97 @@ function packageRoot(): string {
 	while (true) { if (existsSync(join(dir, "package.json"))) return dir; const parent = dirname(dir); if (parent === dir) throw new Error("could not locate installed package root"); dir = parent; }
 }
 
-export async function main(argv = process.argv.slice(2)): Promise<number> {
-	const a = args(argv); if (a.help) { console.log("dream --notes-home <dir> [--min-hours 24] [--min-sessions 3] [--force] [--dreamer <cmd>] [--dreamer-model <pattern>] [--playbook <path>]\nDefault dreamer: in-process pi SDK session with read-only tools; use a cheap model in production. Default playbook: <installed package root>/playbook.md; --playbook overrides it."); return 0; }
-	const home = resolve(String(a["notes-home"] ?? process.env.PI_NOTES_HOME ?? join(homedir(), ".agents", "notes"))); process.env.PI_NOTES_HOME = home; mkdirSync(home, { recursive: true });
-	const lockPath = join(home, ".dream.lock"); const minHours = Number(a["min-hours"] ?? 24); const minSessions = Number(a["min-sessions"] ?? 3);
-	const time = timeGate(lockPath, minHours); console.log(time.reason); if (!a.force && !time.ok) return 0;
-	const material = materialGate(home, existsSync(lockPath) ? statSync(lockPath).mtimeMs : 0, minSessions); console.log(material.reason); if (!a.force && !material.ok) return 0;
+/** Injection seams used by tests; production uses the defaults. */
+export type DreamDependencies = {
+	sessionFactory?: DreamerSessionFactory;
+	dreamerSettings?: (cwd?: string) => DreamerSetting;
+	runDreamer?: typeof runDreamer;
+};
+
+function writeList(writes: DreamWrite[]): string {
+	return writes.length ? writes.map((w) => `- ${w.tool}: ${w.path}`).join("\n") : "- no changes";
+}
+
+/** Best-effort text write; returns the failure message instead of throwing. */
+function writeText(path: string, content: string): string | undefined {
+	try { mkdirSync(dirname(path), { recursive: true }); writeFileSync(path, content); return undefined; }
+	catch (error) { return error instanceof Error ? error.message : String(error); }
+}
+
+function appendText(path: string, content: string): string | undefined {
+	try { appendFileSync(path, content); return undefined; }
+	catch (error) { return error instanceof Error ? error.message : String(error); }
+}
+
+/**
+ * Close one dream: record the report, then run the final audit commit. The audit always
+ * runs even when the report cannot be written, and a failed audit is appended to the
+ * report (when it exists) as well as named on stderr, so neither failure hides the other.
+ */
+function finishDream(home: string, stamp: string, reportPath: string, failed: boolean, body: string, writes: DreamWrite[]): number {
+	const header = failed ? `# Dream ${stamp} (failed)` : `# Dream ${stamp}`;
+	let reportError = writeText(reportPath, `${header}\n\n${body}\n\n${writeList(writes)}\n`);
+	const audit = gitCommit(home, `dream ${stamp}${failed ? " (failed)" : ""}`);
+	if (!audit.ok) {
+		console.error(`dream: final audit failed: ${audit.error}`);
+		reportError ??= appendText(reportPath, `\n## Final audit failed\n\n${audit.error}\n`);
+	}
+	if (reportError) console.error(`dream: could not write report at ${reportPath}: ${reportError}`);
+	return failed || !audit.ok || reportError !== undefined ? 1 : 0;
+}
+
+export async function main(argv = process.argv.slice(2), deps: DreamDependencies = {}): Promise<number> {
+	const a = args(argv); if (a.help) { console.log("dream --notes-home <dir> [--min-hours 24] [--min-sessions 3] [--force] [--dreamer <model pattern>] [--playbook <path>]\nDreamer model: --dreamer wins, else pi-context.dreamer from settings, else the automatic model. Default playbook: <installed package root>/playbook.md; --playbook overrides it."); return 0; }
+	const home = resolve(String(a["notes-home"] ?? notesRoot())); process.env.PI_NOTES_HOME = home; mkdirSync(home, { recursive: true });
+	const lockPath = join(home, ".dream.lock"); const stampPath = lastRunPath(lockPath);
+	const minHours = Number(a["min-hours"] ?? 24); const minSessions = Number(a["min-sessions"] ?? 3);
+	const time = timeGate(stampPath, minHours); console.log(time.reason); if (!a.force && !time.ok) return 0;
+	const since = existsSync(stampPath) ? statSync(stampPath).mtimeMs : 0;
+	const material = materialGate(home, since, minSessions); console.log(material.reason); if (!a.force && !material.ok) return 0;
 	let lock; try { lock = acquireLock(lockPath); } catch (e) { console.log(`lock gate: ${e instanceof Error ? e.message : e}`); return 0; } if (!lock.held) { console.log(lock.reason); return 0; }
 	const stamp = new Date(lock.startedAt).toISOString().replace(/[:.]/g, "-"); const reportPath = join(home, "dreams", `${stamp}.md`);
+	let succeeded = false;
 	try {
+		// CLI --dreamer wins over settings; settings win over the automatic model fallback.
+		let modelPattern: string | undefined;
+		if (a.dreamer) modelPattern = String(a.dreamer);
+		else {
+			const settings = (deps.dreamerSettings ?? readDreamerSettings)();
+			for (const warning of settings.warnings) console.error(warning);
+			modelPattern = settings.pattern;
+		}
+
+		// The baseline snapshot is required: without it the human gate has nothing to inspect.
+		const baseline = gitCommit(home, `baseline ${stamp}`);
+		if (!baseline.ok) { console.error(`dream: baseline audit failed: ${baseline.error}`); return 1; }
+
 		const defaultBook = join(packageRoot(), "playbook.md");
 		const playbookPath = String(a.playbook ?? defaultBook);
-		const playbook = loadPlaybook(playbookPath); const manifest = await runDreamer(playbook, home, { command: a.dreamer ? String(a.dreamer) : undefined, modelPattern: a["dreamer-model"] ? String(a["dreamer-model"]) : undefined });
-		const ctx = { cwd: home, sessionManager: { getSessionId: () => "dream" } } as unknown as ExtensionContext; const actions = applyManifest(ctx, home, stamp, manifest);
-		mkdirSync(join(home, "dreams"), { recursive: true }); writeFileSync(reportPath, `# Dream ${stamp}\n\n${manifest.report}\n\n${actions.map((x) => `- ${x}`).join("\n")}\n`); console.log(reportPath); return 0;
-	} catch (e) { failLock(lock); console.error(e instanceof Error ? e.message : e); return 1; } finally { releaseLock(lock); }
+		let result: DreamResult;
+		try {
+			const playbook = loadPlaybook(playbookPath);
+			result = await (deps.runDreamer ?? runDreamer)(playbook, home, { modelPattern, sessionFactory: deps.sessionFactory });
+		} catch (e) {
+			const message = e instanceof Error ? e.message : String(e);
+			console.error(message);
+			return finishDream(home, stamp, reportPath, true, message, []);
+		}
+		if (result.error) {
+			console.error(result.error);
+			return finishDream(home, stamp, reportPath, true, result.error, result.writes);
+		}
+		const code = finishDream(home, stamp, reportPath, false, result.report, result.writes);
+		if (code === 0) { succeeded = true; console.log(reportPath); }
+		return code;
+	} finally {
+		// Only the holder's own lock is released; a successor's lock is never touched.
+		if (succeeded) releaseLock(lock); else failLock(lock);
+	}
+}
+
+function isEntryPoint(): boolean {
+	const entry = process.argv[1];
+	if (!entry) return false;
+	try { return realpathSync(resolve(entry)) === realpathSync(fileURLToPath(import.meta.url)); } catch { return false; }
 }
-main().then((code) => { process.exitCode = code; });
+if (isEntryPoint()) main().then((code) => { process.exitCode = code; });