@oh-my-pi/pi-coding-agent 15.7.1 → 15.7.3

package/src/config/config-file.ts

@@ -10,18 +10,44 @@ interface ConfigSchemaError {
 	message: string | undefined;
 }
 
+/**
+ * Module-private cache of (jsonPath, ymlPath) pairs we already migrated this
+ * process. Prevents `ConfigFile.relocate()` / repeated `tryLoad()` calls from
+ * re-running the migration over and over on the boot path.
+ */
+const migratedPaths = new Set<string>();
+
+function migrationKey(jsonPath: string, ymlPath: string): string {
+	return `${jsonPath}\u0000${ymlPath}`;
+}
+
+/**
+ * Synchronous JSON → YAML migration kept for callers that still want the
+ * eager path (settings init, tests that observe migration completion).
+ * Idempotent — re-running is a no-op.
+ */
 function migrateJsonToYml(jsonPath: string, ymlPath: string) {
+	const key = migrationKey(jsonPath, ymlPath);
+	if (migratedPaths.has(key)) return;
 	try {
-		if (fs.existsSync(ymlPath)) return;
-		if (!fs.existsSync(jsonPath)) return;
+		if (fs.existsSync(ymlPath)) {
+			migratedPaths.add(key);
+			return;
+		}
+		if (!fs.existsSync(jsonPath)) {
+			migratedPaths.add(key);
+			return;
+		}
 
 		const content = fs.readFileSync(jsonPath, "utf-8");
 		const parsed = JSON.parse(content);
 		if (!parsed) {
 			logger.warn("migrateJsonToYml: invalid json structure", { path: jsonPath });
+			migratedPaths.add(key);
 			return;
 		}
 		fs.writeFileSync(ymlPath, YAML.stringify(parsed, null, 2));
+		migratedPaths.add(key);
 	} catch (error) {
 		logger.warn("migrateJsonToYml: migration failed", { error: String(error) });
 	}
@@ -97,6 +123,7 @@ export type LoadResult<T> =
 
 export class ConfigFile<T> implements IConfigFile<T> {
 	readonly #basePath: string;
+	readonly #jsonMigrationPath: string | null;
 	#cache?: LoadResult<T>;
 	#auxValidate?: (value: T) => void;
 
@@ -107,22 +134,32 @@ export class ConfigFile<T> implements IConfigFile<T> {
 	) {
 		this.#basePath = configPath;
 		if (configPath.endsWith(".yml")) {
-			const jsonPath = `${configPath.slice(0, -4)}.json`;
-			migrateJsonToYml(jsonPath, configPath);
+			this.#jsonMigrationPath = `${configPath.slice(0, -4)}.json`;
 		} else if (configPath.endsWith(".yaml")) {
-			const jsonPath = `${configPath.slice(0, -5)}.json`;
-			migrateJsonToYml(jsonPath, configPath);
+			this.#jsonMigrationPath = `${configPath.slice(0, -5)}.json`;
 		} else if (configPath.endsWith(".json") || configPath.endsWith(".jsonc")) {
 			// JSON configs are still supported without migration.
+			this.#jsonMigrationPath = null;
 		} else {
 			throw new Error(`Invalid config file path: ${configPath}`);
 		}
 	}
 
+	/**
+	 * Run the JSON → YAML migration synchronously, if applicable. Idempotent.
+	 * Sync callers (tests, settings init) hit this implicitly via {@link tryLoad}.
+	 */
+	#ensureMigrated(): void {
+		if (this.#jsonMigrationPath) {
+			migrateJsonToYml(this.#jsonMigrationPath, this.#basePath);
+		}
+	}
+
 	relocate(configPath?: string): ConfigFile<T> {
 		if (!configPath || configPath === this.#basePath) return this;
 		const result = new ConfigFile<T>(this.id, this.schema, configPath);
 		result.#auxValidate = this.#auxValidate;
+		result.#ensureMigrated();
 		return result;
 	}
 
@@ -135,6 +172,13 @@ export class ConfigFile<T> implements IConfigFile<T> {
 		}
 	}
 
+	async getMtimeMsAsync(): Promise<number | null> {
+		const file = Bun.file(this.path());
+		if (!(await file.exists())) return null;
+		const lm = file.lastModified;
+		return typeof lm === "number" && Number.isFinite(lm) ? lm : null;
+	}
+
 	withValidation(name: string, validate: (value: T) => void): this {
 		const prev = this.#auxValidate;
 		this.#auxValidate = (value: T) => {
@@ -164,12 +208,8 @@ export class ConfigFile<T> implements IConfigFile<T> {
 		return result;
 	}
 
-	tryLoad(): LoadResult<T> {
-		if (this.#cache) return this.#cache;
-
+	#parseContent(content: string): LoadResult<T> {
 		try {
-			const content = fs.readFileSync(this.path(), "utf-8").trim();
-
 			let parsed: unknown;
 			if (this.#basePath.endsWith(".json") || this.#basePath.endsWith(".jsonc")) {
 				parsed = JSONC.parse(content);
@@ -202,26 +242,71 @@ export class ConfigFile<T> implements IConfigFile<T> {
 				return this.#storeCache({ error: wrapped, status: "error" });
 			}
 			return this.#storeCache({ value, status: "ok" });
+		} catch (error) {
+			logger.warn("Failed to parse config file", { path: this.path(), error });
+			return this.#storeCache({
+				error: new ConfigError(this.id, undefined, { err: error, stage: "Unexpected" }),
+				status: "error",
+			});
+		}
+	}
+
+	tryLoad(): LoadResult<T> {
+		if (this.#cache) return this.#cache;
+		this.#ensureMigrated();
+
+		let content: string;
+		try {
+			content = fs.readFileSync(this.path(), "utf-8").trim();
 		} catch (error) {
 			if (isEnoent(error)) {
 				return this.#storeCache({ status: "not-found" });
 			}
-			logger.warn("Failed to parse config file", { path: this.path(), error });
+			logger.warn("Failed to read config file", { path: this.path(), error });
 			return this.#storeCache({
-				error: new ConfigError(this.id, undefined, { err: error, stage: "Unexpected" }),
+				error: new ConfigError(this.id, undefined, { err: error, stage: "Read" }),
+				status: "error",
+			});
+		}
+		return this.#parseContent(content);
+	}
+
+	async tryLoadAsync(): Promise<LoadResult<T>> {
+		if (this.#cache) return this.#cache;
+		this.#ensureMigrated();
+
+		let content: string;
+		try {
+			content = (await Bun.file(this.path()).text()).trim();
+		} catch (error) {
+			if (isEnoent(error)) {
+				return this.#storeCache({ status: "not-found" });
+			}
+			logger.warn("Failed to read config file", { path: this.path(), error });
+			return this.#storeCache({
+				error: new ConfigError(this.id, undefined, { err: error, stage: "Read" }),
 				status: "error",
 			});
 		}
+		return this.#parseContent(content);
 	}
 
 	load(): T | null {
 		return this.tryLoad().value ?? null;
 	}
 
+	async loadAsync(): Promise<T | null> {
+		return (await this.tryLoadAsync()).value ?? null;
+	}
+
 	loadOrDefault(): T {
 		return this.tryLoad().value ?? this.createDefault();
 	}
 
+	async loadOrDefaultAsync(): Promise<T> {
+		return (await this.tryLoadAsync()).value ?? this.createDefault();
+	}
+
 	path(): string {
 		return this.#basePath;
 	}

package/src/config/file-lock.ts

@@ -1,5 +1,6 @@
+import { randomUUID } from "node:crypto";
 import * as fs from "node:fs/promises";
-import { isEnoent } from "@oh-my-pi/pi-utils";
+import { isEnoent, logger } from "@oh-my-pi/pi-utils";
 
 export interface FileLockOptions {
 	staleMs?: number;
@@ -16,14 +17,15 @@ const DEFAULT_OPTIONS: Required<FileLockOptions> = {
 interface LockInfo {
 	pid: number;
 	timestamp: number;
+	token: string;
 }
 
 function getLockPath(filePath: string): string {
 	return `${filePath}.lock`;
 }
 
-async function writeLockInfo(lockPath: string): Promise<void> {
-	const info: LockInfo = { pid: process.pid, timestamp: Date.now() };
+async function writeLockInfo(lockPath: string, token: string): Promise<void> {
+	const info: LockInfo = { pid: process.pid, timestamp: Date.now(), token };
 	await Bun.write(`${lockPath}/info`, JSON.stringify(info));
 }
 
@@ -47,33 +49,58 @@ function isProcessAlive(pid: number): boolean {
 
 async function isLockStale(lockPath: string, staleMs: number): Promise<boolean> {
 	const info = await readLockInfo(lockPath);
-	if (!info) return true;
-
-	if (!isProcessAlive(info.pid)) return true;
-
-	if (Date.now() - info.timestamp > staleMs) return true;
+	if (info) {
+		if (!isProcessAlive(info.pid)) return true;
+		if (Date.now() - info.timestamp > staleMs) return true;
+		return false;
+	}
 
-	return false;
+	// No info file. Either the lock holder is between mkdir and writeLockInfo
+	// (fresh dir, do not reap) or the dir was already removed (also do not
+	// reap — there is nothing to clean up, and an unguarded fs.rm here would
+	// race with another contender's successful mkdir and wipe their dir).
+	try {
+		const stat = await fs.stat(lockPath);
+		return Date.now() - stat.mtimeMs > staleMs;
+	} catch (err) {
+		if (isEnoent(err)) return false;
+		throw err;
+	}
 }
 
-async function tryAcquireLock(lockPath: string): Promise<boolean> {
+async function tryAcquireLock(lockPath: string): Promise<string | null> {
 	try {
 		await fs.mkdir(lockPath);
-		await writeLockInfo(lockPath);
-		return true;
+		const token = randomUUID();
+		await writeLockInfo(lockPath, token);
+		return token;
 	} catch (error) {
 		if ((error as NodeJS.ErrnoException).code === "EEXIST") {
-			return false;
+			return null;
 		}
 		throw error;
 	}
 }
 
-async function releaseLock(lockPath: string): Promise<void> {
+async function releaseLock(lockPath: string, expectedToken?: string): Promise<void> {
 	try {
+		if (expectedToken !== undefined) {
+			const info = await readLockInfo(lockPath);
+			if (!info || info.token !== expectedToken) {
+				// We are not the owner. The lock either expired and was reaped
+				// or another process has reclaimed it. Do nothing — releasing
+				// here would wipe the rightful owner's lock.
+				logger.debug("file-lock: skipping release for non-owned lock", {
+					lockPath,
+					expectedToken,
+					actualToken: info?.token,
+				});
+				return;
+			}
+		}
 		await fs.rm(lockPath, { recursive: true });
 	} catch {
-		// Ignore errors on release
+		// Ignore errors on release.
 	}
 }
 
@@ -92,11 +119,14 @@ async function acquireLock(filePath: string, options: FileLockOptions = {}): Pro
 	const lockPath = getLockPath(filePath);
 
 	for (let attempt = 0; attempt < opts.retries; attempt++) {
-		if (await tryAcquireLock(lockPath)) {
-			return () => releaseLock(lockPath);
+		const token = await tryAcquireLock(lockPath);
+		if (token !== null) {
+			return () => releaseLock(lockPath, token);
 		}
 
 		if ((await lockExists(lockPath)) && (await isLockStale(lockPath, opts.staleMs))) {
+			// Reaping a stale lock — no token because we didn't acquire it. The
+			// rightful owner is presumed dead; rm without ownership check.
 			await releaseLock(lockPath);
 			continue;
 		}
@@ -119,3 +149,16 @@ export async function withFileLock<T>(
 		await release();
 	}
 }
+
+/**
+ * Test-only handles for the internal lock primitives. These are NOT part of
+ * the public API — they exist so the contract tests can validate token-keyed
+ * release semantics and the mkdir-race window without re-implementing them.
+ */
+export const __internalsForTesting = {
+	tryAcquireLock,
+	releaseLock,
+	readLockInfo,
+	isLockStale,
+	getLockPath,
+};

package/src/config/keybindings.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import * as fs from "node:fs";
 import * as path from "node:path";
 import {
 	type Keybinding,
@@ -10,6 +10,7 @@ import {
 	KeybindingsManager as TuiKeybindingsManager,
 } from "@oh-my-pi/pi-tui";
 import { getAgentDir, isEnoent, logger } from "@oh-my-pi/pi-utils";
+import { YAML } from "bun";
 
 /**
  * Application-level keybindings (coding agent specific).
@@ -330,17 +331,29 @@ function orderKeybindingsConfig(config: KeybindingsConfig): KeybindingsConfig {
 	return ordered;
 }
 
+const KEYBINDINGS_YML = "keybindings.yml";
+const KEYBINDINGS_YAML = "keybindings.yaml";
+const LEGACY_KEYBINDINGS_JSON = "keybindings.json";
+
+interface KeybindingsConfigPaths {
+	readPath: string;
+	writeBackPath: string;
+}
+
 /**
  * Load raw config from a file synchronously.
- * Returns parsed JSON or null if file doesn't exist or is invalid.
+ * Returns parsed JSON/YAML or null if file doesn't exist or is invalid.
  */
 function loadRawConfig(filePath: string): unknown {
 	try {
-		if (!existsSync(filePath)) {
-			return null;
+		const content = fs.readFileSync(filePath, "utf-8");
+		if (filePath.endsWith(".json")) {
+			return JSON.parse(content);
+		}
+		if (filePath.endsWith(".yml") || filePath.endsWith(".yaml")) {
+			return YAML.parse(content);
 		}
-		const content = readFileSync(filePath, "utf-8");
-		return JSON.parse(content);
+		throw new Error(`Unsupported keybindings config extension: ${filePath}`);
 	} catch (error) {
 		if (isEnoent(error)) {
 			return null;
@@ -350,34 +363,67 @@ function loadRawConfig(filePath: string): unknown {
 	}
 }
 
+function writeKeybindingsConfig(filePath: string, config: KeybindingsConfig): boolean {
+	try {
+		fs.writeFileSync(filePath, YAML.stringify(config, null, 2), "utf-8");
+		logger.debug("Migrated keybindings config", { path: filePath });
+		return true;
+	} catch (error) {
+		logger.warn("Failed to write migrated keybindings config", { path: filePath, error: String(error) });
+		return false;
+	}
+}
+
+function resolveKeybindingsConfigPaths(agentDir: string): KeybindingsConfigPaths {
+	const ymlPath = path.join(agentDir, KEYBINDINGS_YML);
+	if (fs.existsSync(ymlPath)) {
+		return { readPath: ymlPath, writeBackPath: ymlPath };
+	}
+
+	const yamlPath = path.join(agentDir, KEYBINDINGS_YAML);
+	if (fs.existsSync(yamlPath)) {
+		return { readPath: yamlPath, writeBackPath: yamlPath };
+	}
+
+	const jsonPath = path.join(agentDir, LEGACY_KEYBINDINGS_JSON);
+	if (fs.existsSync(jsonPath)) {
+		return { readPath: jsonPath, writeBackPath: ymlPath };
+	}
+
+	return { readPath: ymlPath, writeBackPath: ymlPath };
+}
+
 /**
- * Migrate keybindings config file from old format to new.
- * Reads from agentDir/keybindings.json, migrates old names, and writes back.
+ * Load and migrate keybindings config.
+ * Legacy JSON is read for compatibility, but successful write-back goes to YAML.
  */
-function loadKeybindingsConfig(filePath: string, writeBack: boolean): KeybindingsConfig {
+function loadKeybindingsConfig(
+	filePath: string,
+	writeBackPath: string | undefined,
+): {
+	config: KeybindingsConfig;
+	persistedPath: string;
+} {
 	const rawConfig = loadRawConfig(filePath);
 
 	if (rawConfig === null) {
-		return {};
+		return { config: {}, persistedPath: filePath };
 	}
 
 	const { config: migratedConfig, migrated } = migrateKeybindingNames(rawConfig);
-	if (writeBack && migrated) {
+	const shouldWriteBack = writeBackPath !== undefined && (migrated || writeBackPath !== filePath);
+	if (shouldWriteBack) {
 		const ordered = orderKeybindingsConfig(migratedConfig);
-		try {
-			writeFileSync(filePath, `${JSON.stringify(ordered, null, 2)}\n`, "utf-8");
-			logger.debug("Migrated keybindings config", { path: filePath });
-		} catch (error) {
-			logger.warn("Failed to write migrated keybindings config", { path: filePath, error: String(error) });
-		}
+		const persistedPath = writeKeybindingsConfig(writeBackPath, ordered) ? writeBackPath : filePath;
+		return { config: migratedConfig, persistedPath };
 	}
 
-	return migratedConfig;
+	return { config: migratedConfig, persistedPath: filePath };
 }
 
 function migrateKeybindingsConfigFile(agentDir: string): void {
-	const configPath = path.join(agentDir, "keybindings.json");
-	loadKeybindingsConfig(configPath, true);
+	const { readPath, writeBackPath } = resolveKeybindingsConfigPaths(agentDir);
+	loadKeybindingsConfig(readPath, writeBackPath);
 }
 
 /**
@@ -393,12 +439,13 @@ export class KeybindingsManager extends TuiKeybindingsManager {
 	}
 
 	/**
-	 * Create from config file at agentDir/keybindings.json.
+	 * Create from config file at agentDir/keybindings.yml.
+	 * Legacy keybindings.json is migrated to keybindings.yml on load.
 	 */
 	static create(agentDir: string = getAgentDir()): KeybindingsManager {
-		const configPath = path.join(agentDir, "keybindings.json");
-		const userBindings = KeybindingsManager.#loadFromFile(configPath);
-		const manager = new KeybindingsManager(userBindings, configPath);
+		const { readPath, writeBackPath } = resolveKeybindingsConfigPaths(agentDir);
+		const { config: userBindings, persistedPath } = KeybindingsManager.#loadFromFile(readPath, writeBackPath);
+		const manager = new KeybindingsManager(userBindings, persistedPath);
 		// Set globally so getKeybindings() returns this manager
 		setKeybindings(manager);
 		return manager;
@@ -416,7 +463,8 @@ export class KeybindingsManager extends TuiKeybindingsManager {
 	 */
 	reload(): void {
 		if (!this.#configPath) return;
-		this.setUserBindings(KeybindingsManager.#loadFromFile(this.#configPath));
+		const { config } = KeybindingsManager.#loadFromFile(this.#configPath);
+		this.setUserBindings(config);
 	}
 
 	/**
@@ -437,8 +485,11 @@ export class KeybindingsManager extends TuiKeybindingsManager {
 	/**
 	 * Load user bindings from a file, migrating old names if needed.
 	 */
-	static #loadFromFile(filePath: string): KeybindingsConfig {
-		return loadKeybindingsConfig(filePath, true);
+	static #loadFromFile(
+		filePath: string,
+		writeBackPath?: string,
+	): { config: KeybindingsConfig; persistedPath: string } {
+		return loadKeybindingsConfig(filePath, writeBackPath);
 	}
 }
 

package/src/config/model-registry.ts

@@ -851,6 +851,12 @@ export class ModelRegistry {
 
 	/**
 	 * @param authStorage - Auth storage for API key resolution
+	 *
+	 * Sync constructor — eagerly loads bundled + cached models so tests and
+	 * synchronous callers see a fully-populated registry immediately. Production
+	 * boot paths SHOULD prefer {@link ModelRegistry.create} so the YAML/JSONC
+	 * migration step lands off the event loop's hot path before the first
+	 * `tryLoad()` runs.
 	 */
 	constructor(
 		readonly authStorage: AuthStorage,
@@ -866,7 +872,7 @@ export class ModelRegistry {
 			}
 			return undefined;
 		});
-		// Load models synchronously in constructor
+		// Load models synchronously in constructor.
 		this.#loadModels();
 	}