@astrosheep/pi-context 0.23.1 → 0.25.0

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, RESET_SUMMARY, 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: "new_context",
-		label: "New context",
-		description: "Clear your mind and start a new 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, 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 };

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/, @agents/<name>/, @model/, and @models/<name>/; bare names are the session home";
+
+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 };
+}

package/src/notes/paths.ts

@@ -1,10 +1,10 @@
 import { createHash } from "node:crypto";
-import { existsSync } from "node:fs";
+import { existsSync, readdirSync, renameSync } from "node:fs";
 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" | "personal";
+export type Scope = "session" | "project" | "human" | "agent" | "model";
 
 /** Physical home of the on-disk note store: $PI_NOTES_HOME or ~/.agents/notes. */
 export function notesRoot(): string {
@@ -44,13 +44,70 @@ function sessionId(ctx: ExtensionContext): string {
 	return ctx.sessionManager.getSessionId();
 }
 
-/** Absolute directory holding every note of one scope. */
-export function scopeDir(scope: Scope, ctx: ExtensionContext): string {
-	if (scope === "personal") return join(notesRoot(), "personal");
+/** The one legal home-name shape: lowercase [a-z0-9-] runs separated by single dashes. */
+export const SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+/**
+ * Identity slugs: one declared name per home, never detected from prompt content.
+ * `PI_NOTES_AGENT` declares who is running (default "root"); the model slug derives
+ * from the live model id, provider prefix stripped. Both slugified to [a-z0-9-].
+ */
+export function slugify(value: string): string {
+	const slug = value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+	return slug.length > 0 ? slug : "root";
+}
+
+/** The current agent's home name: the launch-declared identity, defaulting to "root". */
+export function agentSlug(_ctx: ExtensionContext): string {
+	return slugify(process.env.PI_NOTES_AGENT ?? "root");
+}
+
+/** The current model's home name, live-resolved from ctx.model; "default" when unknown. */
+export function modelSlug(ctx: ExtensionContext): string {
+	const id = ctx.model?.id;
+	if (!id) return "default";
+	return slugify(id.split("/").pop() ?? id);
+}
+
+/**
+ * Absolute directory holding every note of one scope. `who` names an agent or model
+ * home absolutely; omitted, the current one resolves (agent from PI_NOTES_AGENT,
+ * model live from ctx.model).
+ */
+export function scopeDir(scope: Scope, ctx: ExtensionContext, who?: string): string {
+	if (scope === "human") return join(notesRoot(), "human");
 	if (scope === "project") return join(notesRoot(), "project", projectKey(ctx.cwd));
+	if (scope === "agent") return join(notesRoot(), "agents", who ?? agentSlug(ctx));
+	if (scope === "model") return join(notesRoot(), "models", who ?? modelSlug(ctx));
 	return join(sessionHomesRoot(), sessionId(ctx));
 }
 
+/**
+ * One-time migration of the pre-v0.25 `personal/` home to `human/`. Runs at extension
+ * activation; returns a warning string when both directories exist (no auto-merge),
+ * undefined otherwise. Old note bodies are history, not addresses, and stay untouched.
+ */
+export function migrateLegacyHomes(home = notesRoot()): string | undefined {
+	const legacy = join(home, "personal");
+	const modern = join(home, "human");
+	if (!existsSync(legacy)) return undefined;
+	if (existsSync(modern)) return "both personal/ and human/ exist under the notes home; migrate by hand, no automatic merge";
+	renameSync(legacy, modern);
+	return undefined;
+}
+
+/** Every existing home directory of the agents/ or models/ namespace, as slugs. */
+export function namespaceSlugs(namespace: "agents" | "models", home = notesRoot()): string[] {
+	try {
+		return readdirSync(join(home, namespace), { withFileTypes: true })
+			.filter((entry) => entry.isDirectory())
+			.map((entry) => entry.name)
+			.sort();
+	} catch {
+		return [];
+	}
+}
+
 /**
  * Notes are markdown files: a virtual path without an `.md` suffix gains one, an explicit
  * `.md` is kept as-is, so `a/b` and `a/b.md` name the same physical file.
@@ -60,6 +117,6 @@ export function noteFileName(vpath: string): string {
 }
 
 /** Absolute file path for a virtual path in a scope. Callers validate the vpath first. */
-export function physicalPath(scope: Scope, vpath: string, ctx: ExtensionContext): string {
-	return join(scopeDir(scope, ctx), ...noteFileName(vpath).split("/"));
+export function physicalPath(scope: Scope, vpath: string, ctx: ExtensionContext, who?: string): string {
+	return join(scopeDir(scope, ctx, who), ...noteFileName(vpath).split("/"));
 }

package/src/notes/session-replay.ts

@@ -0,0 +1,53 @@
+import type { SessionReader } from "../session-reader.js";
+import { MAX_NOTE_BYTES, NOTE_TYPE } from "../protocol.js";
+import { assertVirtualPath } from "./address.js";
+
+export type NoteFile = { text: string; stale: boolean; createdAt: number; updatedAt: number };
+export type NoteOperation = {
+	op: "write" | "append";
+	path: string;
+	// Both are optional on the wire so mark-only and explicit-revive operations replay:
+	// at least one of text/stale is present, enforced by the note tools and isNoteOperation.
+	text?: string;
+	stale?: boolean;
+	createdAt: number;
+	updatedAt: number;
+};
+
+/** Replays only pi-context note operations from session custom entries. */
+function isNoteOperation(data: unknown): data is NoteOperation {
+	if (typeof data !== "object" || data === null) return false;
+	const op = data as Partial<NoteOperation>;
+	return (
+		(op.op === "write" || op.op === "append") &&
+		typeof op.path === "string" &&
+		(op.text === undefined || typeof op.text === "string") &&
+		(op.stale === undefined || typeof op.stale === "boolean") &&
+		(op.text !== undefined || op.stale !== undefined) &&
+		typeof op.createdAt === "number" && Number.isFinite(new Date(op.createdAt).getTime()) &&
+		typeof op.updatedAt === "number" && Number.isFinite(new Date(op.updatedAt).getTime())
+	);
+}
+
+export function notesFromSession(ctx: SessionReader): Map<string, NoteFile> {
+	const files = new Map<string, NoteFile>();
+	for (const entry of ctx.sessionManager.getBranch()) {
+		if (entry.type !== "custom" || entry.customType !== NOTE_TYPE || !isNoteOperation(entry.data)) continue;
+		const op = entry.data;
+		try {
+			assertVirtualPath(op.path);
+		} catch {
+			continue;
+		}
+		const previous = files.get(op.path);
+		const hasText = op.text !== undefined;
+		// A mark-only operation needs an existing note to change; without one it is a no-op.
+		if (!hasText && !previous) continue;
+		const text = hasText ? (op.op === "append" ? `${previous?.text ?? ""}${op.text}` : op.text as string) : previous!.text;
+		if (Buffer.byteLength(text, "utf8") > MAX_NOTE_BYTES) continue;
+		// Carrying text revives unless the call also marks stale; a mark-only op keeps its flag.
+		const stale = hasText ? op.stale ?? false : op.stale ?? previous!.stale;
+		files.set(op.path, { text, stale, createdAt: previous?.createdAt ?? op.createdAt, updatedAt: op.updatedAt });
+	}
+	return files;
+}