@astrosheep/pi-context 0.21.0 → 0.22.1

package/src/dream/git.ts

@@ -1,27 +1,73 @@
 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";
 
 /**
- * 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.
+ * Outcome of one audit commit. `ok: true` always carries a real `commit` snapshot;
+ * `empty: true` only means no files changed (an empty baseline commit or no commit was
+ * needed). `ok: false` means the audit layer could not guarantee a snapshot.
  */
-export function gitCommit(home: string, message: string): void {
+export type AuditResult =
+	| { ok: true; commit: string; empty: boolean }
+	| { ok: false; error: string };
+
+/** 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: string): void {
+	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`. 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: string, message: string): AuditResult {
 	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
-		} catch { /* staged changes exist — fall through to commit */ }
-		execFileSync("git", ["commit", "-q", "-m", message], { cwd: home, stdio: "ignore" });
-		console.log(`git: committed "${message}"`);
+			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}"`);
+		} 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: string): string | undefined {
+	try {
+		const head = execFileSync("git", ["rev-parse", "HEAD"], { cwd: home, encoding: "utf8" }).trim();
+		return head.length > 0 ? head : undefined;
+	} catch { return undefined; }
+}

package/src/dream/lock.ts

@@ -1,39 +1,82 @@
-import { existsSync, readFileSync, statSync, unlinkSync, utimesSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { readFileSync, statSync, unlinkSync, utimesSync, writeFileSync } from "node:fs";
 
-export type LockState = { path: string; held: boolean; reason?: string; startedAt: number; priorMtime?: number };
-const HOUR = 60 * 60 * 1000;
+export type LockState = {
+	path: string;
+	held: boolean;
+	reason?: string;
+	startedAt: number;
+	/** mtime of the last-run sidecar before this run took the lock; failLock restores it. */
+	priorStampMtime?: number;
+	/** Random identity written into the lock file; cleanup only removes the lock it wrote. */
+	token?: string;
+};
 
-function live(pid: number): boolean {
-	if (!Number.isInteger(pid) || pid <= 0) return false;
-	try { process.kill(pid, 0); return true; } catch { return false; }
+/**
+ * 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: string): string {
+	return `${lockPath}.last-run`;
 }
 
+function readText(path: string): string | undefined {
+	try { return readFileSync(path, "utf8"); } catch { return undefined; }
+}
+
+function stampMtime(stampPath: string): number | undefined {
+	try { return statSync(stampPath).mtimeMs; } catch { return undefined; }
+}
+
+/**
+ * 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: LockState): boolean {
+	if (!lock.held || !lock.token) return false;
+	return readText(lock.path)?.trim() === `${process.pid} ${lock.token}`;
+}
+
+/**
+ * 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: string): LockState {
 	const now = Date.now();
-	let priorMtime: number | undefined;
-	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 }; }
+	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 };
 	}
-	writeFileSync(path, String(process.pid), { flag: "wx" });
-	return { path, held: true, startedAt: now, priorMtime };
+	// Only a held lock advances the scheduler timestamp.
+	try { 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: LockState): void {
-	// 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.
-}
-
-export function restoreMtime(path: string, mtimeMs: number): void {
-	try { utimesSync(path, new Date(), new Date(mtimeMs)); } catch { /* advisory */ }
+	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: LockState): void {
 	if (!lock.held) return;
-	if (lock.priorMtime === undefined) { try { unlinkSync(lock.path); } catch { /* best effort */ } }
-	else restoreMtime(lock.path, lock.priorMtime);
+	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 */ }
+	}
+	lock.held = false;
 }

package/src/dream/runner.ts

@@ -6,7 +6,7 @@ import type { Api, Model } from "@earendil-works/pi-ai";
 import { contentText } from "../history.js";
 
 export type DreamWrite = { tool: "write" | "edit"; path: string };
-export type DreamResult = { report: string; writes: DreamWrite[] };
+export type DreamResult = { report: string; writes: DreamWrite[]; error?: string };
 export type DreamerSession = Pick<AgentSession, "prompt" | "subscribe" | "dispose">;
 export type DreamerSessionFactory = (options: { cwd: string; modelPattern?: string; tools: string[] }) => Promise<DreamerSession>;
 export const DREAMER_TOOLS = ["read", "grep", "find", "ls", "write", "edit"];
@@ -85,6 +85,11 @@ export const defaultDreamerSessionFactory: DreamerSessionFactory = async ({ cwd,
 	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: string, cwd: string, options: { modelPattern?: string; sessionFactory?: DreamerSessionFactory } = {}): Promise<DreamResult> {
 	const session = await (options.sessionFactory ?? defaultDreamerSessionFactory)({ cwd, modelPattern: options.modelPattern, tools: DREAMER_TOOLS });
 	let answer = "";
@@ -99,8 +104,12 @@ export async function runDreamer(playbook: string, cwd: string, options: { model
 		answer = contentText(event.message.content);
 	});
 	try {
-		await session.prompt(playbook);
-		if (providerError) throw new Error(`dreamer failed: ${providerError}`);
+		try {
+			await session.prompt(playbook);
+		} catch (error) {
+			return { report: answer, writes, error: error instanceof Error ? error.message : String(error) };
+		}
+		if (providerError) return { report: answer, writes, error: `dreamer failed: ${providerError}` };
 		return { report: answer, writes };
 	} finally {
 		unsubscribe?.();

package/src/notes/address.ts

@@ -3,7 +3,7 @@ import type { Scope } from "./paths.js";
 
 export type NoteAddress = { scope: Scope; path: string };
 
-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
@@ -16,9 +16,9 @@ export function assertAddress(value: unknown): NoteAddress {
 	if (value.startsWith("@project/")) {
 		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/src/notes/frontmatter.ts

@@ -25,7 +25,7 @@ export type NoteMeta = {
 	[key: string]: unknown;
 };
 
-const SCOPES: readonly Scope[] = ["session", "project", "global"];
+const SCOPES: readonly Scope[] = ["session", "project", "personal"];
 const ORIGINS: readonly Origin[] = ["user", "self", "external"];
 const STATUSES: readonly NoteStatus[] = ["active", "superseded", "pending", "archived"];
 const TIMESTAMP_KEYS = ["created_at", "updated_at", "last_accessed"] as const;
@@ -112,7 +112,7 @@ function parseFrontmatter(raw: string): { fields: Record<string, unknown>; body:
 export function parseNote(raw: string, now = Date.now()): { meta: NoteMeta; body: string } {
 	const { fields, body } = parseFrontmatter(raw);
 	const meta = { ...fields } as Record<string, unknown>;
-	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/src/notes/paths.ts

@@ -4,7 +4,7 @@ import { homedir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
-export type Scope = "session" | "project" | "global";
+export type Scope = "session" | "project" | "personal";
 
 /** Physical home of the on-disk note store: $PI_NOTES_HOME or ~/.agents/notes. */
 export function notesRoot(): string {
@@ -46,7 +46,7 @@ function sessionId(ctx: ExtensionContext): string {
 
 /** Absolute directory holding every note of one scope. */
 export function scopeDir(scope: Scope, ctx: ExtensionContext): string {
-	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/src/notes/store.ts

@@ -32,10 +32,10 @@ export type NoteRow = { address: string; scope: Scope; path: string; meta: NoteM
 export type NoteMatch = { line: number; text: string; offsetChars: number };
 export type NoteSearchRow = { address: string; scope: Scope; path: string; meta: NoteMeta; matches: NoteMatch[] };
 
-const SCOPE_ORDER: readonly Scope[] = ["session", "project", "global"];
+const SCOPE_ORDER: readonly Scope[] = ["session", "project", "personal"];
 
 function assertScope(value: unknown): Scope {
-	if (!isScope(value)) throw new NoteError("invalid_scope", `scope must be one of session, project, global (got ${JSON.stringify(value)})`);
+	if (!isScope(value)) throw new NoteError("invalid_scope", `scope must be one of session, project, personal (got ${JSON.stringify(value)})`);
 	return value;
 }
 

package/src/notes/tools.ts

@@ -10,7 +10,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: NoteMeta): Record<string, unknown> {
 	return { ...meta, created_at: localIso(meta.created_at), updated_at: localIso(meta.updated_at), last_accessed: localIso(meta.last_accessed) };

package/src/prompts.ts

@@ -1,8 +1,7 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 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: string, firstWindowId: string, currentWindowId: string, previousWindowId?: string): string {
@@ -15,36 +14,45 @@ function identityBlock(agentName: string, firstWindowId: string, currentWindowId
 	return `${CONTEXT_WINDOW_OPEN_TAG}\n${lines.join("\n")}\n${CONTEXT_WINDOW_CLOSE_TAG}`;
 }
 
+function relativeTime(timestamp: number, now: number): string {
+	const seconds = Math.trunc((timestamp - now) / 1000);
+	const [unit, size] = ([["d", 86400], ["h", 3600], ["m", 60], ["s", 1]] as const)
+		.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: ExtensionContext): string {
 	const sections: string[] = [];
 	// 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"] as const) {
+	for (const scope of ["personal", "project"] as const) {
 		const toc = listNotes(ctx, { scope }).find((row) => row.path === "MAP.md");
 		if (toc && !toc.meta.stale) {
 			if (toc.body.length > 0) sections.push(toc.body);
 		}
 	}
 	// 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"));
 	}
@@ -52,7 +60,7 @@ function notesIndex(ctx: ExtensionContext): string {
 }
 
 function notesHomeBlock(): string {
-	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.";
 }
 
 /**

package/src/protocol.ts

@@ -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;
 /**
@@ -49,11 +51,10 @@ 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 =

package/src/thresholds.ts

@@ -1,8 +1,8 @@
 import { SettingsManager, type ExtensionContext } 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";
 
 export type ResolvedThresholds = { reminder: number; reserve: number; warning: number };
-type PiContextMargins = { reminderMarginTokens?: unknown };
+type PiContextSettings = { reminderMarginTokens?: unknown; dreamer?: unknown };
 
 function isSettingsObject(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -16,9 +16,9 @@ function piContextSettings(settings: unknown): Record<string, unknown> {
 }
 
 /** Merge the global and project "pi-context" objects per key; project wins, mirroring Pi's deep merge. */
-export function mergePiContextSettings(globalSettings: unknown, projectSettings: unknown): PiContextMargins {
+export function mergePiContextSettings(globalSettings: unknown, projectSettings: unknown): PiContextSettings {
 	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. */
@@ -33,7 +33,7 @@ function validMargin(raw: unknown): number | undefined {
  * An invalid margin degrades to the default and reports one warning. Pi's automatic
  * threshold/overflow compaction itself resets immediately, with no model turn.
  */
-export function deriveThresholds(reserveTokens: number, margins: PiContextMargins): { thresholds: ResolvedThresholds; warnings: string[] } {
+export function deriveThresholds(reserveTokens: number, margins: PiContextSettings): { thresholds: ResolvedThresholds; warnings: string[] } {
 	const warnings: string[] = [];
 	const reminderKey = `${PI_CONTEXT_SETTINGS_KEY}.reminderMarginTokens`;
 	let reminderMargin: number;
@@ -48,6 +48,35 @@ export function deriveThresholds(reserveTokens: number, margins: PiContextMargin
 	return { thresholds: { reminder: reserveTokens + reminderMargin, reserve: reserveTokens, warning: reserveTokens + WARNING_RUNWAY_TOKENS }, warnings };
 }
 
+export type DreamerSetting = { pattern?: string; warnings: string[] };
+
+/**
+ * `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: PiContextSettings): DreamerSetting {
+	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()): DreamerSetting {
+	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: ResolvedThresholds | undefined;
 
 /**