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

package/src/cli/args.ts

@@ -54,7 +54,12 @@ export interface Args {
 	unknownFlags: Map<string, boolean | string>;
 }
 
-export function parseArgs(args: string[], extensionFlags?: Map<string, { type: "boolean" | "string" }>): Args {
+export function parseArgs(inputArgs: string[], extensionFlags?: Map<string, { type: "boolean" | "string" }>): Args {
+	// Work on a copy: the `--option=value` handling below splices the value
+	// into the array, and callers reuse the same argv (the post-extension
+	// reparse in `runRootCommand` parses it a second time). Mutating the input
+	// would corrupt that later parse, so never touch the caller's array.
+	const args = [...inputArgs];
 	const result: Args = {
 		messages: [],
 		fileArgs: [],
@@ -63,17 +68,41 @@ export function parseArgs(args: string[], extensionFlags?: Map<string, { type: "
 
 	for (let i = 0; i < args.length; i++) {
 		let arg = args[i];
+		const flagIndex = i;
 
-		// Support --flag=value syntax (e.g. --tools=ask,read)
+		// Support --flag=value syntax (e.g. --tools=ask,read). The value is
+		// spliced in as the next token so value-consuming flags pick it up via
+		// `args[++i]`; a non-consuming flag (e.g. a boolean) leaves it behind and
+		// the post-loop guard drops it so it is not mistaken for a message.
+		let equalsValueIndex = -1;
 		if (arg.startsWith("--") && arg.includes("=")) {
 			const eqIdx = arg.indexOf("=");
 			const value = arg.slice(eqIdx + 1);
 			arg = arg.slice(0, eqIdx);
-			// Insert the value so the existing "args[++i]" logic picks it up
 			args.splice(i + 1, 0, value);
+			equalsValueIndex = i + 1;
 		}
 
-		if (arg === "--help" || arg === "-h") {
+		// Extension-registered flags take precedence over built-ins: a flag an
+		// extension owns (e.g. plan-mode's boolean `--plan`) is parsed with the
+		// extension's semantics rather than falling into a built-in branch. For a
+		// value-taking built-in (`--plan`, `--model`, …) that branch would consume
+		// the following token — eating the user's message and setting the wrong
+		// built-in field — so registered flags shadow same-named built-ins here.
+		const extFlag = arg.startsWith("--") ? extensionFlags?.get(arg.slice(2)) : undefined;
+		if (extFlag) {
+			const flagName = arg.slice(2);
+			if (extFlag.type === "boolean") {
+				result.unknownFlags.set(flagName, true);
+			} else if (extFlag.type === "string" && i + 1 < args.length) {
+				// Consume the value in `--flag=value` form, or when the next token is
+				// not flag-looking. A `-`-prefixed token in space form is left to be
+				// its own flag; pass a flag-looking value as `--flag=value`.
+				if (equalsValueIndex !== -1 || !args[i + 1].startsWith("-")) {
+					result.unknownFlags.set(flagName, args[++i]);
+				}
+			}
+		} else if (arg === "--help" || arg === "-h") {
 			result.help = true;
 		} else if (arg === "--version" || arg === "-v") {
 			result.version = true;
@@ -198,21 +227,15 @@ export function parseArgs(args: string[], extensionFlags?: Map<string, { type: "
 			}
 		} else if (arg.startsWith("@")) {
 			result.fileArgs.push(arg.slice(1)); // Remove @ prefix
-		} else if (arg.startsWith("--") && extensionFlags) {
-			// Check if it's an extension-registered flag
-			const flagName = arg.slice(2);
-			const extFlag = extensionFlags.get(flagName);
-			if (extFlag) {
-				if (extFlag.type === "boolean") {
-					result.unknownFlags.set(flagName, true);
-				} else if (extFlag.type === "string" && i + 1 < args.length) {
-					result.unknownFlags.set(flagName, args[++i]);
-				}
-			}
-			// Unknown flags without extensionFlags are silently ignored (first pass)
 		} else if (!arg.startsWith("-")) {
 			result.messages.push(arg);
 		}
+		// Drop an unconsumed `--flag=value` value (e.g. a boolean flag): when no
+		// branch advanced past the spliced token, remove it so it does not fall
+		// through to a later iteration and become a positional message.
+		if (equalsValueIndex !== -1 && i === flagIndex) {
+			args.splice(equalsValueIndex, 1);
+		}
 	}
 
 	return result;

package/src/cli/extension-flags.ts

@@ -0,0 +1,48 @@
+import { type Args, parseArgs } from "./args";
+
+/**
+ * Minimal extension-runner surface needed to resolve CLI flag values. The real
+ * `ExtensionRunner` satisfies this structurally; depending only on the surface
+ * keeps this module free of the heavier runner/session imports and unit-testable
+ * with a fake.
+ */
+export interface ExtensionFlagSink {
+	getFlags(): Map<string, { type: "boolean" | "string" }>;
+	setFlagValue(name: string, value: boolean | string): void;
+}
+
+/**
+ * Resolve extension-registered CLI flags from `rawArgs` once the flag set is
+ * known, push the resolved values onto the sink, and return the parsed
+ * {@link Args} (whose `messages` and `fileArgs` now reflect those flags).
+ *
+ * The startup parse runs before extensions load, so it cannot recognise their
+ * flags: a string flag's value (`--spawn-peer reviewer` or `--spawn-peer=reviewer`)
+ * is otherwise left in `messages` and leaks into the initial prompt. Re-parsing
+ * here — through the *same* {@link parseArgs} the startup pass uses, now seeded
+ * with the registered flags — consumes every flag form (`--flag`, `--flag value`,
+ * `--flag=value`).
+ *
+ * {@link parseArgs} lets a registered flag shadow a same-named built-in, so even
+ * a built-in-colliding flag (e.g. plan-mode's boolean `--plan`, which would
+ * otherwise hit the built-in plan-model branch) is parsed with the extension's
+ * semantics and surfaces in `unknownFlags` — without consuming the following
+ * message or overwriting the built-in field. No built-in name list to maintain.
+ *
+ * Returns `null` when there is no sink or no registered extension flags, in
+ * which case the caller keeps its original startup parse (an extension-aware
+ * re-parse would be identical anyway).
+ */
+export function applyExtensionFlags(runner: ExtensionFlagSink | undefined, rawArgs: string[]): Args | null {
+	const extensionFlags = runner?.getFlags();
+	if (!runner || !extensionFlags || extensionFlags.size === 0) {
+		return null;
+	}
+	const parsed = parseArgs(rawArgs, extensionFlags);
+	// `parseArgs` only records registered extension flags in `unknownFlags`, so
+	// every entry here is a flag this runner owns that was actually passed.
+	for (const [name, value] of parsed.unknownFlags) {
+		runner.setFlagValue(name, value);
+	}
+	return parsed;
+}

package/src/cli/plugin-cli.ts

@@ -348,10 +348,12 @@ async function handleInstall(
 	flags: { json?: boolean; force?: boolean; dryRun?: boolean; scope?: "user" | "project" },
 ): Promise<void> {
 	if (packages.length === 0) {
-		console.error(chalk.red(`Usage: ${APP_NAME} plugin install <package[@version]>[features] ...`));
+		console.error(chalk.red(`Usage: ${APP_NAME} plugin install <source>[features] ...`));
 		console.error(chalk.dim("Examples:"));
 		console.error(chalk.dim(`  ${APP_NAME} plugin install @oh-my-pi/exa`));
 		console.error(chalk.dim(`  ${APP_NAME} plugin install name@marketplace`));
+		console.error(chalk.dim(`  ${APP_NAME} plugin install github:user/repo`));
+		console.error(chalk.dim(`  ${APP_NAME} plugin install https://github.com/user/repo#v1.0`));
 		process.exit(1);
 	}
 
@@ -898,7 +900,7 @@ export function printPluginHelp(): void {
 	console.log(`${chalk.bold(`${APP_NAME} plugin`)} - Plugin lifecycle management
 
 ${chalk.bold("Commands:")}
-  install <pkg[@ver]>[features]  Install plugins from npm
+  install <source>[features]     Install plugins from npm, GitHub, or git URL
   uninstall <pkg>                Remove plugins
   list                           Show installed plugins
   link <path>                    Link local plugin for development
@@ -916,6 +918,12 @@ ${chalk.bold("Feature Syntax:")}
   pkg[*]             Install with all features
   pkg[]              Install with no optional features
 
+${chalk.bold("Sources:")}
+  pkg, pkg@1.2.3                  npm package (optionally pinned)
+  github:user/repo[#ref]          GitHub shorthand (also gitlab:, bitbucket:, codeberg:, sourcehut:)
+  https://github.com/user/repo    Full git URL (https, ssh, or git protocol)
+  name@marketplace                Marketplace plugin (see marketplace command)
+
 ${chalk.bold("Config Subcommands:")}
   config list <pkg>              List all settings
   config get <pkg> <key>         Get a setting value
@@ -938,5 +946,6 @@ ${chalk.bold("Examples:")}
   ${APP_NAME} plugin config set my-plugin apiKey sk-xxx
   ${APP_NAME} plugin doctor --fix
   ${APP_NAME} plugin install --scope project name@marketplace
+  ${APP_NAME} plugin install github:user/repo#v1.0
 `);
 }

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);
 	}
 }