@astrosheep/pi-context 0.20.0 → 0.21.0

package/dist/test/dream.test.js

@@ -1,43 +1,142 @@
 import test from "node:test";
-import nodeAssert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, readFileSync, readdirSync, statSync, utimesSync, writeFileSync, existsSync } from "node:fs";
+import assert from "node:assert/strict";
+import { existsSync, linkSync, mkdirSync, readFileSync, statSync, symlinkSync, utimesSync, writeFileSync } from "node:fs";
+import { mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { spawnSync } from "node:child_process";
-import { defaultDreamerSessionFactory, runDreamer, READ_ONLY_TOOLS } from "../src/dream/runner.js";
-const cli = join(process.cwd(), "dist/src/dream/cli.js");
-const assert = nodeAssert;
-assert.match = (value, expected) => nodeAssert.ok(typeof expected === "string" ? value.includes(expected) : expected.test(value));
-function fixture() { const home = mkdtempSync(join(tmpdir(), "dream-")); mkdirSync(join(home, "pi/session"), { recursive: true }); return home; }
-function note(home, session, name, body, window) { const dir = join(home, "pi/session", session); mkdirSync(dir, { recursive: true }); writeFileSync(join(dir, name), `---\nscope: session\norigin: self\nstatus: active\nsource_window: ${window}\ncreated_at: 2020-01-01T00:00:00.000Z\nupdated_at: 2020-01-01T00:00:00.000Z\nlast_accessed: 2020-01-01T00:00:00.000Z\naccess_count: 0\n---\n\n${body}`); }
-function dreamer(home, manifest, sentinel) { const file = join(home, "dreamer.mjs"); writeFileSync(file, `import {writeFileSync} from 'node:fs'; ${sentinel ? `writeFileSync(${JSON.stringify(sentinel)}, 'spawned');` : ""} process.stdin.resume(); process.stdin.on('end',()=>process.stdout.write(${JSON.stringify(JSON.stringify(manifest))}));`); return `node ${file}`; }
-function run(home, extra = []) { return spawnSync(process.execPath, [cli, "--notes-home", home, ...extra], { encoding: "utf8" }); }
+import { acquireLock, failLock } from "../src/dream/lock.js";
+import { materialGate, timeGate } from "../src/dream/gates.js";
+import { defaultDreamerSessionFactory, dreamerWriteToolDefinitions, runDreamer, DREAMER_TOOLS } from "../src/dream/runner.js";
+import { gitCommit } from "../src/dream/git.js";
+import { execFileSync } from "node:child_process";
+import { contentText } from "../src/history.js";
+function fixture() { return mkdtempSync(join(tmpdir(), "dream-")); }
 function old(path) { const d = new Date(Date.now() - 48 * 3600_000); utimesSync(path, d, d); }
-test("dream time gate skips first, names reason, and does not spawn", () => { const h = fixture(); const sentinel = join(h, "sentinel"); const lock = join(h, ".dream.lock"); writeFileSync(lock, "999999"); const fresh = new Date(); utimesSync(lock, fresh, fresh); const r = run(h, ["--dreamer", dreamer(h, { report: "x" }, sentinel)]); assert.equal(r.status, 0); assert.match(r.stdout, "time gate"); assert.equal(existsSync(sentinel), false); });
-test("material gate skips when too few session directories changed", () => { const h = fixture(); const lock = join(h, ".dream.lock"); writeFileSync(lock, "999999"); old(lock); note(h, "only", "a.md", "a", "w"); const r = run(h, ["--min-sessions", "3", "--dreamer", dreamer(h, { report: "x" })]); assert.equal(r.status, 0); assert.match(r.stdout, "material gate"); });
-test("force bypasses time and material gates and external dreamer runs", () => { const h = fixture(); const r = run(h, ["--force", "--dreamer", dreamer(h, { report: "forced" })]); assert.equal(r.status, 0); assert.match(readFileSync(readdirSync(join(h, "dreams")).map(x => join(h, "dreams", x))[0], "utf8"), "forced"); });
-test("live PID lock excludes and dead PID is reclaimed", () => { const h = fixture(); const lock = join(h, ".dream.lock"); writeFileSync(lock, String(process.pid)); const r = run(h, ["--force", "--dreamer", dreamer(h, { report: "no" })]); assert.equal(r.status, 0); assert.match(r.stdout, "lock gate"); writeFileSync(lock, "999999"); old(lock); const ok = run(h, ["--force", "--dreamer", dreamer(h, { report: "reclaimed" })]); assert.equal(ok.status, 0); });
-test("external dreamer manifest merges recurrence, proposes global promotion, trashes, and reports", () => { const h = fixture(); note(h, "dream", "a.md", "one", "window-a"); note(h, "dream", "b.md", "two", "window-b"); note(h, "dream", "trash.md", "gone", "window-c"); const m = { merge: [{ into: "a.md", from: ["b.md"] }], promote: [{ path: "a.md", to: "global", reason: "shared" }], trash: [{ path: "trash.md", reason: "obsolete" }], report: "I dreamed on 2026-09-19." }; const r = run(h, ["--force", "--dreamer", dreamer(h, m)]); assert.equal(r.status, 0, r.stderr); const merged = readFileSync(join(h, "pi/session/dream/a.md"), "utf8"); assert.match(merged, "one"); assert.match(merged, "two"); assert.match(merged, "recurrence_count: 1"); assert.match(readFileSync(join(h, "pi/session/dream/b.md"), "utf8"), "status: superseded"); assert.equal(existsSync(join(h, "pi/session/dream/trash.md")), false); const trash = readdirSync(join(h, "trash"))[0]; assert.equal(readFileSync(join(h, "trash", trash, "session", "trash.md"), "utf8").includes("gone"), true); const reports = readdirSync(join(h, "dreams")); const report = readFileSync(join(h, "dreams", reports[0]), "utf8"); assert.match(report, "I dreamed"); assert.match(report, "proposal: promote"); assert.match(report, "trashed"); });
-test("invalid manifest path makes zero writes and exits nonzero", () => { const h = fixture(); note(h, "s1", "a.md", "one", "w"); const before = readFileSync(join(h, "pi/session/s1/a.md"), "utf8"); const r = run(h, ["--force", "--dreamer", dreamer(h, { merge: [{ into: "missing.md", from: ["a.md"] }], report: "bad" })]); assert.notEqual(r.status, 0); assert.match(r.stderr, "missing.md"); assert.equal(readFileSync(join(h, "pi/session/s1/a.md"), "utf8"), before); assert.equal(existsSync(join(h, "dreams")), false); });
-test("failed run restores prior lock mtime", () => { const h = fixture(); const lock = join(h, ".dream.lock"); writeFileSync(lock, "999999"); const prior = Date.now() - 48 * 3600_000; utimesSync(lock, new Date(prior), new Date(prior)); const r = run(h, ["--force", "--dreamer", dreamer(h, { merge: [{ into: "missing", from: [] }], report: "x" })]); assert.notEqual(r.status, 0); assert.ok(Math.abs(statSync(lock).mtimeMs - prior) < 2000); });
-test("SDK dreamer captures assistant event and receives read-only allowlist", async () => {
+test("time and material gates preserve skip decisions and reasons", () => {
+    const home = fixture();
+    const lock = join(home, ".dream.lock");
+    writeFileSync(lock, "999999");
+    const fresh = timeGate(lock, 24);
+    assert.equal(fresh.ok, false);
+    assert.equal(fresh.reason, "time gate: lock is too fresh");
+    old(lock);
+    assert.deepEqual(timeGate(lock, 24).ok, true);
+    mkdirSync(join(home, "pi/session/one"), { recursive: true });
+    writeFileSync(join(home, "pi/session/one/a.md"), "a");
+    const material = materialGate(home, statSync(lock).mtimeMs, 1);
+    assert.equal(material.ok, true);
+    assert.match(material.reason, /material gate: 1 changed sessions/);
+    assert.equal(materialGate(home, Date.now(), 2).ok, false);
+});
+test("live lock is excluded, dead lock is reclaimed, and failures restore mtime", () => {
+    const home = fixture();
+    const lock = join(home, ".dream.lock");
+    writeFileSync(lock, String(process.pid));
+    const live = acquireLock(lock);
+    assert.equal(live.held, false);
+    assert.equal(live.reason, "lock gate: live process holds the lock");
+    writeFileSync(lock, "999999");
+    old(lock);
+    const prior = statSync(lock).mtimeMs;
+    const reclaimed = acquireLock(lock);
+    assert.equal(reclaimed.held, true);
+    utimesSync(lock, new Date(), new Date());
+    failLock(reclaimed);
+    assert.ok(Math.abs(statSync(lock).mtimeMs - prior) < 2000);
+});
+test("dreamer write jail accepts home files and refuses escapes", async () => {
+    const home = fixture();
+    const tools = new Map(dreamerWriteToolDefinitions(home).map((tool) => [tool.name, tool]));
+    const ctx = { cwd: home };
+    await tools.get("write").execute("write", { path: "global/x.md", content: "one" }, undefined, undefined, ctx);
+    assert.equal(readFileSync(join(home, "global/x.md"), "utf8"), "one");
+    const rejectsOutsideHome = async (tool, path) => {
+        const params = tool === "write" ? { path, content: "outside" } : { path, edits: [{ oldText: "one", newText: "outside" }] };
+        await assert.rejects(() => tools.get(tool).execute("escape", params, undefined, undefined, ctx), (error) => error.message.includes(home));
+    };
+    for (const tool of ["write", "edit"]) {
+        await rejectsOutsideHome(tool, "/tmp/dream-jail-outside.md");
+        await rejectsOutsideHome(tool, "../dream-jail-outside.md");
+    }
+    const outside = fixture();
+    symlinkSync(outside, join(home, "escape"));
+    await rejectsOutsideHome("write", "escape/outside.md");
+    await rejectsOutsideHome("edit", "escape/outside.md");
+    assert.equal(existsSync(join(outside, "outside.md")), false, "the jail does not write through an in-home symlink");
+    const outsideFile = join(outside, "outside.md");
+    writeFileSync(outsideFile, "outside");
+    symlinkSync(outsideFile, join(home, "global/outside-link.md"));
+    await rejectsOutsideHome("write", "global/outside-link.md");
+    assert.equal(readFileSync(outsideFile, "utf8"), "outside", "the jail does not write through a symlinked file outside home");
+    linkSync(outsideFile, join(home, "global/hardlink.md"));
+    await rejectsOutsideHome("write", "global/hardlink.md");
+    assert.equal(readFileSync(outsideFile, "utf8"), "outside", "the jail does not write through a hardlinked file outside home");
+    const insideFile = join(home, "global/inside.md");
+    writeFileSync(insideFile, "inside");
+    symlinkSync(insideFile, join(home, "global/inside-link.md"));
+    await tools.get("write").execute("write", { path: "global/inside-link.md", content: "updated" }, undefined, undefined, ctx);
+    assert.equal(readFileSync(insideFile, "utf8"), "updated", "the jail permits a symlinked file that resolves inside home");
+});
+test("dreamer allowlist contains only the file tools and reports their writes", async () => {
     let configured = [];
-    const session = { subscribe(handler) { this.handler = handler; return () => { }; }, handler: (_event) => { }, async prompt(_text) { this.handler({ type: "message_end", message: { role: "assistant", content: [{ type: "text", text: '{"report":"stub"}' }] } }); }, dispose() { } };
-    const manifest = await runDreamer("playbook", "/tmp/notes", { sessionFactory: async (options) => { configured = options.tools; return session; } });
-    assert.deepEqual(manifest, { report: "stub" });
-    assert.deepEqual(configured, READ_ONLY_TOOLS);
-    assert.equal(configured.includes("notes_write"), false);
-    assert.equal(configured.includes("notes_edit"), false);
-});
-test("SDK dreamer surfaces provider stopReason error instead of manifest-parse lie", async () => {
-    const session = { subscribe(handler) { this.handler = handler; return () => { }; }, handler: (_event) => { }, async prompt(_text) { this.handler({ type: "message_end", message: { role: "assistant", content: [], stopReason: "error", errorMessage: "402: {\"error\":{\"message\":\"Insufficient Balance\"}}" } }); }, dispose() { } };
-    await assert.rejects(() => runDreamer("playbook", "/tmp/notes", { sessionFactory: async () => session }), /Insufficient Balance/);
-    await assert.rejects(() => runDreamer("playbook", "/tmp/notes", { sessionFactory: async () => session }), /402/);
+    const session = {
+        subscribe(handler) { this.handler = handler; return () => { }; },
+        handler: (_event) => { },
+        async prompt(_text) { this.handler({ type: "tool_execution_start", toolName: "write", args: { path: "global/a.md", content: "a" } }); this.handler({ type: "tool_execution_start", toolName: "edit", args: { path: "project/p.md", edits: [] } }); this.handler({ type: "message_end", message: { role: "assistant", content: [{ type: "text", text: "done" }, { type: "text", text: "again" }] } }); },
+        dispose() { },
+    };
+    const result = await runDreamer("playbook", "/tmp/notes", { sessionFactory: async (options) => { configured = options.tools; return session; } });
+    assert.deepEqual(configured, DREAMER_TOOLS);
+    assert.deepEqual(configured, ["read", "grep", "find", "ls", "write", "edit"]);
+    assert.equal(configured.some((tool) => tool.startsWith("notes_")), false);
+    assert.deepEqual(result.writes, [{ tool: "write", path: "global/a.md" }, { tool: "edit", path: "project/p.md" }]);
+    assert.equal(result.report, "done\nagain");
+    assert.equal(result.report, contentText([{ type: "text", text: "done" }, { type: "text", text: "again" }]), "dream and history share the text projection");
+});
+test("dreamer session has exactly the jailed file-tool allowlist", async () => {
+    const session = await defaultDreamerSessionFactory({ cwd: fixture(), tools: DREAMER_TOOLS });
+    try {
+        assert.deepEqual(session.agent.state.tools.map((tool) => tool.name).sort(), [...DREAMER_TOOLS].sort());
+    }
+    finally {
+        session.dispose();
+    }
 });
-test("SDK dreamer parse failure keeps existing manifest message without provider error", async () => {
-    const session = { subscribe(handler) { this.handler = handler; return () => { }; }, handler: (_event) => { }, async prompt(_text) { this.handler({ type: "message_end", message: { role: "assistant", content: [{ type: "text", text: "sorry, I could not do that" }] } }); }, dispose() { } };
-    await assert.rejects(() => runDreamer("playbook", "/tmp/notes", { sessionFactory: async () => session }), /did not return a valid JSON manifest/);
+test("playbook describes plain files and the retained frontmatter", () => {
+    const playbook = readFileSync(join(process.cwd(), "playbook.md"), "utf8");
+    assert.equal(playbook.includes("notes_"), false);
+    for (const field of ["origin", "status", "stale", "created_at", "updated_at", "last_accessed", "access_count"])
+        assert.match(playbook, new RegExp(`^${field}:`, "m"));
+    assert.equal(/^scope:/m.test(playbook), false, "scope is derived from the address rather than persisted");
+    assert.match(playbook, /Nothing is physically deleted/);
+});
+test("provider errors propagate without parsing a response", async () => {
+    const session = {
+        subscribe(handler) { this.handler = handler; return () => { }; },
+        handler: (_event) => { },
+        async prompt(_text) { this.handler({ type: "message_end", message: { role: "assistant", stopReason: "error", errorMessage: "Insufficient Balance" } }); },
+        dispose() { },
+    };
+    await assert.rejects(() => runDreamer("playbook", "/tmp/notes", { sessionFactory: async () => session }), /Insufficient Balance/);
 });
 test("default dreamer rejects an unresolvable model pattern", async () => {
-    await assert.rejects(() => defaultDreamerSessionFactory({ cwd: "/tmp/notes", modelPattern: "definitely-not-a-real-model", tools: READ_ONLY_TOOLS }), /definitely-not-a-real-model/);
+    await assert.rejects(() => defaultDreamerSessionFactory({ cwd: "/tmp/notes", modelPattern: "definitely-not-a-real-model", tools: DREAMER_TOOLS }), /definitely-not-a-real-model/);
+});
+test("git audit layer commits baseline and dream, stays silent when clean, keeps file content", () => {
+    const home = fixture();
+    writeFileSync(join(home, "a.md"), "one");
+    gitCommit(home, "baseline t");
+    gitCommit(home, "dream t"); // clean tree — no empty commit
+    const log1 = execFileSync("git", ["log", "--format=%s"], { cwd: home, encoding: "utf8" }).trim();
+    assert.equal(log1, "baseline t");
+    writeFileSync(join(home, "a.md"), "two");
+    gitCommit(home, "dream t2");
+    const log2 = execFileSync("git", ["log", "--format=%s"], { cwd: home, encoding: "utf8" }).trim();
+    assert.equal(log2, "dream t2\nbaseline t");
+    assert.equal(readFileSync(join(home, "a.md"), "utf8"), "two"); // notes themselves untouched by the layer
+    const before = execFileSync("git", ["show", "HEAD~1:a.md"], { cwd: home, encoding: "utf8" }).trim();
+    assert.equal(before, "one"); // rollback information actually recorded
+});
+test("git audit layer never breaks the run when git itself fails", () => {
+    gitCommit(join(fixture(), "missing", "home"), "x"); // init on a missing cwd throws inside — swallowed
 });

package/dist/test/history.test.js

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import test from "node:test";
-import { resetV2WindowId, visibleItem } from "../src/history.js";
+import { contentText, resetV2WindowId, rootWindowId, visibleItem } from "../src/history.js";
 test("visibleItem reports a plain fitting prefix and names the full length", () => {
     const item = visibleItem({ windowId: "w", itemId: "i", role: "user", content: "abcdef", createdAt: undefined }, 4);
     assert.equal(Array.from(item.truncated_content).length, 4);
@@ -19,3 +19,8 @@ test("persisted reset IDs are opaque within the supported protocol version", ()
     assert.equal(resetV2WindowId({ piContext: "reset-v2", windowId: 123 }), undefined);
     assert.equal(resetV2WindowId(null), undefined);
 });
+test("text content projection and root window IDs have stable shared forms", () => {
+    const content = [{ type: "text", text: "first" }, { type: "toolCall", name: "ignored" }, { type: "text", text: "second" }];
+    assert.equal(contentText(content), "first\nsecond");
+    assert.equal(rootWindowId("12345678-abcd"), "pcw:12345678:root");
+});

package/dist/test/integration.test.js

@@ -5,9 +5,10 @@ import { dirname, join } from "node:path";
 import test from "node:test";
 import { AgentSession, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
 import piContext, { historyFromSession, internal } from "../src/index.js";
-import { localIso } from "../src/notes.js";
-import { physicalPath } from "../src/memory/paths.js";
-import { listNotes } from "../src/memory/store.js";
+import { bootBlock } from "../src/prompts.js";
+import { localIso } from "../src/notes/model.js";
+import { physicalPath } from "../src/notes/paths.js";
+import { listNotes } from "../src/notes/store.js";
 import { middleTruncate, page, TOOL_OUTPUT_MAX_BYTES } from "../src/tool-output.js";
 // Settings fixtures live in temp directories. PI_CODING_AGENT_DIR is redirected for the
 // whole test process so the extension's SettingsManager.create(ctx.cwd, undefined, ...)
@@ -109,12 +110,41 @@ function noticesOf(ctx) {
 export async function call(captured, name, params, ctx) {
     const tool = captured.tools.get(name);
     assert.ok(tool, `registered ${name}`);
+    // Most pre-redesign coverage names session notes by their bare address. Keep these old
+    // fixture call sites readable while routing the direct tool invocation through its new
+    // address-shaped input; contract-specific tests below pass address themselves.
+    const noteCall = name === "notes_write" || name === "notes_edit" || name === "notes_read";
+    if (noteCall && "path" in params && !("address" in params)) {
+        const { path, scope, ...rest } = params;
+        assert.equal(typeof path, "string", "legacy note fixture path is a string");
+        const address = scope === "project" ? `@project/${path}` : scope === "global" ? `@global/${path}` : path;
+        return tool.execute("call-1", { ...rest, address }, new AbortController().signal, () => { }, ctx);
+    }
+    if ((name === "notes_list" || name === "notes_search") && params.scope === "global") {
+        const { scope: _scope, pattern, ...rest } = params;
+        return tool.execute("call-1", { ...rest, pattern: `@global/${typeof pattern === "string" ? pattern : "**"}` }, new AbortController().signal, () => { }, ctx);
+    }
+    if ((name === "notes_list" || name === "notes_search") && params.scope === "session") {
+        const { scope: _scope, pattern, ...rest } = params;
+        return tool.execute("call-1", { ...rest, pattern: typeof pattern === "string" ? pattern : "*.md" }, new AbortController().signal, () => { }, ctx);
+    }
     return tool.execute("call-1", params, new AbortController().signal, () => { }, ctx);
 }
 export function resultJson(result) {
     const text = result.content[0];
     assert.ok(text && text.type === "text", "tool result carries text");
-    return JSON.parse(text.text);
+    const value = JSON.parse(text.text);
+    const suffix = (address) => address.startsWith("@project/") ? address.slice("@project/".length) : address.startsWith("@global/") ? address.slice("@global/".length) : address;
+    const legacyPath = (row) => {
+        if (typeof row.address === "string" && row.path === undefined)
+            Object.defineProperty(row, "path", { value: suffix(row.address), enumerable: false });
+    };
+    legacyPath(value);
+    if (Array.isArray(value.files))
+        for (const file of value.files)
+            if (file && typeof file === "object")
+                legacyPath(file);
+    return value;
 }
 /** Assert the delivered wire text fits the tool-output budget, header included for raw reads. */
 export function assertWithinBudget(result, message) {
@@ -247,11 +277,13 @@ test("schemas cover the History/Notes actions plus reset controls", () => {
     // The write surface requires its body; the edit surface requires its anchors.
     const writeSchema = captured.tools.get("notes_write")?.parameters;
     assert.ok(writeSchema?.properties?.content, "notes_write exposes content");
-    assert.ok(writeSchema?.properties?.path, "notes_write exposes path");
-    assert.deepEqual([...(writeSchema?.required ?? [])].sort(), ["content", "path"], "notes_write requires path and content");
+    assert.ok(writeSchema?.properties?.address, "notes_write exposes address");
+    assert.equal(writeSchema?.properties?.scope, undefined, "notes_write has no scope parameter");
+    assert.deepEqual([...(writeSchema?.required ?? [])].sort(), ["address", "content"], "notes_write requires address and content");
     const editSchema = captured.tools.get("notes_edit")?.parameters;
     assert.ok(editSchema?.properties?.edits, "notes_edit exposes edits");
-    assert.deepEqual([...(editSchema?.required ?? [])].sort(), ["path"], "notes_edit requires only path; edits are optional for metadata-only updates");
+    assert.equal(editSchema?.properties?.scope, undefined, "notes_edit has no scope parameter");
+    assert.deepEqual([...(editSchema?.required ?? [])].sort(), ["address"], "notes_edit requires only address; edits are optional for metadata-only updates");
     // The history ordering switch is documented as newest-first by default.
     for (const name of ["history_windows", "history_list", "history_search"]) {
         const schema = captured.tools.get(name)?.parameters;
@@ -270,7 +302,12 @@ test("schemas cover the History/Notes actions plus reset controls", () => {
         assert.equal(schema?.properties?.limit_chars?.maximum, 50000, `${name} caps limit_chars at 50000`);
     }
     const noteReadSchema = captured.tools.get("notes_read")?.parameters;
-    assert.deepEqual(Object.keys(noteReadSchema?.properties ?? {}).sort(), ["limit_chars", "offset_chars", "path", "scope"], "notes_read exposes exactly the character-window params plus scope");
+    assert.deepEqual(Object.keys(noteReadSchema?.properties ?? {}).sort(), ["address", "limit_chars", "offset_chars"], "notes_read exposes exactly address and character-window params");
+    for (const name of ["notes_write", "notes_edit", "notes_read", "notes_list", "notes_search"]) {
+        const schema = captured.tools.get(name)?.parameters;
+        assert.equal(schema?.properties?.scope, undefined, `${name} has no scope property`);
+        assert.equal(schema?.additionalProperties, false, `${name} rejects scope as an additional property`);
+    }
     assert.equal(/start_|stop_line|total_lines/.test(captured.tools.get("notes_read")?.description ?? ""), false, "notes_read prose carries no line surface");
 });
 test("notes_list is most-recently-updated first across merged scopes", async () => {
@@ -288,11 +325,11 @@ test("notes_list is most-recently-updated first across merged scopes", async ()
     put("project", "c.md", base + 5);
     put("global", "e.md", base + 20);
     const files = async (params) => resultJson(await call(captured, "notes_list", params, ctx)).files;
-    assert.deepEqual((await files({})).map((file) => file.path), ["e.md", "a.md", "b.md", "c.md"], "updated_at descending with path ascending as the tiebreak");
+    assert.deepEqual((await files({})).map((file) => file.address), ["@global/e.md", "a.md", "b.md", "@project/c.md"], "updated_at descending with address ascending as the tiebreak");
     // A same-path pair in two scopes keeps both rows; equal timestamps tie-break by scope name.
     put("global", "a.md", base + 10);
-    assert.deepEqual((await files({})).filter((file) => file.path === "a.md").map((file) => file.scope), ["global", "session"], "equal timestamps tie-break by scope name");
-    assert.deepEqual((await files({ scope: "session" })).map((file) => file.path), ["a.md", "b.md"], "a scope filter narrows the set");
+    assert.deepEqual((await files({})).filter((file) => file.address.endsWith("a.md")).map((file) => file.scope), ["global", "session"], "equal timestamps tie-break by full address");
+    assert.deepEqual((await files({ pattern: "*.md" })).map((file) => file.address), ["a.md", "b.md"], "a bare pattern narrows to the session home");
 });
 test("notes are real files that persist across sessions and round-trip Unicode", async () => {
     const original = manager();
@@ -306,7 +343,7 @@ test("notes are real files that persist across sessions and round-trip Unicode",
     const restoredCtx = context(restored);
     const rawRead = await call(restoredCaptured, "notes_read", { path: "checkpoint/进度.md", scope: "global", offset_chars: -4 }, restoredCtx);
     const read = resultRead(rawRead);
-    assert.equal(read.details.path, "checkpoint/进度.md");
+    assert.equal(read.details.address, "@global/checkpoint/进度.md");
     assert.equal(read.content, "Café", "a negative offset reads the body tail in one call");
     assert.equal(read.details.scope, "global");
     const searched = resultJson(await call(restoredCaptured, "notes_search", { query: "Café", scope: "global" }, restoredCtx));
@@ -354,7 +391,7 @@ test("the boot notes index excludes stale notes while list, read, and search sti
     const text = typeof boot?.message.content === "string" ? boot.message.content : "";
     assert.ok(text.includes("fresh.md"), "the fresh note is indexed");
     assert.equal(text.includes("old.md"), false, "the stale note leaves the boot index");
-    assert.equal(text.includes("stale content"), false, "the stale preview is not rendered");
+    assert.equal(text.includes("stale content"), false, "the stale note's body is absent from boot");
     const listed = resultJson(await call(captured, "notes_list", {}, ctx));
     assert.equal(listed.files.find((file) => file.path === "old.md")?.stale, true, "list carries the stale flag");
     assert.equal(listed.files.find((file) => file.path === "fresh.md")?.stale, false);
@@ -372,9 +409,30 @@ test("the boot notes index omits itself when every note is stale", async () => {
     runHandlers(captured, "session_start", {}, ctx);
     const text = typeof captured.sent[0]?.message.content === "string" ? captured.sent[0].message.content : "";
     assert.equal(text.includes("done.md"), false, "no stale note is indexed");
-    assert.equal(text.includes("finished"), false, "no stale preview is rendered");
+    assert.equal(text.includes("finished"), false, "the stale note's body is absent from boot");
     assert.ok(text.includes(internal.CONTEXT_WINDOW_PROTOCOL_OPEN_TAG), "the rest of the boot block still renders");
 });
+test("the boot block gives awake agents the notes-home file layout", () => {
+    const session = manager();
+    const rendered = bootBlock(context(session), "pcw:test:root", undefined, false);
+    assert.equal(rendered.includes(process.env.PI_NOTES_HOME ?? ""), false, "the absolute notes home is never exposed");
+    assert.match(rendered, /bare <vpath>.*@project\/<vpath>.*@global\/<vpath>/);
+    assert.match(rendered, /there is no cross-home fallback/);
+    assert.match(rendered, /Any other note is a plain file — use the file tools/);
+});
+test("the boot block keeps fresh global and project maps resident, never a session map", async () => {
+    const session = manager();
+    const captured = makeExtension(session);
+    const ctx = context(session);
+    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: "@global/MAP.md", content: "MAP: global" }, ctx);
+    const rendered = bootBlock(ctx, "pcw:test:root", undefined, false);
+    assert.ok(rendered.includes("MAP: global"));
+    assert.ok(rendered.includes("MAP: project"));
+    assert.equal(rendered.includes("MAP: session"), false);
+    assert.ok(rendered.indexOf("MAP: global") < rendered.indexOf("MAP: project"), "global map precedes project map");
+});
 test("paged tool outputs stay bounded and cursors reconstruct history and notes", async () => {
     const session = manager();
     const captured = makeExtension(session);
@@ -636,8 +694,8 @@ test("an over-budget note is delivered as a prefix and resumed by next_offset_ch
     assert.ok(first.content.length > 0, "the page is not empty");
     assert.equal(first.content.includes("…"), false, "the payload is a plain prefix with no marker");
     assert.ok(first.content.startsWith("---\n"), "the frontmatter is delivered first");
-    assert.equal(first.header, `[huge.md · chars 0-${first.next_offset_chars} of ${first.total_chars} · continue at offset_chars=${first.next_offset_chars} · session · created ${String(first.details.created_at)} · updated ${String(first.details.updated_at)}]`, "the raw header names the file, the delivered range, the resume cursor, the scope and the timestamps");
-    assert.deepEqual(Object.keys(first.details).sort(), ["created_at", "limit_chars", "next_offset_chars", "offset_chars", "path", "scope", "total_chars", "updated_at"], "notes_read details carries exactly the slim window metadata plus scope");
+    assert.equal(first.header, `[huge.md · chars 0-${first.next_offset_chars} of ${first.total_chars} · continue at offset_chars=${first.next_offset_chars} · session · created ${String(first.details.created_at)} · updated ${String(first.details.updated_at)}]`, "the raw header names the address, delivered range, resume cursor, scope and timestamps");
+    assert.deepEqual(Object.keys(first.details).sort(), ["address", "created_at", "limit_chars", "next_offset_chars", "offset_chars", "scope", "total_chars", "updated_at"], "notes_read details carries exactly the slim window metadata plus scope");
     assert.equal("content" in first.details, false, "details never duplicates the payload");
     assert.equal(first.offset_chars, 0, "the default window starts at the resolved offset 0");
     // Following the cursor reconstructs frontmatter + body by plain concatenation.
@@ -655,7 +713,7 @@ test("an over-budget note is delivered as a prefix and resumed by next_offset_ch
     // 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 missing = resultJson(missingResult);
-    assert.deepEqual(Object.keys(missing).sort(), ["error", "path"], "the read error carries exactly error and path");
+    assert.deepEqual(Object.keys(missing).sort(), ["address", "error"], "the read error carries exactly error and address");
     assert.equal(missing.error, "note not found");
     assert.equal(missingResult.details, undefined, "a JSON error carries no details metadata");
 });
@@ -937,11 +995,10 @@ test("custom reset boundary removes old provider context but history remains sea
     assert.equal(found.items[0]?.item_id, oldUserId);
     assert.ok(sessionManager.getEntry(compactionId));
 });
-test("the boot notes preview keeps short notes whole and long notes head-to-tail", async () => {
+test("the boot notes index shows one metadata line per note and never a body", async () => {
     const sessionManager = manager();
     const captured = makeExtension(sessionManager);
     const ctx = context(sessionManager);
-    // Unique Unicode code points so an overlap introduced by a naive head+tail concat is detectable.
     const longText = Array.from({ length: 400 }, (_, index) => String.fromCharCode(0x4e00 + index)).join("");
     const shortText = "short-first\nshort-second";
     await call(captured, "notes_write", { path: "long.md", content: longText }, ctx);
@@ -950,19 +1007,11 @@ test("the boot notes preview keeps short notes whole and long notes head-to-tail
     const boot = captured.sent[0];
     const text = typeof boot?.message.content === "string" ? boot.message.content : "";
     assert.ok(text.includes("long.md") && text.includes("short.md"), "both notes are indexed");
-    // Short note: complete, with its newline preserved and each line indented 2 spaces.
-    assert.ok(text.includes("  short-first\n  short-second"), "short note text is shown whole and indented");
-    // Long note preview: exactly first 80 + separator + last 240 Unicode characters.
-    const chars = Array.from(longText);
-    const head = chars.slice(0, 80).join("");
-    const tail = chars.slice(chars.length - 240).join("");
-    const previewLine = text.split("\n").find((line) => line.startsWith("  ") && line.includes("…"));
-    assert.ok(previewLine, "long note carries an ellipsis preview line");
-    const preview = Array.from(previewLine.slice(2));
-    assert.ok(previewLine.includes(head), "long preview keeps the head");
-    assert.ok(previewLine.includes(tail), "long preview keeps the tail");
-    assert.equal(preview.length, 321, "head 80 + one separator + tail 240, nothing duplicated");
-    assert.equal(previewLine.includes(longText), false, "long note is truncated, not shown whole");
+    // Each note is exactly one metadata line: address, line count, byte count, timestamp.
+    assert.match(text, /^- long\.md \(1 lines, \d+ UTF-8 bytes, updated [^)]+\)$/m, "the long note is a single metadata line");
+    assert.match(text, /^- short\.md \(2 lines, \d+ UTF-8 bytes, updated [^)]+\)$/m, "the short note is a single metadata line");
+    assert.equal(text.includes(longText), false, "the long note's body never reaches boot");
+    assert.equal(text.includes(shortText), false, "the short note's body never reaches boot");
 });
 test("the boot block is persisted at the root and baked into every reset summary", async () => {
     const sessionManager = manager();
@@ -1584,7 +1633,8 @@ test("malformed frontmatter timestamps degrade to a finite fallback without pois
     assert.ok(Number.isFinite(rows[0].meta.updated_at), "a malformed timestamp degrades to a finite fallback");
     runHandlers(extension, "session_start", {}, ctx);
     const rendered = JSON.stringify(extension.sent);
-    assert.ok(rendered.includes("keep me"), "the valid body still renders");
+    assert.ok(rendered.includes("good.md"), "the valid note still renders as a metadata line");
+    assert.equal(rendered.includes("keep me"), false, "note bodies stay out of the boot block");
     assert.equal(rendered.includes("NaN"), false, "no malformed timestamp leaks into the boot block");
 });
 test("JSONL reload retains once-per-window boot and reminder without runtime memory", () => {
@@ -1663,7 +1713,7 @@ test("argument footguns die loudly and tool-run metadata surfaces (A1/A2/A3/B4/B
     assert.match(notePastEnd.error ?? "", /past the end/, "notes: past-end offset is a named error");
     assert.equal(notePastEnd.offset_chars, noteTotal + 1, "notes: the error echoes the offending offset");
     assert.equal(notePastEnd.total_chars, noteTotal, "notes: the error names the real length");
-    assert.equal(notePastEnd.path, "a.md", "notes: the error echoes the path");
+    assert.equal(notePastEnd.address, "a.md", "notes: the error echoes the address");
     const noteEnd = resultRead(await call(captured, "notes_read", { path: "a.md", offset_chars: noteTotal }, ctx));
     assert.equal(noteEnd.content, "", "notes: offset == total is the legal empty end-read");
     assert.equal(noteEnd.next_offset_chars, null, "notes: the end-read terminates");