@vanillagreen/pi-qol 2.2.1 → 2.3.2

package/README.md

@@ -29,6 +29,17 @@ Requires Pi 0.86.0 or newer. Restart Pi after installation. Use `kendex update-p
 
 The extension reads your enabled features when Pi starts. It adds their editor controls, commands and event handlers. Session actions update the session or queue messages for the agent. Notifications report events through your selected channels. Compaction settings control when long conversations are summarized.
 
+## Memory use
+
+- A session without a UI loads no session-search index. With a UI, the index is loaded shortly after start and kept for `sessionSearch.cacheTtlSeconds` (default 300 seconds; 0 keeps it until the session ends). A search after the index was released opens at once and fills in when the index has loaded again.
+- The index keeps at most 32,768 characters of message text per session and 8,388,608 characters in total, newest session first. A session past the total is searched by name, path and first prompt only.
+- Where Pi cannot switch sessions directly, a chosen resume or fork waits as one `/search:resume-pending` command in the editor. Only the latest one is kept, and it is dropped when the session ends.
+- Parsed prompts are kept for at most 64 sessions, and finished thinking times for at most 256 blocks. Thinking labels are released at the end of each agent run, and notification cooldown entries once their cooldown has passed and all of them when the session ends.
+
+## Saved files
+
+At session start, the extension deletes budget handoff files whose recorded working directory no longer exists. It also deletes files older than 5 days. Both timestamped snapshots and `latest.json` follow this rule.
+
 ## Settings
 
 The settings editor writes project values to `.pi/settings.json`. The default user file is `~/.pi/agent/settings.json`. `PI_CODING_AGENT_DIR` changes the user directory. Package values are stored under `kendex.extensionManager.config["@vanillagreen/pi-qol"]`.

package/extensions/qol/compaction-handoff.ts

@@ -4,11 +4,12 @@
 // drops something critical. The pure data-building + write logic lives here
 // so it can be unit-tested without the pi-coding-agent / pi-ai peer deps.
 
-import { mkdirSync, writeFileSync } from "node:fs";
-import { basename, dirname, join, resolve } from "node:path";
+import { writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
 
+import { openLaneDir } from "../../scripts/lane-retention.js";
 import { QOL_BUDGET_HANDOFF_FOLDER, QOL_BUDGET_HANDOFF_LATEST } from "./constants.js";
-import { expandHome } from "./settings.js";
+import { piUserDir } from "./package-config.js";
 
 export interface QolBudgetHandoff {
 	reason: string;
@@ -22,17 +23,6 @@ export interface QolBudgetHandoff {
 	model?: string;
 }
 
-/** Root-anchored as `crates/core/src/harness/pi.rs::pi_root_is_absolute_for`
- * means it, which `isAbsolute` is not: it calls a driveless `\root` absolute
- * where the renderer does not, putting the two on different roots. Hoisted, so
- * a circular import cannot reach it inside a temporal dead zone. */
-function rootAnchored(path: string, windows: boolean): boolean { return windows ? /^(?:[A-Za-z]:[\\/]|[\\/]{2}[^\\/]+[\\/][^\\/]+)/.test(path) : path.startsWith("/"); }
-
-export function piUserDir(): string {
-	const override = expandHome(process.env.PI_CODING_AGENT_DIR?.trim() || "");
-	return resolve(rootAnchored(override, process.platform === "win32") ? override : expandHome("~/.pi/agent"));
-}
-
 export function safeFileName(value: string): string {
 	return value.replace(/[^\w.-]+/g, "_");
 }
@@ -157,16 +147,13 @@ export function handoffBaseDir(sessionId: string, root: string = piUserDir()): s
 
 export interface WriteHandoffOptions {
 	enabled: boolean;
+	cwd: string;
 	root?: string;
 	/** Injection point so tests can stub fs without mocking node:fs. */
 	writer?: (path: string, payload: string) => void;
 	mkdir?: (path: string) => void;
 }
 
-function defaultMkdir(path: string): void {
-	mkdirSync(path, { recursive: true, mode: 0o700 });
-}
-
 function defaultWriter(path: string, payload: string): void {
 	writeFileSync(path, payload, { mode: 0o600 });
 }
@@ -176,7 +163,7 @@ export function writeBudgetHandoffArtifact(handoff: QolBudgetHandoff, options: W
 	const baseDir = handoffBaseDir(handoff.sessionId, options.root);
 	const stampedPath = handoffStampedPath(baseDir, handoff.timestamp);
 	const latestPath = join(dirname(baseDir), basename(baseDir), QOL_BUDGET_HANDOFF_LATEST);
-	const mkdir = options.mkdir ?? defaultMkdir;
+	const mkdir = options.mkdir ?? ((path: string) => openLaneDir(path, options.cwd));
 	const writer = options.writer ?? defaultWriter;
 	try {
 		mkdir(baseDir);

package/extensions/qol/compaction.ts

@@ -252,7 +252,7 @@ export function buildBudgetHandoff(ctx: ExtensionContext, options: {
 
 export function writeBudgetHandoffArtifact(ctx: ExtensionContext, handoff: QolBudgetHandoff): HandoffWriteResult {
 	const enabled = settingBoolean("compaction.handoffArtifactEnabled", true, ctx.cwd);
-	const result = writeBudgetHandoffArtifactRaw(handoff, { enabled });
+	const result = writeBudgetHandoffArtifactRaw(handoff, { cwd: ctx.cwd, enabled });
 	if (result.error) {
 		compactionNotify(ctx, `QOL handoff artifact write failed: ${result.error}`, "warning");
 	}

package/extensions/qol/constants.ts

@@ -74,7 +74,18 @@ export const DEFAULT_SESSION_SEARCH_PREVIEW_SNIPPETS = 6;
 export const DEFAULT_SESSION_SEARCH_SHORTCUT = "f2";
 export const DEFAULT_SESSION_SEARCH_SUMMARY_INPUT_CHARS = 180_000;
 export const DEFAULT_SESSION_SEARCH_SUMMARY_MAX_TOKENS = 4096;
-export const DEFAULT_SESSION_SEARCH_CACHE_TTL_SECONDS = 0;
+/** How long a loaded session-search index is kept. Past it the index is
+ *  released, and the next search loads it again. */
+export const DEFAULT_SESSION_SEARCH_CACHE_TTL_SECONDS = 300;
+/** Characters of one session's message text the search index keeps. */
+export const SESSION_SEARCH_TEXT_MAX_CHARS_PER_SESSION = 32_768;
+/** Characters of message text the whole search index keeps, newest session
+ *  first; sessions past it are searched by name, path and first prompt only. */
+export const SESSION_SEARCH_TEXT_MAX_CHARS = 8_388_608;
+/** Sessions whose user prompts the search overlay keeps parsed. */
+export const SESSION_SEARCH_USER_MESSAGES_MAX_SESSIONS = 64;
+/** Finished thinking blocks whose time a redrawn message can show again. */
+export const THINKING_TIMER_MAX_DURATIONS = 256;
 export const SESSION_SEARCH_OVERLAY_HEIGHT_RATIO = 0.9;
 
 export const DEFAULT_AUTO_RENAME_MODEL = "openai-codex/gpt-5.4-mini";

package/extensions/qol/glyphs.ts

@@ -1,4 +1,4 @@
-import { readPackageConfig } from "./settings.js";
+import { readPackageConfig } from "./package-config.js";
 
 export type GlyphStyle = "unicode" | "ascii";
 export type GlobalGlyphStyleOverride = "inherit" | GlyphStyle;

package/extensions/qol/images.ts

@@ -3,7 +3,8 @@ import { basename, resolve } from "node:path";
 import type { ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
 import { applyVisibleReplacements, buildVisibleMap, type VisibleReplacement } from "./ansi.js";
 import { IMAGE_EXTENSIONS, IMAGE_PATH_PATTERN } from "./constants.js";
-import { expandHome, settingBoolean } from "./settings.js";
+import { expandHome } from "./package-config.js";
+import { settingBoolean } from "./settings.js";
 
 function stripAtPrefix(path: string): string {
 	return path.startsWith("@") ? path.slice(1) : path;

package/extensions/qol/notifications.ts

@@ -22,6 +22,9 @@ export interface QolNotificationService {
 	notifyQuestionOpened(ctx: ExtensionContext | undefined, event: QuestionOpenedEventLike): boolean;
 }
 
+/** Last send time per notification key, for the cooldown. An entry older than
+ *  the cooldown suppresses nothing, so each send drops those; question keys
+ *  carry a request id, so without the drop the map grows per question. */
 const lastNotificationAt = new Map<string, number>();
 const lastQuestionNotificationAt = new Map<string, number>();
 let tmuxMarkedTarget: string | undefined;
@@ -288,6 +291,13 @@ function notificationEnabledFor(kind: QolNotificationKind, cwd?: string): boolea
 	}
 }
 
+/** Forget every notification cooldown and question dedup key; they belong to
+ *  the session that sent them. */
+export function resetQolNotificationCooldowns(): void {
+	lastNotificationAt.clear();
+	lastQuestionNotificationAt.clear();
+}
+
 /**
  * The window mark and the tmux message never touch the terminal, so they start
  * beside the terminal writes rather than behind them.
@@ -315,7 +325,10 @@ export function sendQolNotification(pi: QolNotificationExec, ctx: ExtensionConte
 	const now = Date.now();
 	const last = lastNotificationAt.get(key) ?? 0;
 	if (cooldownMs > 0 && now - last < cooldownMs) return Promise.resolve();
-	lastNotificationAt.set(key, now);
+	for (const [storedKey, sentAt] of lastNotificationAt) {
+		if (now - sentAt >= cooldownMs) lastNotificationAt.delete(storedKey);
+	}
+	if (cooldownMs > 0) lastNotificationAt.set(key, now);
 
 	const title = sanitizeNotificationPart(settingString("notification.title", DEFAULT_NOTIFICATION_TITLE, cwd), 80) || DEFAULT_NOTIFICATION_TITLE;
 	const text = sanitizeNotificationPart(body, Math.max(40, Math.floor(settingNumber("notification.bodyMaxChars", DEFAULT_NOTIFICATION_BODY_MAX_CHARS, cwd))));

package/extensions/qol/package-config.ts

@@ -0,0 +1,445 @@
+/**
+ * The settings reader every pi-extensions package vendors. Each package carries
+ * this file byte-identical, and `pi-extensions/package-policy.test.mjs` holds
+ * the copies equal: change one, then copy it over every other
+ * `package-config.ts` in the tree.
+ *
+ * It owns the Pi user directory, the project-trust registry and the
+ * `kendex.extensionManager.config` walk, and it provides the default
+ * settings-file order, `piSettingsPaths`. A package that finds its own project
+ * root, such as pi-hooks, passes its own path list to `readPackageConfigAt`.
+ * Widgets and renderers read settings many times per frame; going to the disk
+ * on each read kept every lane's render loop busy. A memoized answer is served
+ * for `SETTINGS_RECHECK_MS` with no filesystem, environment or path work. The
+ * memos are module state, so each package keeps its own; only the trust
+ * registry is shared by every package in the process.
+ * `installSettingsCacheRefresh` drops every answer when the extension manager
+ * announces a settings change and when a session starts.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+
+/** What pi-extension-manager emits on `pi.events` after it writes a setting. */
+export const SETTINGS_CHANGED_EVENT = "kendex:extension-settings-changed";
+
+/** How long a memoized answer is served before its inputs are read again. */
+export const SETTINGS_RECHECK_MS = 1000;
+
+export function expandHome(input: string): string {
+	if (input === "~") return homedir();
+	if (input.startsWith("~/")) return join(homedir(), input.slice(2));
+	return input;
+}
+
+/** Root-anchored as `crates/core/src/harness/pi.rs::pi_root_is_absolute_for`
+ * means it, which `isAbsolute` is not: it calls a driveless `\root` absolute
+ * where the renderer does not, putting the two on different roots. */
+export function rootAnchored(path: string, windows: boolean): boolean {
+	return windows ? /^(?:[A-Za-z]:[\\/]|[\\/]{2}[^\\/]+[\\/][^\\/]+)/.test(path) : path.startsWith("/");
+}
+
+/** The user directory and the environment it was resolved under. `HOME` and
+ * `USERPROFILE` are what `homedir()` reads, on POSIX and on Windows. */
+interface UserDir {
+	agentDir: string | undefined;
+	home: string | undefined;
+	profile: string | undefined;
+	dir: string;
+	settings: string;
+}
+
+let userDirMemo: UserDir | undefined;
+
+function userDir(): UserDir {
+	const agentDir = process.env.PI_CODING_AGENT_DIR;
+	const home = process.env.HOME;
+	const profile = process.env.USERPROFILE;
+	const known = userDirMemo;
+	if (known !== undefined && known.agentDir === agentDir && known.home === home && known.profile === profile) return known;
+	const override = expandHome(agentDir?.trim() || "");
+	const dir = resolve(rootAnchored(override, process.platform === "win32") ? override : expandHome("~/.pi/agent"));
+	userDirMemo = { agentDir, home, profile, dir, settings: join(dir, "settings.json") };
+	return userDirMemo;
+}
+
+/** A root-anchored `PI_CODING_AGENT_DIR`, else `~/.pi/agent`, for the
+ * environment of this call. The settings reads below memoize it instead,
+ * since reading the environment costs more than a warm read. */
+export function piUserDir(): string {
+	return userDir().dir;
+}
+
+interface MemoEntry {
+	/** `performance.now()`, a monotonic clock, so a backward wall-clock step
+	 * cannot hold an entry past its window. */
+	readAt: number;
+	fingerprint: string | undefined;
+	value: unknown;
+}
+
+const memo = new Map<string, MemoEntry>();
+
+/** Drops every memoized answer so the next read goes back to disk and to the
+ * environment. */
+export function clearPackageConfigCache(): void {
+	memo.clear();
+	cwdSettings.clear();
+	userSettingsMemo = undefined;
+}
+
+/** The entry for `key` while its window is open. */
+function openEntry(store: Map<string, MemoEntry>, key: string, now: number): MemoEntry | undefined {
+	const entry = store.get(key);
+	return entry !== undefined && now - entry.readAt < SETTINGS_RECHECK_MS ? entry : undefined;
+}
+
+/**
+ * `compute()` for `key`, served from memory for `SETTINGS_RECHECK_MS`. Once the
+ * window closes, `fingerprint` (when given) runs first, and a fingerprint equal
+ * to the one the value was computed under keeps the value, and its identity,
+ * for another window without calling `compute`. Without a fingerprint the
+ * value is computed again, and so is a value `reusable` answered `false` for,
+ * whatever the fingerprint says. `clearPackageConfigCache` drops every entry.
+ */
+export function settingsMemo<T>(key: string, compute: () => T, fingerprint?: () => string, reusable?: (value: T) => boolean): T {
+	return memoIn(memo, key, performance.now(), compute, fingerprint, reusable);
+}
+
+/** `settingsMemo` over `store` at `now`. One public read takes the clock
+ * once and hands it down, since reading it costs as much as a warm read. */
+function memoIn<T>(store: Map<string, MemoEntry>, key: string, now: number, compute: () => T, fingerprint?: () => string, reusable?: (value: T) => boolean): T {
+	const open = openEntry(store, key, now);
+	if (open !== undefined) return open.value as T;
+	const entry = store.get(key);
+	const print = fingerprint?.();
+	if (entry !== undefined && print !== undefined && entry.fingerprint === print) {
+		entry.readAt = now;
+		return entry.value as T;
+	}
+	const value = compute();
+	store.set(key, { readAt: now, fingerprint: reusable === undefined || reusable(value) ? print : undefined, value });
+	return value;
+}
+
+/** The project settings file for `cwd`: the nearest ancestor's
+ * `.pi/settings.json`, stopping at a `.pi`, `.git` or `.kendex-lock.json`. */
+export function projectSettingsPath(cwd: string): string {
+	let current = resolve(cwd);
+	while (true) {
+		const candidate = join(current, ".pi", "settings.json");
+		if (existsSync(candidate)) return candidate;
+		if (existsSync(join(current, ".pi")) || existsSync(join(current, ".git")) || existsSync(join(current, ".kendex-lock.json"))) return candidate;
+		const parent = dirname(current);
+		if (parent === current) return join(resolve(cwd), ".pi", "settings.json");
+		current = parent;
+	}
+}
+
+const PROJECT_TRUST_SYMBOL = Symbol.for("kendex.pi.project-trust");
+
+interface ProjectTrustRegistry {
+	projectSettings?: Map<string, boolean>;
+}
+
+/** The registry once found or made; no package replaces it after that. */
+let trustRegistry: ProjectTrustRegistry | undefined;
+
+/** Shared by every package in the process: whichever package records Pi's
+ * trust answer first, every package reads it. */
+function projectTrustRegistry(): ProjectTrustRegistry {
+	if (trustRegistry !== undefined) return trustRegistry;
+	const host = globalThis as unknown as Record<PropertyKey, ProjectTrustRegistry | undefined>;
+	trustRegistry = host[PROJECT_TRUST_SYMBOL] ?? {};
+	host[PROJECT_TRUST_SYMBOL] = trustRegistry;
+	return trustRegistry;
+}
+
+/**
+ * Pi's answer to "has this person trusted this workspace". Only a plain `true`
+ * counts: a Pi with no such method, or one that throws, is not trusted. The
+ * answer gates reading a project's settings and running a project's own
+ * scripts, both safe to withhold and unsafe to grant by accident.
+ */
+export function projectTrusted(ctx: { isProjectTrusted?: () => boolean }): boolean {
+	try {
+		return ctx.isProjectTrusted?.() === true;
+	} catch {
+		return false;
+	}
+}
+
+/** Records Pi's trust answer against the settings file `settingsPath`. */
+export function recordSettingsTrust(settingsPath: string, ctx: { isProjectTrusted?: () => boolean }): void {
+	const registry = projectTrustRegistry();
+	if (!registry.projectSettings) registry.projectSettings = new Map();
+	registry.projectSettings.set(settingsPath, projectTrusted(ctx));
+}
+
+export function recordProjectTrust(ctx: { cwd?: string; isProjectTrusted?: () => boolean }): void {
+	if (!ctx.cwd) return;
+	recordSettingsTrust(projectSettingsPath(ctx.cwd), ctx);
+}
+
+/** Read on every call, never memoized: a trust answer recorded by any package
+ * takes effect on the next read. */
+export function settingsFileTrusted(settingsPath: string): boolean {
+	return projectTrustRegistry().projectSettings?.get(settingsPath) === true;
+}
+
+/** The project settings file for `cwd` when Pi trusts the project, else
+ * `undefined`. */
+export function trustedProjectSettingsPath(cwd = process.cwd()): string | undefined {
+	const view = cwdSettingsAt(cwd, performance.now());
+	return view.trusted ? view.project : undefined;
+}
+
+export function projectSettingsTrustedForCwd(cwd = process.cwd()): boolean {
+	return trustedProjectSettingsPath(cwd) !== undefined;
+}
+
+/** The user settings file, resolved from the environment at most once per
+ * window. */
+let userSettingsMemo: { readAt: number; path: string } | undefined;
+
+function userSettingsPathAt(now: number): string {
+	const known = userSettingsMemo;
+	if (known !== undefined && now - known.readAt < SETTINGS_RECHECK_MS) return known.path;
+	const path = userDir().settings;
+	userSettingsMemo = { readAt: now, path };
+	return path;
+}
+
+/** The user settings file the lists below were built on; a new user directory
+ * starts a new set of lists. */
+let pathListsUser: string | undefined;
+const pathLists = new Map<string | undefined, readonly string[]>();
+
+/**
+ * The user settings file, then `project` when given. One frozen list per
+ * answer, so `readSettingsFiles` finds its memo by the list's identity. The
+ * caller decides whether `project` is trusted.
+ */
+export function userAndProjectSettingsPaths(project: string | undefined): readonly string[] {
+	return userAndProjectSettingsPathsAt(project, performance.now());
+}
+
+function userAndProjectSettingsPathsAt(project: string | undefined, now: number): readonly string[] {
+	const user = userSettingsPathAt(now);
+	if (user !== pathListsUser) {
+		pathLists.clear();
+		pathListsUser = user;
+	}
+	let paths = pathLists.get(project);
+	if (paths === undefined) {
+		paths = Object.freeze(project === undefined ? [user] : [user, project]);
+		pathLists.set(project, paths);
+	}
+	return paths;
+}
+
+/** The user settings file, then the project's when Pi trusts the project. */
+export function piSettingsPaths(cwd = process.cwd()): readonly string[] {
+	return cwdSettingsAt(cwd, performance.now()).paths;
+}
+
+export type SettingsRecord = Record<string, unknown>;
+
+/** One settings file that exists. A file that does not parse, or that cannot be
+ * read for any reason but its absence, is `malformed`; a document that parses
+ * to something other than an object reads as an empty one. */
+export type SettingsFile =
+	| { kind: "parsed"; path: string; settings: Readonly<SettingsRecord> }
+	| { kind: "malformed"; path: string; error: string };
+
+function isRecord(value: unknown): value is SettingsRecord {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+/** Memoized values are shared by every caller, so a caller that wrote into one
+ * would change what the next caller reads. Frozen, that write throws instead. */
+function deepFreeze<T>(value: T): T {
+	if (value && typeof value === "object" && !Object.isFrozen(value)) {
+		Object.freeze(value);
+		for (const child of Object.values(value)) deepFreeze(child);
+	}
+	return value;
+}
+
+type FileText = { kind: "absent" } | { kind: "text"; text: string } | { kind: "unreadable"; error: string };
+
+function readText(path: string): FileText {
+	try {
+		return { kind: "text", text: readFileSync(path, "utf8") };
+	} catch (error) {
+		const code = (error as { code?: unknown } | null)?.code;
+		if (code === "ENOENT" || code === "ENOTDIR") return { kind: "absent" };
+		return { kind: "unreadable", error: error instanceof Error ? error.message : String(error) };
+	}
+}
+
+/** Each path list's memo key, so a list a caller keeps is joined once. */
+const settingsFilesKeys = new WeakMap<readonly string[], string>();
+
+function settingsFilesKey(paths: readonly string[]): string {
+	let key = settingsFilesKeys.get(paths);
+	if (key === undefined) {
+		key = `settings-files\0${paths.join("\0")}`;
+		settingsFilesKeys.set(paths, key);
+	}
+	return key;
+}
+
+/**
+ * The files at `paths` that exist, in order. Each window re-reads their text;
+ * text equal to what the last parse saw keeps the last answer, so an unchanged
+ * file is parsed once and its callers keep one identity for it.
+ */
+export function readSettingsFiles(paths: readonly string[]): readonly SettingsFile[] {
+	return readSettingsFilesAt(paths, performance.now());
+}
+
+function readSettingsFilesAt(paths: readonly string[], now: number): readonly SettingsFile[] {
+	const key = settingsFilesKey(paths);
+	// Checked before the closures below exist, so a warm read allocates nothing.
+	const open = openEntry(memo, key, now);
+	if (open !== undefined) return open.value as readonly SettingsFile[];
+	let texts: FileText[] = [];
+	return memoIn(
+		memo,
+		key,
+		now,
+		() =>
+			deepFreeze(
+				paths.flatMap((path, index): SettingsFile[] => {
+					const text = texts[index] ?? readText(path);
+					if (text.kind === "absent") return [];
+					if (text.kind === "unreadable") return [{ kind: "malformed", path, error: text.error }];
+					try {
+						const parsed: unknown = JSON.parse(text.text);
+						return [{ kind: "parsed", path, settings: isRecord(parsed) ? parsed : {} }];
+					} catch (error) {
+						return [{ kind: "malformed", path, error: error instanceof Error ? error.message : String(error) }];
+					}
+				}),
+			),
+		() => {
+			texts = paths.map(readText);
+			return JSON.stringify(texts);
+		},
+	);
+}
+
+/** `packageId`'s object under `kendex.extensionManager.config` in one parsed
+ * settings document, or `undefined` where it holds none. */
+export function packageConfigIn(settings: Readonly<SettingsRecord>, packageId: string): Readonly<SettingsRecord> | undefined {
+	const kendex = settings.kendex;
+	const manager = isRecord(kendex) ? kendex.extensionManager : undefined;
+	const config = isRecord(manager) ? manager.config : undefined;
+	const own = isRecord(config) ? config[packageId] : undefined;
+	return isRecord(own) ? own : undefined;
+}
+
+/** What reads for one cwd resolve to: its project settings file, the trust
+ * answer its paths were built under, the files at those paths and the configs
+ * merged over them. */
+interface CwdSettings {
+	readAt: number;
+	project: string;
+	trusted: boolean;
+	paths: readonly string[];
+	files: readonly SettingsFile[];
+	configs: Map<string, Readonly<SettingsRecord>>;
+}
+
+const cwdSettings = new Map<string, CwdSettings>();
+
+/**
+ * The settings for `cwd`, served for `SETTINGS_RECHECK_MS` with one map
+ * lookup and the trust lookup: no environment, path or file work. Trust is
+ * read on every call, so an answer any package records applies at once. Once
+ * the window closes, the project walk runs again, and the user settings file
+ * and the files come from their own memos.
+ */
+function cwdSettingsAt(cwd: string, now: number): CwdSettings {
+	const known = cwdSettings.get(cwd);
+	const open = known !== undefined && now - known.readAt < SETTINGS_RECHECK_MS ? known : undefined;
+	if (open !== undefined && settingsFileTrusted(open.project) === open.trusted) return open;
+	const project = open !== undefined ? open.project : projectSettingsPath(cwd);
+	const trusted = settingsFileTrusted(project);
+	const paths = userAndProjectSettingsPathsAt(trusted ? project : undefined, now);
+	const files = readSettingsFilesAt(paths, now);
+	// The files may come from a window another cwd opened; this view closes
+	// with it, so an edit is never served for longer than one window.
+	const filesReadAt = memo.get(settingsFilesKey(paths))?.readAt ?? now;
+	const readAt = Math.min(open !== undefined ? open.readAt : now, filesReadAt);
+	const view: CwdSettings = { readAt, project, trusted, paths, files, configs: configsOver(files) };
+	cwdSettings.set(cwd, view);
+	return view;
+}
+
+/** Merged configs per package id, keyed by the file list they were merged
+ * from: `readSettingsFiles` hands back a new list whenever a file changed. */
+const configsByFiles = new WeakMap<readonly SettingsFile[], Map<string, Readonly<SettingsRecord>>>();
+
+/** `packageId`'s config over the files at `paths`, later files overriding
+ * earlier ones key by key. A malformed file contributes nothing. */
+export function readPackageConfigAt(packageId: string, paths: readonly string[]): Readonly<SettingsRecord> {
+	const files = readSettingsFiles(paths);
+	return packageConfigOver(packageId, files, configsOver(files));
+}
+
+function configsOver(files: readonly SettingsFile[]): Map<string, Readonly<SettingsRecord>> {
+	let configs = configsByFiles.get(files);
+	if (!configs) {
+		configs = new Map();
+		configsByFiles.set(files, configs);
+	}
+	return configs;
+}
+
+function packageConfigOver(packageId: string, files: readonly SettingsFile[], configs: Map<string, Readonly<SettingsRecord>>): Readonly<SettingsRecord> {
+	const known = configs.get(packageId);
+	if (known) return known;
+	const merged: SettingsRecord = {};
+	for (const file of files) {
+		if (file.kind !== "parsed") continue;
+		const config = packageConfigIn(file.settings, packageId);
+		if (config) Object.assign(merged, config);
+	}
+	const frozen = Object.freeze(merged);
+	configs.set(packageId, frozen);
+	return frozen;
+}
+
+/** `packageId`'s config over `piSettingsPaths(cwd)`. */
+export function readPackageConfig(packageId: string, cwd = process.cwd()): Readonly<SettingsRecord> {
+	const view = cwdSettingsAt(cwd, performance.now());
+	return packageConfigOver(packageId, view.files, view.configs);
+}
+
+/** The part of Pi's `ExtensionAPI` the refresh needs. */
+export interface SettingsRefreshHost {
+	on(event: "session_start", handler: () => void): unknown;
+	on(event: "session_shutdown", handler: () => void): unknown;
+	events: { on(channel: string, handler: (data: unknown) => void): () => void };
+}
+
+/**
+ * Drops every memoized answer when a session starts, which is where the cwd
+ * and the project's trust can change, and whenever pi-extension-manager
+ * announces a settings change. The subscription lives from `session_start` to
+ * `session_shutdown`, as Pi asks of any listener.
+ */
+export function installSettingsCacheRefresh(pi: SettingsRefreshHost): void {
+	let unsubscribe: (() => void) | undefined;
+	pi.on("session_start", () => {
+		clearPackageConfigCache();
+		unsubscribe ??= pi.events.on(SETTINGS_CHANGED_EVENT, () => clearPackageConfigCache());
+	});
+	pi.on("session_shutdown", () => {
+		unsubscribe?.();
+		unsubscribe = undefined;
+		clearPackageConfigCache();
+	});
+}