@astrosheep/pi-context 0.25.2 → 0.26.1

package/src/context/runtime.ts

@@ -2,10 +2,11 @@ import { getCurrentSystemMessage, Type } from "@earendil-works/pi-ai";
 import { VERSION, defineTool, type ExtensionAPI, type ExtensionContext, type SettingsManager } from "@earendil-works/pi-coding-agent";
 import { registerBudget } from "./budget.js";
 import { output } from "../tool-output.js";
-import { migrateLegacyHomes } from "../notes/paths.js";
-import { currentReset, isWindowMarker, projectRootWindow, projectWindow, rootWindowId } from "./context-window.js";
+import { migrateLegacyHomes } from "../pi/notes/adapter.js";
+import { currentReset, currentWindowId, isCheckpointBackedReset, isWindowBoot, isWindowMarker, projectRootWindow, projectWindow, rootWindowId, type WindowMarker } from "./context-window.js";
 import { registerResetLifecycle } from "./reset-lifecycle.js";
-import { buildResetDrafts, persistManualReset, resetTailCommitted } from "./reset-artifacts.js";
+import { buildResetDrafts, resetTailCommitted } from "./reset-artifacts.js";
+import { BOOT_TYPE, WARNING_CONTENT, WARNING_TYPE } from "../protocol.js";
 import { ensureBoot, type IncompleteNotesNotifier } from "./boot.js";
 
 declare const __PI_CONTEXT_BUILD__: { version: string; sourceHash: string };
@@ -22,6 +23,7 @@ function branchHasWindowMarker(ctx: ExtensionContext, fromId?: string): boolean
 /** Register the context-window runtime and its context-owned commands/tools. */
 export function registerContext(pi: ExtensionAPI, settingsManager?: SettingsManager): void {
 	let enabled = true;
+	let lifecycleGeneration = 0;
 	let missingBootNotice: string | undefined;
 	const incompleteNotesNotified = new Set<string>();
 	const pendingResetNotices = new Set<string>();
@@ -32,8 +34,8 @@ export function registerContext(pi: ExtensionAPI, settingsManager?: SettingsMana
 		if (pendingResetNotices.size === 0) return;
 		const branch = ctx.sessionManager.getBranch();
 		for (const windowId of pendingResetNotices) {
-			const marker = branch.find((entry) => isWindowMarker(entry) && entry.data.windowId === windowId);
-			if (!marker || !resetTailCommitted(ctx, marker.id, windowId)) continue;
+			const marker = branch.find((entry): entry is WindowMarker => isWindowMarker(entry) && entry.data.windowId === windowId);
+			if (!marker || !isCheckpointBackedReset(ctx, marker) || !resetTailCommitted(ctx, marker.id, windowId)) continue;
 			pendingResetNotices.delete(windowId);
 			ctx.ui.notify(`pi-context: memory cleared · ${windowId}`, "info");
 		}
@@ -52,18 +54,24 @@ export function registerContext(pi: ExtensionAPI, settingsManager?: SettingsMana
 	const migrationWarning = migrateLegacyHomes();
 	if (migrationWarning) console.warn(`pi-context: ${migrationWarning}`);
 
-	const budget = registerBudget(pi, () => enabled, settingsManager);
+	const budget = registerBudget(pi, () => enabled, settingsManager, (windowId) => resets.closeOut(windowId, "automatic"));
 
-	pi.on("session_start", (_event, ctx) => {
+	pi.on("session_start", async (_event, ctx) => {
+		const generation = ++lifecycleGeneration;
 		if (!enabled) return;
 		missingBootNotice = undefined;
 		pendingResetNotices.clear();
-		ensureBoot(pi, ctx, notifyIncompleteNotes);
+		await ensureBoot(pi, ctx, notifyIncompleteNotes, () => generation === lifecycleGeneration && enabled);
 	});
-	pi.on("session_tree", (_event, ctx) => {
+	pi.on("session_tree", async (_event, ctx) => {
+		const generation = ++lifecycleGeneration;
 		missingBootNotice = undefined;
 		pendingResetNotices.clear();
-		if (enabled) ensureBoot(pi, ctx, notifyIncompleteNotes);
+		if (enabled) await ensureBoot(pi, ctx, notifyIncompleteNotes, () => generation === lifecycleGeneration && enabled);
+	});
+	pi.on("session_shutdown", () => {
+		lifecycleGeneration++;
+		pendingResetNotices.clear();
 	});
 
 	// Pi's branch summarizer receives raw entries and bypasses context_with_system. Do not
@@ -81,7 +89,11 @@ export function registerContext(pi: ExtensionAPI, settingsManager?: SettingsMana
 		const reset = currentReset(ctx);
 		const windowId = reset?.data.windowId ?? rootWindowId(ctx.sessionManager.getSessionId());
 		try {
-			return { messages: reset ? projectWindow(event.messages, windowId) : projectRootWindow(event.messages, windowId) };
+			if (reset) {
+				if (!event.messages.some((message) => isWindowBoot(message, windowId))) throw new Error(`Missing boot for context window ${windowId}`);
+				return { messages: isCheckpointBackedReset(ctx, reset) ? event.messages : projectWindow(event.messages, windowId) };
+			}
+			return { messages: projectRootWindow(event.messages, windowId) };
 		} catch (error) {
 			if (missingBootNotice !== windowId) {
 				missingBootNotice = windowId;
@@ -101,9 +113,12 @@ export function registerContext(pi: ExtensionAPI, settingsManager?: SettingsMana
 			const arg = args.trim().toLowerCase();
 			if (arg === "on") {
 				enabled = true;
-				ensureBoot(pi, cmdCtx, notifyIncompleteNotes);
+				const generation = ++lifecycleGeneration;
+				await ensureBoot(pi, cmdCtx, notifyIncompleteNotes, () => generation === lifecycleGeneration && enabled);
 			} else if (arg === "off") {
 				enabled = false;
+				lifecycleGeneration++;
+				pendingResetNotices.clear();
 				budget.clear();
 				resets.clear();
 			} else if (arg !== "") {
@@ -115,16 +130,25 @@ export function registerContext(pi: ExtensionAPI, settingsManager?: SettingsMana
 	});
 
 	pi.registerCommand("wipe-memory", {
-		description: "Persist a fresh context window without calling the model",
+		description: "Ask the agent to close out its notes, then start a fresh context window",
 		handler: async (_args, cmdCtx) => {
 			if (!enabled) {
 				cmdCtx.ui.notify("pi-context: /wipe-memory requires /pi-context on.", "error");
 				return;
 			}
+			const requestedWindowId = currentWindowId(cmdCtx);
+			await cmdCtx.waitForIdle();
+			if (!enabled || currentWindowId(cmdCtx) !== requestedWindowId) return;
+			const armed = resets.closeOut(requestedWindowId, "manual");
+			if (armed === "already-pending") return;
+			try {
+				pi.sendMessage({ customType: WARNING_TYPE, content: WARNING_CONTENT, display: false }, { triggerTurn: true });
+			} catch (error) {
+				resets.clear();
+				cmdCtx.ui.notify(`pi-context: could not start manual close-out (${String(error)}).`, "error");
+				return;
+			}
 			await cmdCtx.waitForIdle();
-			if (!enabled) return;
-			resets.clear();
-			notifyCommittedResets(cmdCtx, persistManualReset(pi, cmdCtx, notifyIncompleteNotes));
 		},
 	});
 
@@ -133,18 +157,22 @@ export function registerContext(pi: ExtensionAPI, settingsManager?: SettingsMana
 		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() {
+		async execute(_id, _params, _signal, _update, ctx) {
 			if (!enabled) return output({ error: "pi-context is off (/pi-context on to enable)" });
-			return output({ status: resets.request() }, undefined, true);
+			return output({ status: resets.request(currentWindowId(ctx)) }, undefined, true);
 		},
 	}));
 
 	const resets = registerResetLifecycle(pi, {
 		isEnabled: () => enabled,
-		buildReset: (ctx) => {
-			const drafts = buildResetDrafts(ctx, notifyIncompleteNotes);
-			pendingResetNotices.add(drafts[1].details.windowId);
-			return drafts;
+		buildReset: (ctx, isCurrent) => buildResetDrafts(ctx, notifyIncompleteNotes, isCurrent),
+		getLifecycleGeneration: () => lifecycleGeneration,
+		onResetReady: (_ctx, drafts) => {
+			const boot = drafts.find((draft) => draft.type === "custom_message" && draft.customType === BOOT_TYPE);
+			if (boot?.type === "custom_message" && boot.details && typeof boot.details === "object") {
+				const windowId = (boot.details as { windowId?: unknown }).windowId;
+				if (typeof windowId === "string") pendingResetNotices.add(windowId);
+			}
 		},
 		budget,
 	});

package/src/context/thresholds.ts

@@ -24,7 +24,7 @@ export function deriveThresholds(reserveTokens: number, margins: PiContextSettin
 	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}.`);
+			warnings.push(`pi-context: ${reminderKey} must be a positive integer; using the default reminder margin.`);
 			reminderMargin = DEFAULT_REMINDER_MARGIN_TOKENS;
 		} else reminderMargin = parsed;
 	}

package/src/dream/cli.ts

@@ -8,7 +8,7 @@ import { loadPlaybook, runDreamer, type DreamerSessionFactory, type DreamResult,
 import { gitCommit } from "./git.js";
 import { readDreamerSettings, type DreamerSetting } from "./settings.js";
 import { doctor } from "./doctor.js";
-import { notesRoot } from "../notes/paths.js";
+import { notesRoot } from "../pi/notes/adapter.js";
 
 function args(argv: string[]) { const out: Record<string, string | boolean> = {}; for (let i=0;i<argv.length;i++) { const a=argv[i]!; if (a === "--force" || a === "--help") out[a.slice(2)] = true; else if (a.startsWith("--")) out[a.slice(2)] = argv[++i] ?? ""; } return out; }
 function packageRoot(): string {

package/src/dream/doctor.ts

@@ -27,10 +27,13 @@ export function doctor(home: string): string[] {
 			if (fields.has(field[1]!)) report(path, `duplicate metadata key ${field[1]}; keep one value`);
 			fields.set(field[1]!, field[2]!.replace(/^(["'])(.*)\1$/, "$2"));
 		}
-		for (const [key, valid] of Object.entries({ origin: /^(user|self|external)$/, status: /^(active|superseded|pending|archived)$/, stale: /^(true|false)$/, access_count: /^\d+$/ })) {
+		for (const [key, valid] of Object.entries({ origin: /^(user|self|external)$/, status: /^(active|superseded|pending|archived)$/, stale: /^(true|false)$/, accessCount: /^\d+$/ })) {
 			if (!valid.test(fields.get(key) ?? "")) report(path, `missing/invalid ${key}; repair frontmatter`);
 		}
-		for (const key of ["created_at", "updated_at", "last_accessed"]) {
+		for (const [legacy, current] of [["created_at", "createdAt"], ["updated_at", "updatedAt"], ["last_accessed", "lastAccessed"], ["access_count", "accessCount"], ["source_window", "sourceWindow"], ["recurrence_count", "recurrenceCount"], ["recurrence_windows", "recurrenceWindows"]]) {
+			if (fields.has(legacy)) report(path, `legacy metadata key ${legacy}; manually migrate to ${current}`);
+		}
+		for (const key of ["createdAt", "updatedAt", "lastAccessed"]) {
 			const value = fields.get(key);
 			if (!value || !Number.isFinite(Date.parse(value))) report(path, `missing/invalid ${key}; use an ISO timestamp`);
 		}

package/src/index.ts

@@ -1,13 +1,13 @@
 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 { registerNotesTools } from "./pi/notes/tools.js";
 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 { 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, WARNING_CONTENT } from "./protocol.js";
 import { assertVirtualPath } from "./notes/address.js";
 export { historyFromSession } from "./history/history.js";
-export { notesFromSession } from "./notes/session-replay.js";
+export { notesFromSession } from "./pi/notes/session-replay.js";
 
 function registerPiContext(pi: ExtensionAPI, settingsManager?: SettingsManager): void {
 	const [major, minor] = VERSION.split(".").map(Number);
@@ -32,4 +32,4 @@ export default function piContext(pi: ExtensionAPI): void {
 	registerPiContext(pi);
 }
 
-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 };
+export const internal = { MAX_NOTE_BYTES, NOTE_TYPE, BOOT_TYPE, GUIDANCE_TYPE, WARNING_TYPE, CONTINUATION_TYPE, WARNING_PROMPT, WARNING_CONTENT, 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,5 +1,5 @@
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { agentSlug, modelSlug, SLUG_PATTERN, type Scope } from "./paths.js";
+import type { NotesContext } from "./context.js";
+import { SLUG_PATTERN, type Scope } from "./paths.js";
 
 export type NoteAddress = { scope: Scope; path: string; who?: string };
 
@@ -39,7 +39,7 @@ export function globToRegExp(pattern: string): RegExp {
 	return new RegExp(`${source}$`);
 }
 
-/** Glob patterns are not virtual paths (`*` is legal), so they get their own guard: no NUL, no backslashes. */
+/** Glob patterns are not virtual paths (`*` is legal), so they get their own guard. */
 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");
@@ -48,12 +48,8 @@ export function assertGlobPattern(value: unknown): string | undefined {
 }
 
 /**
- * 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.
+ * Decode one public note address into its physical home and virtual path. @self and @model
+ * are relative; explicit agents/models addresses always name a canonical slug.
  */
 export function assertAddress(value: unknown): NoteAddress {
 	if (typeof value !== "string") throw new Error(`invalid note address: ${ADDRESS_FORMS}`);
@@ -87,13 +83,11 @@ export function assertAddress(value: unknown): NoteAddress {
 	return { scope, path, who };
 }
 
-/** 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 {
+/** Render a virtual path in its one unambiguous public address form. */
+export function addressFor(context: NotesContext, 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}`;
+	if (scope === "agent") return `@agents/${who ?? context.agent}/${path}`;
+	return `@models/${who ?? context.model}/${path}`;
 }

package/src/notes/constants.ts

@@ -0,0 +1,3 @@
+export const MAX_NOTE_BYTES = 1_000_000;
+/** Write-time cap on a virtual note path. Reads and legacy replay stay uncapped. */
+export const MAX_NOTE_PATH_BYTES = 512;

package/src/notes/context.ts

@@ -0,0 +1,40 @@
+import { resolve } from "node:path";
+import { SLUG_PATTERN } from "./paths.js";
+
+/** Explicit, host-neutral identity for one notes store. */
+export type NotesContext = Readonly<{
+	home: string;
+	sessionId: string;
+	projectKey: string;
+	agent: string;
+	model: string;
+}>;
+
+function requireString(field: string, value: unknown): string {
+	if (typeof value !== "string" || value.length === 0) throw new TypeError(`notes context ${field} must be a non-empty string`);
+	return value;
+}
+
+function assertDirectoryComponent(field: string, value: string): void {
+	if (value === "." || value === ".." || /[\\/\0:]/.test(value)) {
+		throw new TypeError(`notes context ${field} must be a safe single directory component`);
+	}
+}
+
+/** Validate and snapshot caller identity; no global or environment defaults are consulted. */
+export function snapshotNotesContext(value: NotesContext): NotesContext {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new TypeError("notes context must be a plain object");
+	const prototype = Object.getPrototypeOf(value);
+	if (prototype !== Object.prototype && prototype !== null) throw new TypeError("notes context must be a plain object");
+	const homeValue = requireString("home", value.home);
+	const sessionId = requireString("sessionId", value.sessionId);
+	const projectKey = requireString("projectKey", value.projectKey);
+	const agent = requireString("agent", value.agent);
+	const model = requireString("model", value.model);
+	assertDirectoryComponent("sessionId", sessionId);
+	assertDirectoryComponent("projectKey", projectKey);
+	if (!SLUG_PATTERN.test(agent)) throw new TypeError("notes context agent must be a canonical lowercase slug");
+	if (!SLUG_PATTERN.test(model)) throw new TypeError("notes context model must be a canonical lowercase slug");
+	const home = resolve(homeValue);
+	return Object.freeze({ home, sessionId, projectKey, agent, model });
+}

package/src/notes/frontmatter.ts

@@ -13,23 +13,26 @@ export type NoteMeta = {
 	origin: Origin;
 	status: NoteStatus;
 	stale: boolean;
-	created_at: number;
-	updated_at: number;
-	last_accessed: number;
-	access_count: number;
-	source_window?: string;
+	createdAt: number;
+	updatedAt: number;
+	lastAccessed: number;
+	accessCount: number;
+	sourceWindow?: string;
 	supersedes?: string;
-	recurrence_count?: number;
-	recurrence_windows?: string[];
+	recurrenceCount?: number;
+	recurrenceWindows?: string[];
+	/** Project ownership on newly-created session notes; legacy/invalid values are preserved as-is. */
+	project?: unknown;
 	[key: string]: unknown;
 };
 
 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;
+const TIMESTAMP_KEYS = ["createdAt", "updatedAt", "lastAccessed"] as const;
+const LEGACY_KNOWN_KEYS = ["created_at", "updated_at", "last_accessed", "access_count", "source_window", "recurrence_count", "recurrence_windows"] 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 KNOWN_KEYS = ["origin", "status", "stale", "createdAt", "updatedAt", "lastAccessed", "accessCount", "sourceWindow", "supersedes", "recurrenceCount", "recurrenceWindows"] as const;
 
 const pad2 = (value: number) => String(value).padStart(2, "0");
 
@@ -96,7 +99,7 @@ function parseFrontmatter(raw: string): { fields: Record<string, unknown>; body:
 		}
 	}
 	if (close === -1) return { fields: {}, body: raw };
-	const fields: Record<string, unknown> = {};
+	const fields = Object.create(null) as Record<string, unknown>;
 	for (let index = 1; index < close; index++) {
 		const line = lines[index]!;
 		const match = /^([A-Za-z_][A-Za-z0-9_-]*):(.*)$/.exec(line);
@@ -122,10 +125,13 @@ function parseFrontmatter(raw: string): { fields: Record<string, unknown>; body:
 
 /**
  * Parse a note file. Missing known keys take the Design defaults (status active, stale false,
- * access_count 0, timestamps now); unknown keys are carried through untouched.
+ * accessCount 0, timestamps now); unknown keys are carried through untouched. Known
+ * snake_case metadata is refused because it requires the explicit manual migration.
  */
 export function parseNote(raw: string, now = Date.now()): { meta: NoteMeta; body: string } {
 	const { fields, body } = parseFrontmatter(raw);
+	const legacyKeys = LEGACY_KNOWN_KEYS.filter((key) => Object.hasOwn(fields, key));
+	if (legacyKeys.length > 0) throw new Error(`legacy note metadata ${legacyKeys.join(", ")} requires manual migration to camelCase before this note can be used`);
 	const meta = { ...fields } as Record<string, unknown>;
 	// 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.
@@ -134,7 +140,7 @@ export function parseNote(raw: string, now = Date.now()): { meta: NoteMeta; body
 	meta.status = isStatus(meta.status) ? meta.status : "active";
 	meta.stale = meta.stale === true;
 	for (const key of TIMESTAMP_KEYS) meta[key] = toEpoch(meta[key], now);
-	meta.access_count = typeof meta.access_count === "number" && Number.isFinite(meta.access_count) ? meta.access_count : 0;
+	meta.accessCount = typeof meta.accessCount === "number" && Number.isFinite(meta.accessCount) ? meta.accessCount : 0;
 	return { meta: meta as NoteMeta, body };
 }
 

package/src/notes/index.ts

@@ -0,0 +1,22 @@
+export { createNotesStore, NoteError } from "./store.js";
+export { projectKey, slugify } from "./paths.js";
+export type { NotesContext } from "./context.js";
+export type {
+	EditOperation,
+	EditOptions,
+	NoteChange,
+	NoteEditResult,
+	NoteErrorCode,
+	NoteMatch,
+	NoteMeta,
+	NoteReadResult,
+	NoteRow,
+	NoteSearchRow,
+	NoteStatus,
+	NoteWriteResult,
+	NotesQuery,
+	NotesStore,
+	Origin,
+	Scope,
+	WriteOptions,
+} from "./store.js";

package/src/notes/paths.ts

@@ -1,34 +1,18 @@
 import { createHash } from "node:crypto";
-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";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { basename, dirname, join, resolve, sep } from "node:path";
+import type { NotesContext } from "./context.js";
 
 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 {
-	const override = process.env.PI_NOTES_HOME;
-	return override && override.length > 0 ? resolve(override) : join(homedir(), ".agents", "notes");
-}
-
-/** Absolute directory holding the per-session note homes. */
-export function sessionHomesRoot(home = notesRoot()): string {
-	return join(home, "pi", "session");
-}
+/** 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]+)*$/;
 
-/**
- * Absolute git root for `cwd`, walking upward until a directory holds a `.git` entry.
- * No git root yields undefined, which projectKey then replaces with the cwd itself.
- */
-function gitRoot(cwd: string): string | undefined {
-	let dir = resolve(cwd);
-	for (;;) {
-		if (existsSync(join(dir, ".git"))) return dir;
-		const parent = dirname(dir);
-		if (parent === dir) return undefined;
-		dir = parent;
-	}
+/** Slugify a caller-declared identity; identity is never inferred from note content. */
+export function slugify(value: string): string {
+	const slug = value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+	return slug.length > 0 ? slug : "root";
 }
 
 /** `<basename(absGitRoot)-sha1(absGitRoot)[:8]>`, or the same formula over cwd with no git root. */
@@ -39,67 +23,67 @@ export function projectKey(cwd: string): string {
 	return `${basename(root)}-${digest}`;
 }
 
-/** Session identity comes from the pi session manager; ids are filesystem-safe by construction. */
-function sessionId(ctx: ExtensionContext): string {
-	return ctx.sessionManager.getSessionId();
-}
-
-/** 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-].
+ * Repository root behind one `.git` entry. A `.git` directory is the main checkout
+ * itself. A `.git` file is a worktree or submodule pointer: a linked worktree names
+ * `<main>/.git/worktrees/<name>` and resolves to `<main>`, so every worktree of one
+ * repository shares one project identity. Submodules, bare repositories, and separate
+ * git dirs keep the current directory.
  */
-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");
+function repositoryRoot(dir: string): string {
+	let stats;
+	try {
+		stats = statSync(join(dir, ".git"));
+	} catch {
+		return dir;
+	}
+	if (stats.isDirectory()) return dir;
+	let pointer: string;
+	try {
+		pointer = readFileSync(join(dir, ".git"), "utf8");
+	} catch {
+		return dir;
+	}
+	const match = /^gitdir:\s*(.+)$/m.exec(pointer);
+	if (!match) return dir;
+	const parts = resolve(dir, match[1]!.trim()).split(sep);
+	const worktrees = parts.lastIndexOf("worktrees");
+	if (worktrees <= 0 || worktrees !== parts.length - 2) return dir;
+	const common = parts.slice(0, worktrees).join(sep);
+	return basename(common) === ".git" ? dirname(common) : dir;
 }
 
-/** 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 repository root for cwd, walking upward until a directory holds a `.git` entry. */
+function gitRoot(cwd: string): string | undefined {
+	let dir = resolve(cwd);
+	for (;;) {
+		if (existsSync(join(dir, ".git"))) return repositoryRoot(dir);
+		const parent = dirname(dir);
+		if (parent === dir) return undefined;
+		dir = parent;
+	}
 }
 
-/**
- * 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));
+/** Absolute directory holding the per-session note homes. */
+export function sessionHomesRoot(home: string): string {
+	return join(home, "pi", "session");
 }
 
-/**
- * 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;
+/** Absolute directory holding one scope's notes. The context's home is already resolved. */
+export function scopeDir(scope: Scope, context: NotesContext, who?: string): string {
+	if (!["session", "project", "human", "agent", "model"].includes(scope)) throw new TypeError("invalid notes scope");
+	if (who !== undefined && (scope !== "agent" && scope !== "model" || !SLUG_PATTERN.test(who))) throw new TypeError("who must be a canonical agent/model slug");
+	if (scope === "human") return join(context.home, "human");
+	if (scope === "project") return join(context.home, "project", context.projectKey);
+	if (scope === "agent") return join(context.home, "agents", who ?? context.agent);
+	if (scope === "model") return join(context.home, "models", who ?? context.model);
+	return join(sessionHomesRoot(context.home), context.sessionId);
 }
 
-/** Every existing home directory of the agents/ or models/ namespace, as slugs. */
-export function namespaceSlugs(namespace: "agents" | "models", home = notesRoot()): string[] {
+/** Every existing home directory of the agents/ or models/ namespace, as names. */
+export async function namespaceSlugs(namespace: "agents" | "models", home: string): Promise<string[]> {
 	try {
-		return readdirSync(join(home, namespace), { withFileTypes: true })
+		return (await readdir(join(home, namespace), { withFileTypes: true }))
 			.filter((entry) => entry.isDirectory())
 			.map((entry) => entry.name)
 			.sort();
@@ -117,6 +101,8 @@ 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, who?: string): string {
-	return join(scopeDir(scope, ctx, who), ...noteFileName(vpath).split("/"));
+export function physicalPath(scope: Scope, vpath: string, context: NotesContext, who?: string): string {
+	if (typeof vpath !== "string" || vpath.length === 0 || vpath.includes("\0") || vpath.includes("\\") || vpath.startsWith("/")) throw new TypeError("path must be a safe virtual relative path");
+	if (vpath.split("/").some((part) => part.length === 0 || part === "." || part === "..")) throw new TypeError("path contains an unsupported component");
+	return join(scopeDir(scope, context, who), ...noteFileName(vpath).split("/"));
 }