@astrosheep/pi-context 0.21.0 → 0.22.0

package/README.md

@@ -20,7 +20,7 @@ pi -e npm:@astrosheep/pi-context
 - **A boot block at every window head** — static once-per-window content (cache-stable) carrying the window identity, the recent-notes index, and a short protocol that teaches the model how to recover: notes for its own bookkeeping, history tools for everything before the reset.
 - **Low-budget guidance** — one persisted early warning per window when the estimated remaining budget crosses the reminder line, so the model checkpoints before the lights go out.
 - **`get_context_remaining`** — the live, reserve-adjusted estimate of the context budget left before Pi's compaction reserve.
-- **Nine history/notes tools** — Codex's History/Notes actions flattened into Pi's single tool namespace; notes are real markdown files under `~/.agents/notes` (`global/`, `project/`, `pi/session/`):
+- **Nine history/notes tools** — Codex's History/Notes actions flattened into Pi's single tool namespace; notes are real markdown files under `~/.agents/notes` (`personal/`, `project/`, `pi/session/`):
 
 | Codex action | Pi tool |
 | --- | --- |
@@ -51,6 +51,27 @@ The reminder threshold is Pi's compaction reserve plus a margin, configured unde
 
 `reminder = reserveTokens + reminderMarginTokens`; with the defaults the early warning fires 24,576 tokens above Pi's reset line.
 
+The dreamer model is configured under the same key. `--dreamer <model pattern>` on the `dream` CLI wins; otherwise a non-empty `pi-context.dreamer` string from settings applies; otherwise the automatic model is used. An invalid value (empty or not a string) is ignored with one warning.
+
+```json
+{
+  "pi-context": { "reminderMarginTokens": 24576, "dreamer": "anthropic/claude-sonnet-4-5" }
+}
+```
+
+## The dream lock
+
+The `dream` CLI takes an exclusive `.dream.lock` in the notes home with a single O_CREAT|O_EXCL creation. The lock is Git-style existence locking: an existing lock refuses a new run regardless of its contents, PID, or age, and `--force` bypasses only the scheduling and material gates, never the lock. A lock is released only by the run that acquired it (and repeated cleanup is harmless), so a live dream is never displaced.
+
+If a dream process crashed, its lock remains and later runs refuse to start. There is no automatic recovery and no force-unlock command: after you have confirmed that no dream process is running, remove the stale lock by hand.
+
+```sh
+# only when no dream is running
+rm "${PI_NOTES_HOME:-$HOME/.agents/notes}/.dream.lock"
+```
+
+Removing a lock while a holder is running is outside the supported cooperative protocol and can let two dreams run at once.
+
 ## Documentation
 
 Implementation architecture and the reset lifecycle live in [docs/](docs/).

package/dist/src/dream/cli.js

@@ -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 { gitCommit } from "./git.js";
+import { readDreamerSettings } from "../thresholds.js";
 import { notesRoot } from "../notes/paths.js";
 function args(argv) { const out = {}; for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -24,23 +26,65 @@ function packageRoot() {
         dir = parent;
     }
 }
-export async function main(argv = process.argv.slice(2)) {
+function writeList(writes) {
+    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, content) {
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, content);
+        return undefined;
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+}
+function appendText(path, content) {
+    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, stamp, reportPath, failed, body, writes) {
+    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 = {}) {
     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.");
+        console.log("dream --notes-home <dir> [--min-hours 24] [--min-sessions 3] [--force] [--dreamer <model pattern>] [--playbook <path>]\nDreamer model: --dreamer wins, else pi-context.dreamer from settings, else the automatic model. Default playbook: <installed package root>/playbook.md; --playbook overrides it.");
         return 0;
     }
     const home = resolve(String(a["notes-home"] ?? notesRoot()));
     process.env.PI_NOTES_HOME = home;
     mkdirSync(home, { recursive: true });
     const lockPath = join(home, ".dream.lock");
+    const stampPath = lastRunPath(lockPath);
     const minHours = Number(a["min-hours"] ?? 24);
     const minSessions = Number(a["min-sessions"] ?? 3);
-    const time = timeGate(lockPath, minHours);
+    const time = timeGate(stampPath, minHours);
     console.log(time.reason);
     if (!a.force && !time.ok)
         return 0;
-    const material = materialGate(home, existsSync(lockPath) ? statSync(lockPath).mtimeMs : 0, minSessions);
+    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;
@@ -58,26 +102,65 @@ export async function main(argv = process.argv.slice(2)) {
     }
     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;
+        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;
+        let result;
+        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 {
-        releaseLock(lock);
+        // Only the holder's own lock is released; a successor's lock is never touched.
+        if (succeeded)
+            releaseLock(lock);
+        else
+            failLock(lock);
+    }
+}
+function isEntryPoint() {
+    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/dist/src/dream/gates.js

@@ -1,13 +1,17 @@
 import { existsSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { sessionHomesRoot } from "../notes/paths.js";
-export function timeGate(lockPath, minHours, now = Date.now()) {
-    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, minHours, now = Date.now()) {
+    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, lockMtime, minSessions) {
+export function materialGate(home, sinceMtime, minSessions) {
     const root = sessionHomesRoot(home);
     let changed = 0;
     if (existsSync(root))
@@ -15,7 +19,7 @@ export function materialGate(home, lockMtime, minSessions) {
             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))
+            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` };

package/dist/src/dream/git.js

@@ -1,28 +1,71 @@
 import { execFileSync } from "node:child_process";
-import { existsSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+/** Lock runtime artifacts are not notes and must not appear in snapshots or `git status`. */
+const RUNTIME_IGNORE = ".dream.lock*";
+/** Add the runtime-artifact pattern to the repository's local exclude, once. */
+function ensureRuntimeIgnored(home) {
+    try {
+        const exclude = join(home, ".git", "info", "exclude");
+        const current = existsSync(exclude) ? readFileSync(exclude, "utf8") : "";
+        if (current.split(/\r?\n/).includes(RUNTIME_IGNORE))
+            return;
+        mkdirSync(dirname(exclude), { recursive: true });
+        const prefix = current.length > 0 && !current.endsWith("\n") ? `${current}\n` : current;
+        writeFileSync(exclude, `${prefix}${RUNTIME_IGNORE}\n`);
+    }
+    catch { /* best effort: an unignored lock only adds noise to the audit */ }
+}
 /**
- * Git audit layer for a dream run: one commit before (baseline) and one after
- * (dream), so the human gate reviews `git show` instead of trusting a report,
- * and rollback is `git revert`. This layer is a garnish, never load-bearing:
- * every failure is logged and swallowed — a notes home without git, or a
- * broken repo, still dreams. Nothing is committed when the tree is clean.
+ * Git audit layer for a dream run: one commit before (baseline) and one after (dream),
+ * so the human gate reviews `git show` instead of trusting a report, and rollback is
+ * `git revert`. The caller decides how loud a failure is; this function only reports it.
+ * A clean tree on an established repository commits nothing; a repository with no HEAD
+ * gets an empty baseline commit, because an audit run with no snapshot is not a success.
  */
 export function gitCommit(home, message) {
     try {
         if (!existsSync(join(home, ".git"))) {
             execFileSync("git", ["init", "-q"], { cwd: home, stdio: "ignore" });
         }
+        ensureRuntimeIgnored(home);
         execFileSync("git", ["add", "-A"], { cwd: home, stdio: "ignore" });
+        let clean = false;
         try {
             execFileSync("git", ["diff", "--cached", "--quiet"], { cwd: home, stdio: "ignore" });
-            return; // clean tree — no empty commit
+            clean = true; // clean tree — no empty commit on an established repository
+        }
+        catch {
+            clean = false;
+        }
+        const before = headCommit(home);
+        if (!clean) {
+            execFileSync("git", ["commit", "-q", "-m", message], { cwd: home, stdio: "ignore" });
+            console.log(`git: committed "${message}"`);
         }
-        catch { /* staged changes exist — fall through to commit */ }
-        execFileSync("git", ["commit", "-q", "-m", message], { cwd: home, stdio: "ignore" });
-        console.log(`git: committed "${message}"`);
+        else if (before === undefined) {
+            // A newly initialized repository has no snapshot at all; give the audit one.
+            execFileSync("git", ["commit", "-q", "--allow-empty", "-m", message], { cwd: home, stdio: "ignore" });
+            console.log(`git: committed "${message}"`);
+        }
+        const commit = headCommit(home);
+        if (commit === undefined)
+            return { ok: false, error: "audit commit produced no snapshot (no HEAD)" };
+        return { ok: true, commit, empty: clean };
     }
     catch (error) {
-        console.log(`git audit layer skipped: ${error instanceof Error ? error.message : error}`);
+        const reason = error instanceof Error ? error.message : String(error);
+        console.log(`git audit layer failed: ${reason}`);
+        return { ok: false, error: reason };
+    }
+}
+/** HEAD sha, or undefined when the repository has no commit yet. */
+function headCommit(home) {
+    try {
+        const head = execFileSync("git", ["rev-parse", "HEAD"], { cwd: home, encoding: "utf8" }).trim();
+        return head.length > 0 ? head : undefined;
+    }
+    catch {
+        return undefined;
     }
 }

package/dist/src/dream/lock.js

@@ -1,58 +1,99 @@
-import { existsSync, readFileSync, statSync, unlinkSync, utimesSync, writeFileSync } from "node:fs";
-const HOUR = 60 * 60 * 1000;
-function live(pid) {
-    if (!Number.isInteger(pid) || pid <= 0)
-        return false;
+import { randomUUID } from "node:crypto";
+import { readFileSync, statSync, unlinkSync, utimesSync, writeFileSync } from "node:fs";
+/**
+ * The scheduler's last-run timestamp lives in a sidecar beside the lock, never in the
+ * lock file itself: acquiring, releasing or cleaning up the lock touches only the PID
+ * marker, so lock lifecycle does not destroy the timestamp the time gate reads.
+ */
+export function lastRunPath(lockPath) {
+    return `${lockPath}.last-run`;
+}
+function readText(path) {
     try {
-        process.kill(pid, 0);
-        return true;
+        return readFileSync(path, "utf8");
     }
     catch {
-        return false;
+        return undefined;
     }
 }
-export function acquireLock(path) {
-    const now = Date.now();
-    let priorMtime;
-    if (existsSync(path)) {
-        const stat = statSync(path);
-        priorMtime = stat.mtimeMs;
-        let pid = 0;
-        try {
-            pid = Number.parseInt(readFileSync(path, "utf8").trim(), 10);
-        }
-        catch { /* reclaim */ }
-        if (now - stat.mtimeMs <= HOUR && live(pid))
-            return { path, held: false, reason: "lock gate: live process holds the lock", startedAt: now };
-        try {
-            unlinkSync(path);
-        }
-        catch {
-            return { path, held: false, reason: "lock gate: lock could not be reclaimed", startedAt: now };
-        }
+function stampMtime(stampPath) {
+    try {
+        return statSync(stampPath).mtimeMs;
+    }
+    catch {
+        return undefined;
     }
-    writeFileSync(path, String(process.pid), { flag: "wx" });
-    return { path, held: true, startedAt: now, priorMtime };
 }
-export function releaseLock(lock) {
-    // The lock is also the durable last-dream timestamp. Leave the PID marker in place;
-    // the next acquisition reclaims it once the PID is dead or it is older than an hour.
+/**
+ * Cleanup ownership: only the exact marker this run wrote may be removed. The token is
+ * diagnostic and guards cleanup; it never grants permission to take an existing lock.
+ */
+function ownsLock(lock) {
+    if (!lock.held || !lock.token)
+        return false;
+    return readText(lock.path)?.trim() === `${process.pid} ${lock.token}`;
 }
-export function restoreMtime(path, mtimeMs) {
+/**
+ * Acquire the dream lock with Git-style exclusive existence locking: one O_CREAT|O_EXCL
+ * creation. An existing path refuses acquisition regardless of its contents, PID, or age,
+ * and is never read for permission, replaced, or removed. There is no automatic stale
+ * recovery; a crash-left lock is human cleanup after confirming no dream is running.
+ */
+export function acquireLock(path) {
+    const now = Date.now();
+    const priorStampMtime = stampMtime(lastRunPath(path));
+    const token = randomUUID();
+    try {
+        writeFileSync(path, `${process.pid} ${token}`, { flag: "wx" });
+    }
+    catch {
+        return { path, held: false, reason: "lock gate: lock already exists", startedAt: now };
+    }
+    // Only a held lock advances the scheduler timestamp.
     try {
-        utimesSync(path, new Date(), new Date(mtimeMs));
+        writeFileSync(lastRunPath(path), new Date(now).toISOString());
     }
     catch { /* advisory */ }
+    return { path, held: true, startedAt: now, priorStampMtime, token };
+}
+/** Release only the lock this run acquired. Idempotent: repeated cleanup does nothing. */
+export function releaseLock(lock) {
+    if (!lock.held)
+        return;
+    if (ownsLock(lock)) {
+        try {
+            unlinkSync(lock.path);
+        }
+        catch { /* best effort */ }
+    }
+    lock.held = false;
 }
+/**
+ * A failed run must not advance the scheduler: restore the previous timestamp, or remove
+ * the one this run wrote when there was none. Only this run's own marker is removed, and
+ * the state is marked released so a later cleanup attempt is harmless.
+ */
 export function failLock(lock) {
     if (!lock.held)
         return;
-    if (lock.priorMtime === undefined) {
+    if (ownsLock(lock)) {
+        const stampPath = lastRunPath(lock.path);
+        if (lock.priorStampMtime === undefined) {
+            try {
+                unlinkSync(stampPath);
+            }
+            catch { /* best effort */ }
+        }
+        else {
+            try {
+                utimesSync(stampPath, new Date(), new Date(lock.priorStampMtime));
+            }
+            catch { /* best effort */ }
+        }
         try {
             unlinkSync(lock.path);
         }
         catch { /* best effort */ }
     }
-    else
-        restoreMtime(lock.path, lock.priorMtime);
+    lock.held = false;
 }

package/dist/src/dream/runner.js

@@ -83,6 +83,11 @@ export const defaultDreamerSessionFactory = async ({ cwd, modelPattern, tools })
     const { session } = await createAgentSession({ cwd, sessionManager: SessionManager.inMemory(cwd), tools, customTools: dreamerWriteToolDefinitions(cwd), noTools: "all", model, thinkingLevel: "off" });
     return session;
 };
+/**
+ * Run one dream turn. A dreamer failure is returned as `error` together with the partial
+ * writes observed so far, so the caller can record partial state instead of losing it;
+ * only a failure to even start the session throws.
+ */
 export async function runDreamer(playbook, cwd, options = {}) {
     const session = await (options.sessionFactory ?? defaultDreamerSessionFactory)({ cwd, modelPattern: options.modelPattern, tools: DREAMER_TOOLS });
     let answer = "";
@@ -102,9 +107,14 @@ export async function runDreamer(playbook, cwd, options = {}) {
         answer = contentText(event.message.content);
     });
     try {
-        await session.prompt(playbook);
+        try {
+            await session.prompt(playbook);
+        }
+        catch (error) {
+            return { report: answer, writes, error: error instanceof Error ? error.message : String(error) };
+        }
         if (providerError)
-            throw new Error(`dreamer failed: ${providerError}`);
+            return { report: answer, writes, error: `dreamer failed: ${providerError}` };
         return { report: answer, writes };
     }
     finally {

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