@astrosheep/pi-context 0.21.0 → 0.22.0

package/dist/test/integration.test.js

@@ -117,12 +117,12 @@ export async function call(captured, name, params, ctx) {
     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;
+        const address = scope === "project" ? `@project/${path}` : scope === "personal" ? `@personal/${path}` : path;
         return tool.execute("call-1", { ...rest, address }, new AbortController().signal, () => { }, ctx);
     }
-    if ((name === "notes_list" || name === "notes_search") && params.scope === "global") {
+    if ((name === "notes_list" || name === "notes_search") && params.scope === "personal") {
         const { scope: _scope, pattern, ...rest } = params;
-        return tool.execute("call-1", { ...rest, pattern: `@global/${typeof pattern === "string" ? pattern : "**"}` }, new AbortController().signal, () => { }, ctx);
+        return tool.execute("call-1", { ...rest, pattern: `@personal/${typeof pattern === "string" ? pattern : "**"}` }, new AbortController().signal, () => { }, ctx);
     }
     if ((name === "notes_list" || name === "notes_search") && params.scope === "session") {
         const { scope: _scope, pattern, ...rest } = params;
@@ -134,7 +134,7 @@ export function resultJson(result) {
     const text = result.content[0];
     assert.ok(text && text.type === "text", "tool result carries text");
     const value = JSON.parse(text.text);
-    const suffix = (address) => address.startsWith("@project/") ? address.slice("@project/".length) : address.startsWith("@global/") ? address.slice("@global/".length) : address;
+    const suffix = (address) => address.startsWith("@project/") ? address.slice("@project/".length) : address.startsWith("@personal/") ? address.slice("@personal/".length) : address;
     const legacyPath = (row) => {
         if (typeof row.address === "string" && row.path === undefined)
             Object.defineProperty(row, "path", { value: suffix(row.address), enumerable: false });
@@ -323,36 +323,36 @@ test("notes_list is most-recently-updated first across merged scopes", async ()
     put("session", "b.md", base + 10);
     put("session", "a.md", base + 10);
     put("project", "c.md", base + 5);
-    put("global", "e.md", base + 20);
+    put("personal", "e.md", base + 20);
     const files = async (params) => resultJson(await call(captured, "notes_list", params, ctx)).files;
-    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");
+    assert.deepEqual((await files({})).map((file) => file.address), ["@personal/e.md", "a.md", "b.md", "@project/c.md"], "updated_at descending with address ascending as the tiebreak");
     // A same-path pair in two scopes keeps both rows; equal timestamps tie-break by scope name.
-    put("global", "a.md", base + 10);
-    assert.deepEqual((await files({})).filter((file) => file.address.endsWith("a.md")).map((file) => file.scope), ["global", "session"], "equal timestamps tie-break by full address");
+    put("personal", "a.md", base + 10);
+    assert.deepEqual((await files({})).filter((file) => file.address.endsWith("a.md")).map((file) => file.scope), ["personal", "session"], "equal timestamps tie-break by full address");
     assert.deepEqual((await files({ 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();
     const captured = makeExtension(original);
     const ctx = context(original);
-    await call(captured, "notes_write", { path: "checkpoint/进度.md", content: "第一行\nneedle Café", scope: "global" }, ctx);
-    // A brand-new session over the same physical root sees the global note: nothing is replayed
+    await call(captured, "notes_write", { path: "checkpoint/进度.md", content: "第一行\nneedle Café", scope: "personal" }, ctx);
+    // A brand-new session over the same physical root sees the personal 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: "global", offset_chars: -4 }, restoredCtx);
+    const rawRead = await call(restoredCaptured, "notes_read", { path: "checkpoint/进度.md", scope: "personal", offset_chars: -4 }, restoredCtx);
     const read = resultRead(rawRead);
-    assert.equal(read.details.address, "@global/checkpoint/进度.md");
+    assert.equal(read.details.address, "@personal/checkpoint/进度.md");
     assert.equal(read.content, "Café", "a negative offset reads the body tail in one call");
-    assert.equal(read.details.scope, "global");
-    const searched = resultJson(await call(restoredCaptured, "notes_search", { query: "Café", scope: "global" }, restoredCtx));
+    assert.equal(read.details.scope, "personal");
+    const searched = resultJson(await call(restoredCaptured, "notes_search", { query: "Café", scope: "personal" }, restoredCtx));
     assert.equal(searched.files[0]?.matches[0]?.line, 2);
-    const listedFiles = resultJson(await call(restoredCaptured, "notes_list", { pattern: "checkpoint/**", scope: "global" }, restoredCtx));
+    const listedFiles = resultJson(await call(restoredCaptured, "notes_list", { pattern: "checkpoint/**", scope: "personal" }, restoredCtx));
     assert.equal(listedFiles.files.length, 1, "glob ** crosses into the checkpoint directory");
     assert.equal(listedFiles.files[0]?.path, "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: "global" }, restoredCtx));
+    const rootOnly = resultJson(await call(restoredCaptured, "notes_list", { pattern: "*", scope: "personal" }, restoredCtx));
     assert.equal(rootOnly.files.length, 0, "glob * stays within one segment");
     assert.equal(searched.files[0]?.created_at, listedFiles.files[0]?.created_at, "note tools agree on the timestamp format");
     assert.equal(searched.files[0]?.updated_at, listedFiles.files[0]?.updated_at);
@@ -380,6 +380,17 @@ test("stale lifecycle: writes and metadata-only edits close and revive a note",
     const missing = resultJson(await call(captured, "notes_edit", { path: "missing.md", stale: true }, ctx));
     assert.equal(missing.error, "note not found");
 });
+test("notes tools stay usable while a dream holds the lock", async () => {
+    // A live dream lock is not a general lock: the awake notes tools never consult it.
+    writeFileSync(join(process.env.PI_NOTES_HOME, ".dream.lock"), String(process.pid));
+    const sm = manager();
+    const captured = makeExtension(sm);
+    const ctx = context(sm);
+    const written = resultJson(await call(captured, "notes_write", { path: "during-dream.md", content: "awake" }, ctx));
+    assert.equal(written.address, "during-dream.md");
+    const edited = resultJson(await call(captured, "notes_edit", { path: "during-dream.md", edits: [{ oldText: "awake", newText: "still awake" }] }, ctx));
+    assert.equal(edited.applied, 1, "notes_edit still applies while a dream lock is held");
+});
 test("the boot notes index excludes stale notes while list, read, and search still see them", async () => {
     const sm = manager();
     const captured = makeExtension(sm);
@@ -416,22 +427,22 @@ 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, /bare <vpath>.*@project\/<vpath>.*@personal\/<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 () => {
+test("the boot block keeps fresh personal 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);
+    await call(captured, "notes_write", { address: "@personal/MAP.md", content: "MAP: personal" }, ctx);
     const rendered = bootBlock(ctx, "pcw:test:root", undefined, false);
-    assert.ok(rendered.includes("MAP: global"));
+    assert.ok(rendered.includes("MAP: personal"));
     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");
+    assert.ok(rendered.indexOf("MAP: personal") < rendered.indexOf("MAP: project"), "personal map precedes project map");
 });
 test("paged tool outputs stay bounded and cursors reconstruct history and notes", async () => {
     const session = manager();
@@ -1035,8 +1046,7 @@ test("the boot block is persisted at the root and baked into every reset summary
     assert.ok(rootText.includes("decisions.md"));
     const decisionsMeta = listNotes(ctx, { scope: "session" }).find((row) => row.path === "decisions.md")?.meta;
     assert.ok(decisionsMeta);
-    const bootUpdated = assertIsoTimestamp(rootText, "note metadata carries an updated timestamp");
-    assert.equal(Date.parse(bootUpdated), decisionsMeta.updated_at, "boot note timestamp restores the persisted updatedAt");
+    assert.match(rootText, /updated \d+s ago\)/, "boot note metadata carries a relative update time");
     assert.ok(rootText.includes(internal.CONTEXT_WINDOW_PROTOCOL_OPEN_TAG));
     // Reset: the boot block IS the compaction summary; no separate boot/hint is persisted.
     await call(captured, "new_context", {}, ctx);
@@ -1050,8 +1060,8 @@ test("the boot block is persisted at the root and baked into every reset summary
     assert.equal(before.compaction.summary.startsWith(internal.CONTEXT_WINDOW_OPEN_TAG), false, "a reset line precedes the identity block");
     assert.match(before.compaction.summary, new RegExp(`Current context window id: ${details.windowId}`));
     assert.ok(before.compaction.summary.includes("decisions.md"));
-    const resetUpdated = assertIsoTimestamp(before.compaction.summary, "reset summary keeps the note updated timestamp");
-    assert.equal(Date.parse(resetUpdated), decisionsMeta.updated_at, "reset summary keeps the persisted updatedAt");
+    assert.match(before.compaction.summary, /updated \d+s ago\)/, "reset summary carries a relative update time");
+    assert.equal(listNotes(ctx, { scope: "session" }).find((row) => row.path === "decisions.md")?.meta.updated_at, decisionsMeta.updated_at, "rendering relative time preserves the stored timestamp");
     assert.ok(before.compaction.summary.includes(internal.CONTEXT_WINDOW_PROTOCOL_OPEN_TAG));
     const windows = historyFromSession(ctx);
     assert.ok(before.compaction.summary.includes(`Previous context window id: ${windows[windows.length - 1]?.windowId}`));

package/dist/test/notes.test.js

@@ -62,7 +62,7 @@ test("write lands a real markdown file with harness frontmatter and a pure body"
     }
     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");
@@ -210,17 +210,17 @@ test.skip("scope resolution and movement are superseded by explicit address test
     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");
@@ -228,11 +228,11 @@ test.skip("scope resolution and movement are superseded by explicit address test
     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();
@@ -241,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);
@@ -276,12 +276,12 @@ 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, "the stale note's body is absent from boot");
     for (const name of ["notes_write", "notes_edit", "notes_read", "notes_search", "notes_list"]) {
@@ -356,31 +356,31 @@ 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("fresh global and project MAP.md bodies are both resident before the pocket", 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", { 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\nMAP: second" }, 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"), "the global map is injected");
+    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: global") < boot.indexOf("MAP: project"), "the global map precedes the project map");
+    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("the boot pocket applies per-home quotas in session, project, global order", 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);
     const base = Date.parse("2026-01-01T00:00:00.000Z");
-    for (const [scope, count] of [["session", 6], ["project", 3], ["global", 3]]) {
+    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);
@@ -389,21 +389,21 @@ test("the boot pocket applies per-home quotas in session, project, global order"
     }
     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);
+    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.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 global). 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", "@global/global-2.md", "@global/global-1.md"]) {
+    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", "@global/global-0.md", "MAP.md", "MAP: session"]) {
+    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("@global/global-2.md") < boot.indexOf("@global/global-1.md"), "global 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("@global/global-2.md"), "project notes precede global 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-"));
@@ -421,54 +421,54 @@ test("@ addresses select one home, reject illegal sigils, and never fall back",
     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: "@global/same.md", content: "global" }, 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("global", "same.md", ctx)), "@global writes to the global 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\/.*@global\/.*bare names are the session home/);
-    await assert.rejects(() => call(captured, "notes_write", { address: "bad@name.md", content: "no" }, ctx), /@project\/.*@global\/.*bare names are the session home/);
-    assert.equal(existsSync(join(root, "global", "bad@name.md")), false, "a bad sigil creates nothing anywhere");
+    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; legacy scope is read then dropped", async () => {
+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: "@global/global.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(), ["@global/global.md", "@project/project.md", "root.md"]);
+    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: "@global/global.md" }, ctx));
-    assert.match(read.header, /^\[@global\/global\.md /, "the raw read header echoes the full address");
+    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: global\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");
+    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 global maps are skipped independently", async () => {
+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: "@global/MAP.md", content: "global stale", stale: true }, 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 global map");
-    assert.equal(boot.includes("global stale"), false, "the stale global map is skipped");
+    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: "@global/MAP.md", stale: false }, 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("global stale"), "a fresh global map survives a stale project map");
+    assert.ok(boot.includes("personal stale"), "a fresh personal map survives a stale project map");
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/pi-context",
-  "version": "0.21.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",

package/playbook.md

@@ -2,7 +2,7 @@ I am dreaming over my notes. They are plain markdown files in three homes, addre
 
 - bare `<vpath>` for this session
 - `@project/<vpath>` for this project
-- `@global/<vpath>` for global notes
+- `@personal/<vpath>` for personal notes
 
 Every note has this frontmatter block:
 
@@ -23,10 +23,10 @@ access_count: 0
 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 `@global/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, global. 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.
+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 `@global/<vpath>`. Keep notes compact and preserve useful provenance in the body.
+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/dream/cli.ts

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
-import { existsSync, mkdirSync, statSync, writeFileSync } from "node:fs";
+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 { 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; }
@@ -13,21 +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 <model pattern>] [--playbook <path>]\nDefault dreamer: in-process pi SDK session with jailed file tools. Default playbook: <installed package root>/playbook.md; --playbook overrides it."); 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 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;
+	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`);
-	gitCommit(home, `baseline ${stamp}`);
+	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 result = await runDreamer(playbook, home, { modelPattern: a.dreamer ? String(a.dreamer) : undefined });
-		const writes = result.writes.length ? result.writes.map((w) => `- ${w.tool}: ${w.path}`).join("\n") : "- no changes";
-		mkdirSync(join(home, "dreams"), { recursive: true }); writeFileSync(reportPath, `# Dream ${stamp}\n\n${result.report}\n\n${writes}\n`); gitCommit(home, `dream ${stamp}`); 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; });

package/src/dream/gates.ts

@@ -3,18 +3,24 @@ import { join } from "node:path";
 import { sessionHomesRoot } from "../notes/paths.js";
 
 export type GateResult = { ok: boolean; reason: string };
-export function timeGate(lockPath: string, minHours: number, now = Date.now()): GateResult {
-	if (!existsSync(lockPath)) return { ok: true, reason: "time gate: no prior lock" };
-	const age = now - statSync(lockPath).mtimeMs;
-	return age >= minHours * 3600000 ? { ok: true, reason: "time gate: stale" } : { ok: false, reason: "time gate: lock is too fresh" };
+
+/**
+ * The scheduler reads the last-run sidecar, not the lock: the lock's lifetime says
+ * nothing about when the last dream ran, while the sidecar records exactly that.
+ */
+export function timeGate(stampPath: string, minHours: number, now = Date.now()): GateResult {
+	if (!existsSync(stampPath)) return { ok: true, reason: "time gate: no prior dream" };
+	const age = now - statSync(stampPath).mtimeMs;
+	return age >= minHours * 3600000 ? { ok: true, reason: "time gate: stale" } : { ok: false, reason: "time gate: last dream is too recent" };
 }
-export function materialGate(home: string, lockMtime: number, minSessions: number): GateResult {
+
+export function materialGate(home: string, sinceMtime: number, minSessions: number): GateResult {
 	const root = sessionHomesRoot(home);
 	let changed = 0;
 	if (existsSync(root)) for (const dir of readdirSync(root, { withFileTypes: true })) {
 		if (!dir.isDirectory()) continue;
 		const files = readdirSync(join(root, dir.name), { withFileTypes: true });
-		if (files.some((f) => f.isFile() && statSync(join(root, dir.name, f.name)).mtimeMs > lockMtime)) changed++;
+		if (files.some((f) => f.isFile() && statSync(join(root, dir.name, f.name)).mtimeMs > sinceMtime)) changed++;
 	}
 	return changed >= minSessions ? { ok: true, reason: `material gate: ${changed} changed sessions` } : { ok: false, reason: `material gate: only ${changed} changed sessions` };
 }