@astrosheep/pi-context 0.24.0 → 0.25.1

package/src/context/thresholds.ts

@@ -0,0 +1,78 @@
+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 { mergePiContextSettings, type PiContextSettings } from "../settings.js";
+
+export type ResolvedThresholds = { reminder: number; reserve: number; warning: number };
+/** A margin is usable only as a positive integer; anything else is ignored. */
+function validMargin(raw: unknown): number | undefined {
+	if (typeof raw !== "number" || !Number.isSafeInteger(raw) || raw <= 0) return undefined;
+	return raw;
+}
+
+/**
+ * Pure derivation of the thresholds from Pi's reserve: the reminder fires at reserve
+ * plus the pi-context margin, the warning steer at reserve plus WARNING_RUNWAY_TOKENS.
+ * An invalid margin degrades to the default and reports one warning. Automatic
+ * threshold/overflow handling is represented by reset lifecycle boundary drafts;
+ * no compaction summary is generated.
+ */
+export function deriveThresholds(reserveTokens: number, margins: PiContextSettings): { thresholds: ResolvedThresholds; warnings: string[] } {
+	const warnings: string[] = [];
+	const reminderKey = `${PI_CONTEXT_SETTINGS_KEY}.reminderMarginTokens`;
+	let reminderMargin: number;
+	if (margins.reminderMarginTokens === undefined) reminderMargin = DEFAULT_REMINDER_MARGIN_TOKENS;
+	else {
+		const parsed = validMargin(margins.reminderMarginTokens);
+		if (parsed === undefined) {
+			warnings.push(`pi-context: ${reminderKey} must be a positive integer; using default ${DEFAULT_REMINDER_MARGIN_TOKENS}.`);
+			reminderMargin = DEFAULT_REMINDER_MARGIN_TOKENS;
+		} else reminderMargin = parsed;
+	}
+	return { thresholds: { reminder: reserveTokens + reminderMargin, reserve: reserveTokens, warning: reserveTokens + WARNING_RUNWAY_TOKENS }, warnings };
+}
+
+/**
+ * Read the active compaction reserve, enablement, and pi-context margin settings. This
+ * function deliberately has no cache: the budget owner supplies the invocation-scoped
+ * cache so two live piContext instances cannot share mutable policy state.
+ */
+export type ThresholdSettingsResolution = {
+	thresholds: ResolvedThresholds;
+	automatic: boolean;
+	warnings: string[];
+};
+
+function readThresholdSettingsFromManager(ctx: ExtensionContext, settingsManager: SettingsManager): ThresholdSettingsResolution {
+	// Resolve the active provider/model override from the public settings API.
+	const model = ctx.model;
+	const compaction = settingsManager.getCompactionSettings(model ? { provider: model.provider, id: model.id } : undefined);
+	const derived = deriveThresholds(
+		compaction.reserveTokens,
+		mergePiContextSettings(settingsManager.getGlobalSettings(), settingsManager.getProjectSettings()),
+	);
+	return { thresholds: derived.thresholds, automatic: compaction.enabled, warnings: derived.warnings };
+}
+
+/**
+ * Resolve policy from either the explicitly supplied SDK authority or Pi's default
+ * file-backed settings. The caller owns diagnostics and any lifecycle caching.
+ */
+export function readThresholdSettings(ctx: ExtensionContext, settingsManager?: SettingsManager): ThresholdSettingsResolution {
+	try {
+		if (settingsManager) return readThresholdSettingsFromManager(ctx, settingsManager);
+		return readThresholdSettingsFromManager(
+			ctx,
+			SettingsManager.create(ctx.cwd, undefined, { projectTrusted: ctx.isProjectTrusted() }),
+		);
+	} catch (error) {
+		return {
+			thresholds: {
+				reminder: DEFAULT_RESERVE_TOKENS + DEFAULT_REMINDER_MARGIN_TOKENS,
+				reserve: DEFAULT_RESERVE_TOKENS,
+				warning: DEFAULT_RESERVE_TOKENS + WARNING_RUNWAY_TOKENS,
+			},
+			automatic: true,
+			warnings: [`pi-context: could not read settings; using defaults (${String(error)}).`],
+		};
+	}
+}

package/src/dream/cli.ts

@@ -6,7 +6,7 @@ import { acquireLock, failLock, lastRunPath, releaseLock } from "./lock.js";
 import { materialGate, timeGate } from "./gates.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 { readDreamerSettings, type DreamerSetting } from "./settings.js";
 import { doctor } from "./doctor.js";
 import { notesRoot } from "../notes/paths.js";
 

package/src/dream/doctor.ts

@@ -1,6 +1,7 @@
 import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
 import { basename, join, relative } from "node:path";
-import { assertAddress } from "../notes/address.js";
+import { ADDRESS_FORMS, assertAddress } from "../notes/address.js";
+import { SLUG_PATTERN } from "../notes/paths.js";
 
 /** Read-only diagnostics. Never follows symlinks or acquires/removes a dream lock. */
 export function doctor(home: string): string[] {
@@ -41,10 +42,17 @@ export function doctor(home: string): string[] {
 			if (!address.startsWith("@") && basename(path) !== "MAP.md") continue;
 			try {
 				const parsed = assertAddress(address);
-				const targetHome = parsed.scope === "personal" ? join(home, "personal") : parsed.scope === "project" ? project : root;
+				// Relative homes (@self/, @model/) name whoever is running; a static doctor
+				// cannot resolve them, so only absolute links are checked.
+				if ((parsed.scope === "agent" || parsed.scope === "model") && parsed.who === undefined) continue;
+				const targetHome = parsed.scope === "human" ? join(home, "human")
+					: parsed.scope === "project" ? project
+					: parsed.scope === "agent" ? join(home, "agents", parsed.who!)
+					: parsed.scope === "model" ? join(home, "models", parsed.who!)
+					: root;
 				if (!targetHome) { report(path, `${address}: project context unavailable; use a resolvable reference`); continue; }
 				if (!existsSync(join(targetHome, parsed.path))) report(path, `${address}: target missing; update or remove the reference`);
-			} catch { report(path, `${address}: invalid address; use bare, @project/ or @personal/ addresses`); }
+			} catch { report(path, `${address}: invalid address; ${ADDRESS_FORMS}`); }
 		}
 	};
 	const walk = (dir: string, root: string, project?: string) => {
@@ -64,14 +72,27 @@ export function doctor(home: string): string[] {
 		for (const name of readdirSync(home)) {
 			const path = join(home, name);
 			inspect(path, () => {
-				if (name === "global") { report(path, "legacy home; manually migrate to personal/ without overwriting existing files"); return; }
+				if (name === "global") { report(path, "legacy home; manually migrate to human/ without overwriting existing files"); return; }
+				if (name === "personal") { report(path, "legacy home; migrate to human/ (rename the directory), merging by hand if human/ already exists"); return; }
 				if (name === ".dream.lock") {
 					const valid = lstatSync(path).isFile() && /^[1-9]\d* [\da-f]{8}(?:-[\da-f]{4}){3}-[\da-f]{12}\s*$/i.test(readFileSync(path, "utf8"));
 					report(path, `${valid ? "lock present" : "malformed lock"}; verify no dream is running before manual removal; liveness not inferred`);
 					return;
 				}
 				if ([".git", "dreams", "snapshots", "trash", ".dream.lock.last-run"].includes(name)) return;
-				if (name === "personal") { if (directory(path)) walk(path, path); return; }
+				if (name === "human") { if (directory(path)) walk(path, path); return; }
+				if (name === "agents" || name === "models") {
+					if (!directory(path)) return;
+					for (const slug of readdirSync(path)) {
+						const dir = join(path, slug);
+						inspect(dir, () => {
+							if (!SLUG_PATTERN.test(slug)) report(dir, `invalid ${name.slice(0, -1)} slug; expected [a-z0-9-]`);
+							if (!directory(dir)) return;
+							walk(dir, dir);
+						});
+					}
+					return;
+				}
 				if (name === "project" || name === "pi") {
 					if (!directory(path)) return;
 					const homes = name === "pi" ? join(path, "session") : path;
@@ -89,7 +110,7 @@ export function doctor(home: string): string[] {
 					}
 					return;
 				}
-				report(path, "unexpected root entry; expected personal/, project/, pi/session/ or dream artifacts");
+				report(path, "unexpected root entry; expected human/, project/, agents/, models/, pi/session/ or dream artifacts");
 			});
 		}
 	});

package/src/dream/runner.ts

@@ -3,7 +3,7 @@ import { lstat, mkdir, realpath } from "node:fs/promises";
 import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { createAgentSession, createEditToolDefinition, createWriteToolDefinition, ModelRuntime, resolveModelScopeWithDiagnostics, SessionManager, type AgentSession, type ToolDefinition } from "@earendil-works/pi-coding-agent";
 import type { Api, Model } from "@earendil-works/pi-ai";
-import { contentText } from "../history.js";
+import { contentText } from "../history/history.js";
 
 export type DreamWrite = { tool: "write" | "edit"; path: string };
 export type DreamResult = { report: string; writes: DreamWrite[]; error?: string };

package/src/dream/settings.ts

@@ -0,0 +1,32 @@
+import { SettingsManager } from "@earendil-works/pi-coding-agent";
+import { PI_CONTEXT_DREAMER_KEY, PI_CONTEXT_SETTINGS_KEY } from "../protocol.js";
+import { mergePiContextSettings, type PiContextSettings } from "../settings.js";
+
+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)}).`] };
+	}
+}

package/src/{history-tools.ts → history/history-tools.ts}

@@ -1,7 +1,7 @@
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { output, outputRaw, page, middleTruncate, prefixFit, earliestMatchOffsetChars, readCharacterWindow, readWindowBlock, withinTextBudget, DEFAULT_READ_WINDOW_CHARS, HISTORY_PREVIEW_CHARS, MAX_READ_WINDOW_CHARS } from "./tool-output.js";
-import { positiveInteger, recentFirst, nullableString, role, cursor, searchQuery, searchQueries } from "./tool-schema.js";
+import { output, outputRaw, page, middleTruncate, prefixFit, earliestMatchOffsetChars, readCharacterWindow, readWindowBlock, withinTextBudget, DEFAULT_READ_WINDOW_CHARS, HISTORY_PREVIEW_CHARS, MAX_READ_WINDOW_CHARS } from "../tool-output.js";
+import { positiveInteger, recentFirst, nullableString, role, cursor, searchQuery, searchQueries } from "../tool-schema.js";
 import { historyFromSession, filteredItems, visibleItem, allItems, vacuousRoleToolCombo, unknownWindowId } from "./history.js";
 
 /**
@@ -46,7 +46,7 @@ export function registerHistoryTools(pi: ExtensionAPI) {
 	pi.registerTool(defineTool({
 		name: "history_list",
 		label: "History list items",
-		description: "List durable session items, including items before compaction, using opaque item and window IDs; the role parameter's description enumerates the six roles. Every item carries truncated and total_chars: when truncated is true, truncated_content is a plain prefix of the item's content with no marker, and total_chars is its full code-point length. max_chars_per_item: 1 therefore yields pure addresses you can resolve with history_read.",
+		description: "List durable session items, including items from earlier reset windows, using opaque item and window IDs; native compaction and branch summaries remain history items in their current window. The role parameter's description enumerates the six roles. Every item carries truncated and total_chars: when truncated is true, truncated_content is a plain prefix of the item's content with no marker, and total_chars is its full code-point length. max_chars_per_item: 1 therefore yields pure addresses you can resolve with history_read.",
 		parameters: Type.Object({ limit: positiveInteger(), cursor: cursor(), recent_first: recentFirst(), role: Type.Optional(role), tool_name: nullableString(), window_id: nullableString(), max_chars_per_item: positiveInteger() }, { additionalProperties: false }),
 		async execute(_id, params, _signal, _update, ctx) {
 			const invalid = vacuousRoleToolCombo(params);

package/src/{history.ts → history/history.ts}

@@ -1,8 +1,8 @@
 import type { TextContent, ToolCall } from "@earendil-works/pi-ai";
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
-import type { SessionReader } from "./session-reader.js";
-import { RESET_V2 } from "./protocol.js";
-import { HISTORY_PREVIEW_CHARS } from "./tool-output.js";
+import type { SessionReader } from "../session-reader.js";
+import { isWindowMarker, rootWindowId } from "../context/context-window.js";
+import { HISTORY_PREVIEW_CHARS } from "../tool-output.js";
 
 type HistoryItem = {
 	windowId: string;
@@ -94,38 +94,22 @@ function toolCallItems(windowId: string, entry: { id: string; timestamp?: string
 	return items;
 }
 
-/** The extension-owned window id baked onto a reset-v2 compaction entry, if present. */
-export function resetV2WindowId(details: unknown): string | undefined {
-	if (typeof details !== "object" || details === null) return undefined;
-	const candidate = details as { piContext?: unknown; windowId?: unknown };
-	if (candidate.piContext !== RESET_V2 || typeof candidate.windowId !== "string") return undefined;
-	return candidate.windowId;
-}
-
-/** A compaction entry's window id: the extension-minted id for reset-v2, else Pi's entry id. */
-export function windowIdOf(sessionId: string, entry: { id: string; details?: unknown }): string {
-	return resetV2WindowId(entry.details) ?? `pcw:${sessionId.slice(0, 8)}:${entry.id}`;
-}
-
-/** Mint the durable identity of a session's root history window. */
-export function rootWindowId(sessionId: string): string {
-	return `pcw:${sessionId.slice(0, 8)}:root`;
-}
-
 /** Build durable, on-demand history directly from every entry on the current session branch. */
 export function historyFromSession(ctx: SessionReader): HistoryWindow[] {
 	const sessionId = ctx.sessionManager.getSessionId();
 	let window: HistoryWindow = { windowId: rootWindowId(sessionId), items: [] };
 	const windows = [window];
 	for (const entry of ctx.sessionManager.getBranch()) {
-		if (entry.type === "compaction") {
-			window = { windowId: windowIdOf(sessionId, entry), createdAt: entry.timestamp, items: [] };
+		if (isWindowMarker(entry)) {
+			window = { windowId: entry.data.windowId, createdAt: entry.timestamp, items: [] };
 			windows.push(window);
+			continue;
+		}
+		if (entry.type === "compaction" || entry.type === "branch_summary") {
 			window.items.push({
 				windowId: window.windowId,
 				itemId: entry.id,
-				// A reset-v2 compaction is authored by this extension; a native Pi compaction is not.
-				role: resetV2WindowId(entry.details) === undefined ? "system" : "developer",
+				role: "system",
 				content: entry.summary,
 				createdAt: entry.timestamp,
 			});
@@ -215,26 +199,3 @@ export function filteredItems(ctx: SessionReader, params: HistoryFilter): Histor
 	if (params.recent_first !== false) items.reverse();
 	return items;
 }
-
-
-/** Persisted messages in the active window, excluding earlier windows on this branch. */
-export function hasWindowMessage(ctx: SessionReader, customType: string): boolean {
-	const branch = ctx.sessionManager.getBranch();
-	for (let i = branch.length - 1; i >= 0; i--) {
-		const entry = branch[i];
-		if (entry.type === "compaction") break;
-		if (entry.type === "custom_message" && entry.customType === customType) return true;
-	}
-	return false;
-}
-
-/** Cheap current-window lookup: scan the branch tail for the latest compaction entry. */
-export function currentWindowId(ctx: SessionReader): string {
-	const sessionId = ctx.sessionManager.getSessionId();
-	const branch = ctx.sessionManager.getBranch();
-	for (let i = branch.length - 1; i >= 0; i--) {
-		const entry = branch[i];
-		if (entry?.type === "compaction") return windowIdOf(sessionId, entry);
-	}
-	return rootWindowId(sessionId);
-}

package/src/index.ts

@@ -1,97 +1,35 @@
-import { registerHistoryTools } from "./history-tools.js";
+import { VERSION, type ExtensionAPI, type ExtensionFactory, type SettingsManager } from "@earendil-works/pi-coding-agent";
+import { registerHistoryTools } from "./history/history-tools.js";
 import { registerNotesTools } from "./notes/tools.js";
-import { registerBudget } from "./budget.js";
-import { output } from "./tool-output.js";
-import { deriveThresholds, mergePiContextSettings } from "./thresholds.js";
-import { STATE_TYPE, NOTE_TYPE, BOOT_TYPE, GUIDANCE_TYPE, WARNING_TYPE, RESET_MARKER_TYPE, CONTINUATION_TYPE, RESET_V2, MAX_NOTE_BYTES, CONTEXT_WINDOW_OPEN_TAG, CONTEXT_WINDOW_CLOSE_TAG, CONTEXT_WINDOW_PROTOCOL_OPEN_TAG, CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG, GUIDANCE_OPEN_TAG, PI_CONTEXT_SETTINGS_KEY, DEFAULT_RESERVE_TOKENS, DEFAULT_REMINDER_MARGIN_TOKENS, WARNING_RUNWAY_TOKENS, RESET_SUMMARY, CONTINUATION, WARNING_PROMPT } from "./protocol.js";
-import { historyFromSession, hasWindowMessage, currentWindowId, resetV2WindowId, rootWindowId, windowIdOf } from "./history.js";
-import { assertVirtualPath } from "./notes/model.js";
-import { bootBlock } from "./prompts.js";
-export { historyFromSession } from "./history.js";
-export { notesFromSession } from "./notes/model.js";
-import { registerResetLifecycle } from "./reset-lifecycle.js";
-import { registerWarning } from "./warning.js";
-import { randomUUID } from "node:crypto";
-import { Type } from "@earendil-works/pi-ai";
-import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-
-export default function piContext(pi: ExtensionAPI) {
-	let enabled = true;
-	registerBudget(pi, () => enabled);
-	registerWarning(pi, () => enabled);
-
-	pi.on("session_start", (_event, ctx) => {
-		if (!enabled) return;
-		// The root window has no compaction entry to carry the boot block, so persist
-		// it once as a hidden custom message. Reset windows already carry theirs at
-		// position 0 in the compaction summary, so a resumed session adds nothing.
-		const rootId = rootWindowId(ctx.sessionManager.getSessionId());
-		if (currentWindowId(ctx) !== rootId || hasWindowMessage(ctx, BOOT_TYPE)) return;
-		pi.sendMessage({ customType: BOOT_TYPE, content: bootBlock(ctx, rootId, undefined, false), display: false }, { triggerTurn: false });
-	});
-
-	pi.registerCommand("pi-context", {
-		description: "Toggle pi-context: context_window boot block, low-budget guidance, and reset-style compaction",
-		getArgumentCompletions: (prefix) =>
-			["on", "off"].filter((a) => a.startsWith(prefix)).map((a) => ({ value: a, label: a })),
-		handler: async (args, cmdCtx) => {
-			const arg = args.trim().toLowerCase();
-			if (arg === "on") enabled = true;
-			else if (arg === "off") { enabled = false; resets.clear(); }
-			else if (arg !== "") {
-				cmdCtx.ui.notify("Usage: /pi-context [on|off]", "error");
-				return;
-			}
-			cmdCtx.ui.notify(`pi-context: ${enabled ? "on" : "off"}`, "info");
-		},
-	});
+import { deriveThresholds } from "./context/thresholds.js";
+import { registerContext } from "./context/runtime.js";
+import { mergePiContextSettings } from "./settings.js";
+import { NOTE_TYPE, BOOT_TYPE, GUIDANCE_TYPE, WARNING_TYPE, RESET_MARKER_TYPE, CONTINUATION_TYPE, MAX_NOTE_BYTES, CONTEXT_WINDOW_OPEN_TAG, CONTEXT_WINDOW_CLOSE_TAG, CONTEXT_WINDOW_PROTOCOL_OPEN_TAG, CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG, GUIDANCE_OPEN_TAG, PI_CONTEXT_SETTINGS_KEY, DEFAULT_RESERVE_TOKENS, DEFAULT_REMINDER_MARGIN_TOKENS, WARNING_RUNWAY_TOKENS, CONTINUATION, WARNING_PROMPT } from "./protocol.js";
+import { assertVirtualPath } from "./notes/address.js";
+export { historyFromSession } from "./history/history.js";
+export { notesFromSession } from "./notes/session-replay.js";
 
+function registerPiContext(pi: ExtensionAPI, settingsManager?: SettingsManager): void {
+	const [major, minor] = VERSION.split(".").map(Number);
+	if (!(major > 0 || (major === 0 && minor >= 87))) {
+		throw new Error(`pi-context requires Pi >= 0.87.0; running ${VERSION}. Upgrade Pi and restart the process; /reload only reloads extensions.`);
+	}
+	registerContext(pi, settingsManager);
 	registerHistoryTools(pi);
 	registerNotesTools(pi);
+}
 
-	pi.registerTool(defineTool({
-		name: "wipe_memory",
-		label: "Wipe memory",
-		description: "Wipe your in-context memory and start a fresh context window. Your session, notes, and history survive.",
-		parameters: Type.Object({}, { additionalProperties: false }),
-		async execute() {
-			if (!enabled) return output({ error: "pi-context is off (/pi-context on to enable)" });
-			return output({ status: resets.request() }, undefined, true);
-		},
-	}));
+/**
+ * Create an extension factory bound to an SDK settings authority. The host must pass
+ * the same manager to createAgentSession and to this factory's resource loader.
+ */
+export function createPiContext(options: { settingsManager?: SettingsManager } = {}): ExtensionFactory {
+	return (pi) => registerPiContext(pi, options.settingsManager);
+}
 
-	const resets = registerResetLifecycle(pi, {
-		isEnabled: () => enabled,
-		continuation: { customType: CONTINUATION_TYPE, content: CONTINUATION, display: false },
-		isCurrentReset: (entryId, ctx) => {
-			const entry = ctx.sessionManager.getEntry(entryId);
-			return entry?.type === "compaction" && resetV2WindowId(entry.details) === currentWindowId(ctx);
-		},
-		onReset: (entryId) => pi.appendEntry(STATE_TYPE, { version: 1, lastResetEntryId: entryId }),
-		buildReset: (event, ctx, explicit) => {
-			const sessionId = ctx.sessionManager.getSessionId();
-			// Window IDs are independent of Pi entry IDs. Avoid reusing a window
-			// identity already present on this branch.
-			const windows = historyFromSession(ctx);
-			const usedIds = new Set(windows.map((window) => window.windowId));
-			let minted = { id: randomUUID().slice(0, 8) };
-			while (usedIds.has(windowIdOf(sessionId, minted))) minted = { id: randomUUID().slice(0, 8) };
-			const windowId = windowIdOf(sessionId, minted);
-			const previousId = windows[windows.length - 1]?.windowId ?? rootWindowId(sessionId);
-			// The reset marker stays as firstKeptEntryId; it no longer names the window.
-			pi.appendEntry(RESET_MARKER_TYPE, { version: 1, reason: event.reason, requested: explicit });
-			const markerId = ctx.sessionManager.getLeafId();
-			if (!markerId) return { cancel: true };
-			return {
-				compaction: {
-					summary: bootBlock(ctx, windowId, previousId, true),
-					firstKeptEntryId: markerId,
-					tokensBefore: event.preparation.tokensBefore,
-					details: { piContext: RESET_V2, windowId },
-				},
-			};
-		},
-	});
+/** The Pi-discovered extension keeps the standard file-backed settings behavior. */
+export default function piContext(pi: ExtensionAPI): void {
+	registerPiContext(pi);
 }
 
-export const internal = { MAX_NOTE_BYTES, NOTE_TYPE, BOOT_TYPE, GUIDANCE_TYPE, WARNING_TYPE, WARNING_PROMPT, WARNING_RUNWAY_TOKENS, RESET_MARKER_TYPE, RESET_SUMMARY, CONTINUATION, CONTEXT_WINDOW_OPEN_TAG, CONTEXT_WINDOW_CLOSE_TAG, CONTEXT_WINDOW_PROTOCOL_OPEN_TAG, CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG, GUIDANCE_OPEN_TAG, PI_CONTEXT_SETTINGS_KEY, DEFAULT_RESERVE_TOKENS, DEFAULT_REMINDER_MARGIN_TOKENS, deriveThresholds, mergePiContextSettings, assertVirtualPath };
+export const internal = { MAX_NOTE_BYTES, NOTE_TYPE, BOOT_TYPE, GUIDANCE_TYPE, WARNING_TYPE, CONTINUATION_TYPE, WARNING_PROMPT, WARNING_RUNWAY_TOKENS, RESET_MARKER_TYPE, CONTINUATION, CONTEXT_WINDOW_OPEN_TAG, CONTEXT_WINDOW_CLOSE_TAG, CONTEXT_WINDOW_PROTOCOL_OPEN_TAG, CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG, GUIDANCE_OPEN_TAG, PI_CONTEXT_SETTINGS_KEY, DEFAULT_RESERVE_TOKENS, DEFAULT_REMINDER_MARGIN_TOKENS, deriveThresholds, mergePiContextSettings, assertVirtualPath };

package/src/notes/address.ts

@@ -1,33 +1,99 @@
-import { assertVirtualPath } from "./model.js";
-import type { Scope } from "./paths.js";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { agentSlug, modelSlug, SLUG_PATTERN, type Scope } from "./paths.js";
 
-export type NoteAddress = { scope: Scope; path: string };
+export type NoteAddress = { scope: Scope; path: string; who?: string };
 
-const ADDRESS_FORMS = "legal prefixes are @project/ and @personal/; bare names are the session home";
+export const ADDRESS_FORMS = "legal prefixes are @project/, @human/, @self/, and @model/; bare names are this session";
+
+export function assertVirtualPath(value: unknown): string {
+	if (typeof value !== "string" || value.length === 0) throw new Error("path must be a non-empty virtual relative path");
+	if (value.includes("\0") || value.includes("\\") || value.startsWith("/")) throw new Error("path must be a safe virtual relative path");
+	const parts = value.split("/");
+	if (parts.some((part) => part.length === 0 || part === "." || part === "..")) throw new Error("path contains an unsupported component");
+	return value;
+}
+
+/**
+ * Minimal glob over virtual note paths: `*` matches any run within a segment (never
+ * `/`), `**` matches any run across segments (a leading double-star followed by a
+ * slash also matches zero segments, so it covers the root too), `?` matches exactly
+ * one non-`/` character. Everything else is literal and the match is anchored to the
+ * whole path.
+ */
+export function globToRegExp(pattern: string): RegExp {
+	let source = "^";
+	for (let index = 0; index < pattern.length; index++) {
+		const char = pattern[index]!;
+		if (char === "*") {
+			if (pattern[index + 1] === "*") {
+				const followedBySlash = pattern[index + 2] === "/";
+				source += followedBySlash ? "(?:[^]*\\/)?" : "[^]*";
+				index += followedBySlash ? 2 : 1;
+			} else {
+				source += "[^/]*";
+			}
+		} else {
+			source += char.replace(/[\\^$.*+?()[\]{}|]/g, "\\$&");
+		}
+	}
+	return new RegExp(`${source}$`);
+}
+
+/** Glob patterns are not virtual paths (`*` is legal), so they get their own guard: no NUL, no backslashes. */
+export function assertGlobPattern(value: unknown): string | undefined {
+	if (value === undefined || value === null || value === "") return undefined;
+	if (typeof value !== "string") throw new Error("glob pattern must be a string");
+	if (value.includes("\0") || value.includes("\\")) throw new Error("glob pattern must not contain NUL or backslashes");
+	return value;
+}
 
 /**
  * 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.
+ * The word after `@` is always a reserved home name; agent and model names live at the
+ * second level (@agents/faye/, never @faye/), so user-chosen names can never collide with
+ * the reserved set. `@self` and `@model` are relative — `who` stays undefined and the
+ * store resolves the current agent/model at call time.
  */
 export function assertAddress(value: unknown): NoteAddress {
 	if (typeof value !== "string") throw new Error(`invalid note address: ${ADDRESS_FORMS}`);
 	let scope: Scope = "session";
 	let path = value;
-	if (value.startsWith("@project/")) {
-		scope = "project";
-		path = value.slice("@project/".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}`);
+	let who: string | undefined;
+	if (value.startsWith("@")) {
+		const rest = value.slice(1);
+		const headEnd = rest.indexOf("/");
+		const head = headEnd === -1 ? rest : rest.slice(0, headEnd);
+		const tail = headEnd === -1 ? "" : rest.slice(headEnd + 1);
+		path = tail;
+		if (head === "project") scope = "project";
+		else if (head === "human") scope = "human";
+		else if (head === "self") scope = "agent";
+		else if (head === "model") scope = "model";
+		else if (head === "agents" || head === "models") {
+			const nameEnd = tail.indexOf("/");
+			who = nameEnd === -1 ? tail : tail.slice(0, nameEnd);
+			if (!SLUG_PATTERN.test(who)) throw new Error(`invalid note address: ${ADDRESS_FORMS}`);
+			scope = head === "agents" ? "agent" : "model";
+			path = nameEnd === -1 ? "" : tail.slice(nameEnd + 1);
+		} else {
+			throw new Error(`invalid note address: ${ADDRESS_FORMS}`);
+		}
+		if (path === "" && scope !== "agent" && scope !== "model") throw new Error(`invalid note address: ${ADDRESS_FORMS}`);
+		if (path === "" && who === undefined) throw new Error(`invalid note address: ${ADDRESS_FORMS}`);
 	}
 	if (path.includes("@")) throw new Error(`invalid note address: ${ADDRESS_FORMS}`);
 	assertVirtualPath(path);
-	return { scope, path };
+	return { scope, path, who };
 }
 
-/** Render a virtual path in its one unambiguous public address form. */
-export function addressFor(scope: Scope, path: string): string {
-	return scope === "session" ? path : `@${scope}/${path}`;
+/** Render a virtual path in its one unambiguous public address form. Relative forms
+ * (@self/, @model/) never render: the canonical address always carries the resolved
+ * name, so listings alone tell every home apart. */
+export function addressFor(ctx: ExtensionContext, scope: Scope, path: string, who?: string): string {
+	if (scope === "session") return path;
+	if (scope === "project") return `@project/${path}`;
+	if (scope === "human") return `@human/${path}`;
+	if (scope === "agent") return `@agents/${who ?? agentSlug(ctx)}/${path}`;
+	return `@models/${who ?? modelSlug(ctx)}/${path}`;
 }

package/src/notes/frontmatter.ts

@@ -1,4 +1,3 @@
-import { localIso } from "./model.js";
 import type { Scope } from "./paths.js";
 
 export type NoteStatus = "active" | "superseded" | "pending" | "archived";
@@ -25,13 +24,29 @@ export type NoteMeta = {
 	[key: string]: unknown;
 };
 
-const SCOPES: readonly Scope[] = ["session", "project", "personal"];
+const SCOPES: readonly Scope[] = ["session", "project", "human", "agent", "model"];
 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;
 /** Emission order, exactly the Design's key list. */
 const KNOWN_KEYS = ["origin", "status", "stale", "created_at", "updated_at", "last_accessed", "access_count", "source_window", "supersedes", "recurrence_count", "recurrence_windows"] as const;
 
+const pad2 = (value: number) => String(value).padStart(2, "0");
+
+/**
+ * Format epoch milliseconds as an ISO 8601 string in the host's local time zone with an
+ * explicit numeric offset (e.g. 2026-09-15T17:31:45.392+08:00). A UTC host renders
+ * "+00:00"; the "Z" designator is never used, and Date.parse round-trips the value.
+ */
+export function localIso(epochMs: number): string {
+	const date = new Date(epochMs);
+	const offsetMinutes = -date.getTimezoneOffset();
+	const absOffset = Math.abs(offsetMinutes);
+	const offset = `${offsetMinutes < 0 ? "-" : "+"}${pad2(Math.floor(absOffset / 60))}:${pad2(absOffset % 60)}`;
+	const wallClock = `${date.getFullYear()}-${pad2(date.getMonth() + 1)}-${pad2(date.getDate())}T${pad2(date.getHours())}:${pad2(date.getMinutes())}:${pad2(date.getSeconds())}.${String(date.getMilliseconds()).padStart(3, "0")}`;
+	return `${wallClock}${offset}`;
+}
+
 export function isScope(value: unknown): value is Scope {
 	return typeof value === "string" && (SCOPES as readonly string[]).includes(value);
 }
@@ -112,7 +127,9 @@ 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 : "personal";
+	// scope is a legacy on-disk field: store callers derive it from the file's home and
+	// overwrite it after parsing, so an absent or outdated value just falls back.
+	meta.scope = isScope(meta.scope) ? meta.scope : "session";
 	meta.origin = isOrigin(meta.origin) ? meta.origin : "self";
 	meta.status = isStatus(meta.status) ? meta.status : "active";
 	meta.stale = meta.stale === true;

package/src/notes/notes-snapshot.ts

@@ -0,0 +1,40 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { listNotes, type NoteRow, type Scope } from "./store.js";
+
+const NOTES_HOMES = [
+	{ scope: "session", label: "this session" },
+	{ scope: "project", label: "@project" },
+	{ scope: "human", label: "@human" },
+	{ scope: "agent", label: "@self" },
+	{ scope: "model", label: "@model" },
+] as const satisfies ReadonlyArray<{ scope: Scope; label: string }>;
+
+export type NotesHome = (typeof NOTES_HOMES)[number];
+export type NotesLoader = (ctx: ExtensionContext, scope: Scope) => NoteRow[];
+export type NotesSnapshot = {
+	/** Wall-clock instant captured when this boot began; rendering never consults Date.now(). */
+	readonly openedAt: number;
+	readonly homes: ReadonlyMap<Scope, readonly NoteRow[]>;
+	readonly unavailable: readonly NotesHome[];
+};
+
+/**
+ * Acquire the five homes once for one boot. Only filesystem-style errno failures are isolated;
+ * malformed note data and unrelated construction errors remain visible to the caller.
+ */
+export function loadNotesSnapshot(ctx: ExtensionContext, loadHome: NotesLoader = (context, scope) => listNotes(context, { scope })): NotesSnapshot {
+	const openedAt = Date.now();
+	const homes = new Map<Scope, readonly NoteRow[]>();
+	const unavailable: NotesHome[] = [];
+	for (const home of NOTES_HOMES) {
+		try {
+			homes.set(home.scope, loadHome(ctx, home.scope));
+		} catch (error) {
+			const code = typeof error === "object" && error !== null ? (error as NodeJS.ErrnoException).code : undefined;
+			if (typeof code !== "string" || !/^E[A-Z0-9_]+$/.test(code) || code.startsWith("ERR_")) throw error;
+			homes.set(home.scope, []);
+			unavailable.push(home);
+		}
+	}
+	return { openedAt, homes, unavailable };
+}