@astrosheep/pi-context 0.21.0 → 0.22.1

package/dist/src/notes/address.js

@@ -1,5 +1,5 @@
 import { assertVirtualPath } from "./model.js";
-const ADDRESS_FORMS = "legal prefixes are @project/ and @global/; bare names are the session home";
+const ADDRESS_FORMS = "legal prefixes are @project/ and @personal/; bare names are the session home";
 /**
  * Decode the one public note address into its physical home and virtual path. This is a
  * tool-boundary rule: replay paths keep using assertVirtualPath directly and are untouched.
@@ -13,9 +13,9 @@ export function assertAddress(value) {
         scope = "project";
         path = value.slice("@project/".length);
     }
-    else if (value.startsWith("@global/")) {
-        scope = "global";
-        path = value.slice("@global/".length);
+    else if (value.startsWith("@personal/")) {
+        scope = "personal";
+        path = value.slice("@personal/".length);
     }
     else if (value.startsWith("@")) {
         throw new Error(`invalid note address: ${ADDRESS_FORMS}`);

package/dist/src/notes/frontmatter.js

@@ -1,5 +1,5 @@
 import { localIso } from "./model.js";
-const SCOPES = ["session", "project", "global"];
+const SCOPES = ["session", "project", "personal"];
 const ORIGINS = ["user", "self", "external"];
 const STATUSES = ["active", "superseded", "pending", "archived"];
 const TIMESTAMP_KEYS = ["created_at", "updated_at", "last_accessed"];
@@ -89,7 +89,7 @@ function parseFrontmatter(raw) {
 export function parseNote(raw, now = Date.now()) {
     const { fields, body } = parseFrontmatter(raw);
     const meta = { ...fields };
-    meta.scope = isScope(meta.scope) ? meta.scope : "global";
+    meta.scope = isScope(meta.scope) ? meta.scope : "personal";
     meta.origin = isOrigin(meta.origin) ? meta.origin : "self";
     meta.status = isStatus(meta.status) ? meta.status : "active";
     meta.stale = meta.stale === true;

package/dist/src/notes/paths.js

@@ -39,8 +39,8 @@ function sessionId(ctx) {
 }
 /** Absolute directory holding every note of one scope. */
 export function scopeDir(scope, ctx) {
-    if (scope === "global")
-        return join(notesRoot(), "global");
+    if (scope === "personal")
+        return join(notesRoot(), "personal");
     if (scope === "project")
         return join(notesRoot(), "project", projectKey(ctx.cwd));
     return join(sessionHomesRoot(), sessionId(ctx));

package/dist/src/notes/store.js

@@ -21,10 +21,10 @@ export class NoteError extends Error {
         this.edit_index = extra.edit_index;
     }
 }
-const SCOPE_ORDER = ["session", "project", "global"];
+const SCOPE_ORDER = ["session", "project", "personal"];
 function assertScope(value) {
     if (!isScope(value))
-        throw new NoteError("invalid_scope", `scope must be one of session, project, global (got ${JSON.stringify(value)})`);
+        throw new NoteError("invalid_scope", `scope must be one of session, project, personal (got ${JSON.stringify(value)})`);
     return value;
 }
 function assertOrigin(value) {

package/dist/src/notes/tools.js

@@ -9,7 +9,7 @@ import { NoteError, editNote, listNotes, readNote, searchNotes, writeNote } from
 const ORIGIN = Type.Optional(Type.Union([Type.Literal("user"), Type.Literal("self"), Type.Literal("external")], {
     description: "Where the note's content came from. user: written or dictated by the human. self: written by you, the agent (default). external: anything else — third-party text, tool output, fetched material.",
 }));
-const ADDRESS_DESCRIPTION = "Address forms are bare `<vpath>` for this session, `@project/<vpath>` for this project's home, and `@global/<vpath>` for the global home. `@` means leaving home. Any other `@` prefix, or `@` inside a vpath, is a hard error: legal prefixes are `@project/` and `@global/`; bare names are the session home. There is no cross-home fallback. Paths reject `..`, absolute paths, and backslashes.";
+const ADDRESS_DESCRIPTION = "Address forms are bare `<vpath>` for this session, `@project/<vpath>` for this project's home, and `@personal/<vpath>` for the human's cross-project home. `@` means leaving home. Any other `@` prefix, or `@` inside a vpath, is a hard error: legal prefixes are `@project/` and `@personal/`; bare names are the session home. There is no cross-home fallback. Paths reject `..`, absolute paths, and backslashes.";
 function wireMeta(meta) {
     return { ...meta, created_at: localIso(meta.created_at), updated_at: localIso(meta.updated_at), last_accessed: localIso(meta.last_accessed) };
 }

package/dist/src/prompts.js

@@ -1,7 +1,6 @@
 import { historyFromSession } from "./history.js";
-import { localIso } from "./notes/model.js";
 import { listNotes } from "./notes/store.js";
-import { CONTEXT_WINDOW_OPEN_TAG, CONTEXT_WINDOW_CLOSE_TAG, POCKET_GLOBAL_LIMIT, POCKET_PROJECT_LIMIT, POCKET_SESSION_LIMIT, RESET_SUMMARY, PROTOCOL_BLOCK, GUIDANCE_OPEN_TAG, GUIDANCE_CLOSE_TAG } from "./protocol.js";
+import { CONTEXT_WINDOW_OPEN_TAG, CONTEXT_WINDOW_CLOSE_TAG, POCKET_PERSONAL_LIMIT, POCKET_PROJECT_LIMIT, POCKET_SESSION_LIMIT, RESET_SUMMARY, PROTOCOL_BLOCK, GUIDANCE_OPEN_TAG, GUIDANCE_CLOSE_TAG } from "./protocol.js";
 /** Codex-style <context_window> identity block: agent name and first/current/previous window ids only. */
 function identityBlock(agentName, firstWindowId, currentWindowId, previousWindowId) {
     const lines = [
@@ -13,20 +12,27 @@ function identityBlock(agentName, firstWindowId, currentWindowId, previousWindow
         lines.push(`Previous context window id: ${previousWindowId}`);
     return `${CONTEXT_WINDOW_OPEN_TAG}\n${lines.join("\n")}\n${CONTEXT_WINDOW_CLOSE_TAG}`;
 }
+function relativeTime(timestamp, now) {
+    const seconds = Math.trunc((timestamp - now) / 1000);
+    const [unit, size] = [["d", 86400], ["h", 3600], ["m", 60], ["s", 1]]
+        .find(([unit, size]) => Math.abs(seconds) >= size || unit === "s");
+    const amount = `${Math.abs(Math.trunc(seconds / size))}${unit}`;
+    return seconds > 0 ? `in ${amount}` : `${amount} ago`;
+}
 /**
- * Boot notes index. Map residency ("地图在场"): fresh MAP.md bodies from the global and
+ * Boot notes index. Map residency ("地图在场"): fresh MAP.md bodies from the personal and
  * project homes are both injected, broadest first; stale maps are skipped per home, and the
  * session home is never peeked — a session MAP.md is an ordinary note. The pocket then lists
  * recent fresh notes under per-home quotas (POCKET_SESSION_LIMIT / POCKET_PROJECT_LIMIT /
- * POCKET_GLOBAL_LIMIT), most-recently-updated first within each home, one metadata line
- * each: address, line count, UTF-8 byte count, local ISO update time. Bodies never render
+ * POCKET_PERSONAL_LIMIT), most-recently-updated first within each home, one metadata line
+ * each: address, line count, UTF-8 byte count, relative update time at window open. Bodies never render
  * in the pocket; stale notes are excluded; MAP.md itself never takes a pocket seat.
  */
 function notesIndex(ctx) {
     const sections = [];
     // Map residency ("地图在场"): scope-native maps, both fresh ones injected broadest-first.
     // A session MAP.md is an ordinary note, never resident; stale maps skip independently.
-    for (const scope of ["global", "project"]) {
+    for (const scope of ["personal", "project"]) {
         const toc = listNotes(ctx, { scope }).find((row) => row.path === "MAP.md");
         if (toc && !toc.meta.stale) {
             if (toc.body.length > 0)
@@ -34,23 +40,24 @@ function notesIndex(ctx) {
         }
     }
     // listNotes is most-recently-updated first within each home. Per-home quotas keep session
-    // churn from evicting project or global notes; maps never take pocket seats.
+    // churn from evicting project or personal notes; maps never take pocket seats.
     const recentNotes = [
         ...listNotes(ctx, { scope: "session" }).filter((row) => !row.meta.stale && row.path !== "MAP.md").slice(0, POCKET_SESSION_LIMIT),
         ...listNotes(ctx, { scope: "project" }).filter((row) => !row.meta.stale && row.path !== "MAP.md").slice(0, POCKET_PROJECT_LIMIT),
-        ...listNotes(ctx, { scope: "global" }).filter((row) => !row.meta.stale && row.path !== "MAP.md").slice(0, POCKET_GLOBAL_LIMIT),
+        ...listNotes(ctx, { scope: "personal" }).filter((row) => !row.meta.stale && row.path !== "MAP.md").slice(0, POCKET_PERSONAL_LIMIT),
     ];
     if (recentNotes.length > 0) {
-        const lines = [`You find ${recentNotes.length} crumpled note${recentNotes.length === 1 ? "" : "s"} in your pocket (by home, most recent first within each: up to ${POCKET_SESSION_LIMIT} from this session, ${POCKET_PROJECT_LIMIT} from this project, ${POCKET_GLOBAL_LIMIT} from global). A note's content never appears here, so its name has to say what the note is about:`];
+        const lines = [`You find ${recentNotes.length} crumpled note${recentNotes.length === 1 ? "" : "s"} in your pocket (by home, most recent first within each: up to ${POCKET_SESSION_LIMIT} from this session, ${POCKET_PROJECT_LIMIT} from this project, ${POCKET_PERSONAL_LIMIT} from personal). A note's content never appears here, so its name has to say what the note is about:`];
+        const now = Date.now();
         for (const row of recentNotes) {
-            lines.push(`- ${row.address} (${row.body.split("\n").length} lines, ${row.sizeBytes} UTF-8 bytes, updated ${localIso(row.meta.updated_at)})`);
+            lines.push(`- ${row.address} (${row.body.split("\n").length} lines, ${row.sizeBytes} UTF-8 bytes, updated ${relativeTime(row.meta.updated_at, now)})`);
         }
         sections.push(lines.join("\n"));
     }
     return sections.join("\n\n");
 }
 function notesHomeBlock() {
-    return "Notes_* addresses have three homes: bare <vpath> is this session, @project/<vpath> is this project, and @global/<vpath> is global. @ means leaving home; there is no cross-home fallback. Any other note is a plain file — use the file tools.";
+    return "Notes_* addresses have three homes: bare <vpath> is this session, @project/<vpath> is this project, and @personal/<vpath> is the human's cross-project home. @ means leaving home; there is no cross-home fallback. Any other note is a plain file — use the file tools.";
 }
 /**
  * Assemble the static, once-per-window boot block: the reset line for resets, the

package/dist/src/protocol.js

@@ -9,7 +9,7 @@ export const RESET_V2 = "reset-v2";
 export const MAX_NOTE_BYTES = 1_000_000;
 export const POCKET_SESSION_LIMIT = 5;
 export const POCKET_PROJECT_LIMIT = 2;
-export const POCKET_GLOBAL_LIMIT = 2;
+export const POCKET_PERSONAL_LIMIT = 2;
 // Write-time cap on a virtual note path. Deliberately NOT enforced by assertVirtualPath:
 // notesFromSession replays already-persisted operations, which must keep loading sessions
 // that contain a longer legacy path. Reads and replay stay un-capped.
@@ -21,6 +21,8 @@ export const CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG = "</context_window_protocol>";
 export const GUIDANCE_OPEN_TAG = "<context_window_guidance>";
 export const GUIDANCE_CLOSE_TAG = "</context_window_guidance>";
 export const PI_CONTEXT_SETTINGS_KEY = "pi-context";
+/** Nested under "pi-context": the default dreamer model pattern, overridden by CLI --dreamer. */
+export const PI_CONTEXT_DREAMER_KEY = "dreamer";
 export const DEFAULT_RESERVE_TOKENS = 16_384;
 export const DEFAULT_REMINDER_MARGIN_TOKENS = 24_576;
 /**
@@ -47,10 +49,9 @@ Use get_context_remaining to see how much of the window is left. When it runs ou
 
 If <context_window> lists a Previous context window id, a reset just happened and the old conversation is not included. Read your note checkpoint first, then recover details through history_*: history_read directly when you know the window and item IDs, history_list or history_search to find them when you don't.
 
-Your notes live in three homes: this session (bare names), this repo (@project/<vpath>), everywhere you go (@global/<vpath>). @ means leaving home — and homes don't visit each other: there is no cross-home fallback.
-Notes carry what exists nowhere else — what the human told you, what you discovered, where you stand.
-Session notes belong to this trip — the goal, the progress, the loose ends, packed for the road. The next window of THIS trip wakes to them; once the trip is over, nobody does.
-@project notes hold what you learned by working here — the things you only know because you were here — for whoever works here next.
-@global notes travel with you. Every window. Every conversation. Every trip. So before you drop anything in there, ask yourself: does this deserve to stare you in the face every single time you talk to the human? No? Then keep your weird junk OUT.
+Your notes live in three homes: this session (bare names), this project (@project/<vpath>), the human across projects (@personal/<vpath>). @ means leaving home — and homes don't visit each other: there is no cross-home fallback.
+Session notes belong to this trip — the goal, the progress, the loose ends. The next window of THIS trip wakes to them; once the trip is over, nobody does.
+@project notes hold facts about this project — architecture, conventions, workflows, deployment and environment details — for whoever works here next.
+@personal notes hold the human's durable preferences and standing rules, plus lessons that apply across projects. Duration does not make a note personal; its stated scope must already be broader than the project or conversation at hand. When the intended scope is unclear, keep the note in the narrowest stated scope rather than widening it.
 ${CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG}`;
 export const WARNING_PROMPT = "Your memory is about to be erased. Write the note. NOW. If it already exists, revise it with notes_edit (or rewrite it whole): the goal, decisions, progress, learnings, next steps, the skills you still need, the window ID and item ID of every relevant user request still being solved, and important actions/tool calls for future reference. Do not continue any task. Then call new_context IMMEDIATELY — anything not in the note dies with the window.";

package/dist/src/thresholds.js

@@ -1,5 +1,5 @@
 import { SettingsManager } from "@earendil-works/pi-coding-agent";
-import { PI_CONTEXT_SETTINGS_KEY, DEFAULT_RESERVE_TOKENS, DEFAULT_REMINDER_MARGIN_TOKENS, WARNING_RUNWAY_TOKENS } from "./protocol.js";
+import { PI_CONTEXT_SETTINGS_KEY, PI_CONTEXT_DREAMER_KEY, DEFAULT_RESERVE_TOKENS, DEFAULT_REMINDER_MARGIN_TOKENS, WARNING_RUNWAY_TOKENS } from "./protocol.js";
 function isSettingsObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -13,7 +13,7 @@ function piContextSettings(settings) {
 /** Merge the global and project "pi-context" objects per key; project wins, mirroring Pi's deep merge. */
 export function mergePiContextSettings(globalSettings, projectSettings) {
     const merged = { ...piContextSettings(globalSettings), ...piContextSettings(projectSettings) };
-    return { reminderMarginTokens: merged.reminderMarginTokens };
+    return { reminderMarginTokens: merged.reminderMarginTokens, dreamer: merged.dreamer };
 }
 /** A margin is usable only as a positive integer; anything else is ignored. */
 function validMargin(raw) {
@@ -44,6 +44,33 @@ export function deriveThresholds(reserveTokens, margins) {
     }
     return { thresholds: { reminder: reserveTokens + reminderMargin, reserve: reserveTokens, warning: reserveTokens + WARNING_RUNWAY_TOKENS }, warnings };
 }
+/**
+ * `pi-context.dreamer` is a non-empty model pattern. Anything else present is ignored
+ * with one warning; absent means no configured pattern, so the automatic model applies.
+ */
+export function deriveDreamer(settings) {
+    const raw = settings.dreamer;
+    if (raw === undefined)
+        return { warnings: [] };
+    if (typeof raw !== "string" || raw.trim().length === 0) {
+        return { warnings: [`pi-context: ${PI_CONTEXT_SETTINGS_KEY}.${PI_CONTEXT_DREAMER_KEY} must be a non-empty string; ignoring it.`] };
+    }
+    return { pattern: raw.trim(), warnings: [] };
+}
+/**
+ * Resolve the configurable dreamer model from Pi settings for a CLI invocation: global
+ * `~/.pi/agent/settings.json` merged with the project's `.pi/settings.json`, project
+ * values winning per key. A settings read failure degrades to no pattern with one warning.
+ */
+export function readDreamerSettings(cwd = process.cwd()) {
+    try {
+        const settingsManager = SettingsManager.create(cwd, undefined, { projectTrusted: true });
+        return deriveDreamer(mergePiContextSettings(settingsManager.getGlobalSettings(), settingsManager.getProjectSettings()));
+    }
+    catch (error) {
+        return { warnings: [`pi-context: could not read settings; using the automatic dreamer model (${String(error)}).`] };
+    }
+}
 let cached;
 /**
  * Session-level threshold resolution: Pi's compaction reserve plus the settings.json

package/dist/test/doctor.test.js

@@ -0,0 +1,44 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, symlinkSync, readdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { doctor } from "../src/dream/doctor.js";
+import { main } from "../src/dream/cli.js";
+const note = (body = "") => `---\norigin: self\nstatus: active\nstale: false\ncreated_at: 2026-01-01T00:00:00Z\nupdated_at: 2026-01-01T00:00:00Z\nlast_accessed: 2026-01-01T00:00:00Z\naccess_count: 0\n---\n\n${body}`;
+const home = () => mkdtempSync(join(tmpdir(), "dream-doctor-"));
+test("doctor validates note homes and references without changing files", async () => {
+    const root = home();
+    mkdirSync(join(root, "personal"));
+    writeFileSync(join(root, "personal/a.md"), note());
+    writeFileSync(join(root, "personal/MAP.md"), note("- `a.md`\n- `@personal/a.md`"));
+    const before = readFileSync(join(root, "personal/a.md"));
+    assert.deepEqual(doctor(root), []);
+    assert.equal(await main(["doctor", "--notes-home", root], { runDreamer: async () => { throw new Error("must not run"); } }), 0);
+    assert.deepEqual(readFileSync(join(root, "personal/a.md")), before);
+    assert.deepEqual(readdirSync(root), ["personal"]);
+});
+test("doctor reports layout, metadata, links and locks; never repairs", () => {
+    const root = home();
+    mkdirSync(join(root, "global"));
+    mkdirSync(join(root, "project/bad"), { recursive: true });
+    writeFileSync(join(root, "project/bad/MAP.md"), note("`missing.md` `@global/old.md`"));
+    writeFileSync(join(root, "project/bad/broken.md"), "---\norigin: nope\n---\n");
+    writeFileSync(join(root, ".dream.lock"), "garbage");
+    symlinkSync(join(root, "project"), join(root, "project/bad/link"));
+    const output = doctor(root).join("\n");
+    for (const expected of ["legacy home", "invalid project key", "target missing", "invalid address", "invalid origin", "invalid created_at", "malformed lock", "symlink"])
+        assert.ok(output.includes(expected), expected);
+    assert.equal(readFileSync(join(root, ".dream.lock"), "utf8"), "garbage");
+    assert.ok(existsSync(join(root, "global")));
+});
+test("doctor reports missing homes without creating them, including CLI", async () => {
+    const missing = join(home(), "absent");
+    assert.equal(await main(["doctor", "--notes-home", missing]), 1);
+    assert.equal(existsSync(missing), false);
+});
+test("doctor reports valid lock presence without claiming it is stale", () => {
+    const root = home();
+    writeFileSync(join(root, ".dream.lock"), "123 12345678-1234-1234-1234-123456789abc");
+    assert.match(doctor(root).join("\n"), /lock present.*liveness not inferred/);
+});