@oh-my-pi/pi-coding-agent 17.3.0 → 17.3.2

package/src/cli/flag-tables.ts

@@ -47,7 +47,6 @@ import { CliUsageError } from "./usage-error";
 export interface ParseDeps {
 	logger: { warn: (message: string, meta?: Record<string, unknown>) => void };
 	parseThinking: (value: string | null | undefined) => ConfiguredThinkingLevel | undefined;
-	builtinToolNames: readonly string[];
 	normalizeToolNames: (values: Iterable<string>) => string[];
 	thinkingEfforts: readonly string[];
 }
@@ -189,15 +188,8 @@ export const STRING_SETTERS: Record<string, StringSetter> = {
 				.map(s => s.trim())
 				.filter(Boolean),
 		);
-		// An unknown name silently narrowing the toolset is worse than a failed
-		// launch: scripts keep running believing the tool is available (e.g. a
-		// stale `--tools bash,ssh` after the ssh tool's removal).
-		const unknown = names.filter(name => !deps.builtinToolNames.includes(name));
-		if (unknown.length > 0) {
-			throw new CliUsageError(
-				`Unknown tool${unknown.length === 1 ? "" : "s"} in --tools: ${unknown.join(", ")}. Valid tools: ${deps.builtinToolNames.join(", ")}.`,
-			);
-		}
+		// Validation runs after session tool discovery. At this point extension,
+		// custom, plugin-manifest, and MCP tools are not all known yet.
 		result.tools = names;
 	},
 	"--thinking": (result, value, deps) => {

package/src/cli/gc-cli.ts

@@ -151,11 +151,21 @@ function numberSetting(value: number | undefined, fallback: unknown, defaultValu
 async function resolveOptions(flags: GcCommandFlags): Promise<ResolvedGcOptions> {
 	const agentDir = path.resolve(flags.agentDir ?? getAgentDir());
 	const selected = flags.blobs === true || flags.archive === true || flags.wal === true;
+	const archiveSelected = selected && flags.archive === true;
+	const needsArchiveSettings =
+		archiveSelected &&
+		(flags.coldArchiveAfterDays === undefined ||
+			flags.retainNewestGlobal === undefined ||
+			flags.retainNewestPerCwd === undefined);
 	const settings =
-		flags.apply === true ? await Settings.loadIsolated({ agentDir }) : await Settings.loadReadOnly({ agentDir });
-	const getBoolean = (pathKey: "gc.blobs" | "gc.archive" | "gc.wal") => settings.get(pathKey);
+		!selected || needsArchiveSettings
+			? flags.apply === true
+				? await Settings.loadIsolated({ agentDir })
+				: await Settings.loadReadOnly({ agentDir })
+			: undefined;
+	const getBoolean = (pathKey: "gc.blobs" | "gc.archive" | "gc.wal") => settings?.get(pathKey) ?? getDefault(pathKey);
 	const getNumber = (pathKey: "gc.coldArchiveAfterDays" | "gc.retainNewestGlobal" | "gc.retainNewestPerCwd") =>
-		settings.get(pathKey);
+		settings?.get(pathKey) ?? getDefault(pathKey);
 	return {
 		apply: flags.apply === true,
 		json: flags.json === true,

package/src/cli/setup-cli.ts

@@ -66,7 +66,7 @@ export function parseSetupArgs(args: string[]): SetupCommandArgs | undefined {
 	};
 }
 
-interface PythonCheckResult {
+export interface PythonCheckResult {
 	available: boolean;
 	pythonPath?: string;
 	usingManagedEnv?: boolean;
@@ -82,7 +82,7 @@ function managedPythonPath(): string {
 /**
  * Check Python environment and kernel dependencies.
  */
-async function checkPythonSetup(cwd: string, interpreter?: string): Promise<PythonCheckResult> {
+export async function checkPythonSetup(cwd: string, interpreter?: string): Promise<PythonCheckResult> {
 	const availability = await checkPythonKernelAvailability(cwd, interpreter, { forceProbe: true });
 	return {
 		available: availability.ok,

package/src/cli/update-cli.ts

@@ -12,6 +12,7 @@ import { Transform } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { $env, $which, APP_NAME, compareVersions, isEnoent, VERSION } from "@oh-my-pi/pi-utils";
 import chalk from "@oh-my-pi/pi-utils/chalk";
+import { withFileLock } from "@oh-my-pi/pi-utils/file-lock";
 import { $ } from "bun";
 import { theme } from "../modes/theme/theme";
 import { isTimeoutError, withTimeoutSignal } from "../utils/fetch-timeout";
@@ -466,6 +467,27 @@ function isPathInDirectory(filePath: string, directoryPath: string): boolean {
 	return isPathInDirectoryLexical(resolvedFile, dirReal);
 }
 
+function isPathInManagerRoot(linkTarget: string, nodeModulesDir: string): boolean {
+	if (isPathInDirectoryLexical(linkTarget, nodeModulesDir)) return true;
+	// Resolve only the manager root. Resolving the link target itself would
+	// follow globally linked packages into their checkout and lose ownership.
+	const nodeModulesReal = tryRealpath(path.resolve(nodeModulesDir));
+	return nodeModulesReal !== undefined && isPathInDirectoryLexical(linkTarget, nodeModulesReal);
+}
+
+function resolveNpmGlobalNodeModulesDir(globalBinDir: string | undefined): string | undefined {
+	if (!globalBinDir) return undefined;
+	if (process.platform === "win32") return path.join(globalBinDir, "node_modules");
+	return path.join(path.dirname(globalBinDir), "lib", "node_modules");
+}
+
+function isManagerOwnedBinEntry(linkTarget: string | undefined, nodeModulesDir: string | undefined): boolean {
+	// Non-symlink launchers and unreadable links retain the existing bin-dir
+	// classification. A readable link must point through the manager's exact
+	// global node_modules tree.
+	return linkTarget === undefined || (nodeModulesDir !== undefined && isPathInManagerRoot(linkTarget, nodeModulesDir));
+}
+
 type UpdateMethod = "brew" | "mise" | "nix" | "bun" | "npm" | "binary";
 
 interface UpdateMethodResolutionOptions {
@@ -473,6 +495,8 @@ interface UpdateMethodResolutionOptions {
 	miseBinDirs?: readonly string[];
 	miseDataDir?: string;
 	npmBinDir?: string;
+	/** Bun's configured global package directory, independent of its bin directory. */
+	bunGlobalDir?: string;
 	/**
 	 * Whether the resolved omp path is a plain file (the standalone binary)
 	 * rather than a package-manager symlink. Stops a binary install from being
@@ -480,6 +504,11 @@ interface UpdateMethodResolutionOptions {
 	 * target directory.
 	 */
 	ompIsRegularFile?: boolean;
+	/**
+	 * Absolute path named by the bin entry's first symlink hop. This deliberately
+	 * preserves a global package symlink instead of resolving into its checkout.
+	 */
+	ompLinkTarget?: string;
 }
 
 type UpdateTarget =
@@ -495,7 +524,15 @@ function resolveUpdateMethod(
 	bunBinDir: string | undefined,
 	options: UpdateMethodResolutionOptions = {},
 ): UpdateMethod {
-	const { homebrewPrefix, miseBinDirs = [], miseDataDir, npmBinDir, ompIsRegularFile = false } = options;
+	const {
+		bunGlobalDir,
+		homebrewPrefix,
+		miseBinDirs = [],
+		miseDataDir,
+		npmBinDir,
+		ompIsRegularFile = false,
+		ompLinkTarget,
+	} = options;
 	const launcherExtension = path.extname(ompPath).toLowerCase();
 	const isWindowsScriptLauncher =
 		launcherExtension === ".cmd" || launcherExtension === ".ps1" || launcherExtension === ".bat";
@@ -513,9 +550,28 @@ function resolveUpdateMethod(
 	// (bun's .exe launcher, npm's .cmd/.ps1), so a regular file is NOT evidence
 	// of a standalone install and the override would hijack managed installs.
 	const isStandaloneRegularFile = ompIsRegularFile && process.platform !== "win32";
-	if (bunBinDir && isPathInDirectory(ompPath, bunBinDir) && !isStandaloneRegularFile) return "bun";
-	if ((npmBinDir && isPathInDirectory(ompPath, npmBinDir) && !isStandaloneRegularFile) || isWindowsScriptLauncher)
+	const bunNodeModulesDir = resolveBunGlobalNodeModulesDirFromLocations({
+		globalDir: bunGlobalDir,
+		globalBinDir: bunBinDir,
+	});
+	if (
+		bunBinDir &&
+		isPathInDirectory(ompPath, bunBinDir) &&
+		!isStandaloneRegularFile &&
+		isManagerOwnedBinEntry(ompLinkTarget, bunNodeModulesDir)
+	) {
+		return "bun";
+	}
+	const npmNodeModulesDir = resolveNpmGlobalNodeModulesDir(npmBinDir);
+	if (
+		npmBinDir &&
+		isPathInDirectory(ompPath, npmBinDir) &&
+		!isStandaloneRegularFile &&
+		isManagerOwnedBinEntry(ompLinkTarget, npmNodeModulesDir)
+	) {
 		return "npm";
+	}
+	if (isWindowsScriptLauncher) return "npm";
 	return "binary";
 }
 
@@ -526,6 +582,44 @@ export function resolveUpdateMethodForTest(
 ): UpdateMethod {
 	return resolveUpdateMethod(ompPath, bunBinDir, options);
 }
+
+/** Resolve an update target from the concrete PATH entry selected by the shell. */
+export function resolveUpdateTargetFromPath(
+	ompPath: string,
+	bunBinDir: string | undefined,
+	options: UpdateMethodResolutionOptions & { allowPackageManagers: boolean },
+): UpdateTarget {
+	let ompIsRegularFile = false;
+	let ompIsSymlink = false;
+	let ompLinkTarget: string | undefined;
+	let ompRealpath: string | undefined;
+	try {
+		const stat = fs.lstatSync(ompPath);
+		ompIsRegularFile = stat.isFile() && !stat.isSymbolicLink();
+		ompIsSymlink = stat.isSymbolicLink();
+		if (ompIsSymlink) {
+			const rawTarget = fs.readlinkSync(ompPath);
+			const linkDir = path.dirname(ompPath);
+			ompLinkTarget = path.resolve(tryRealpath(linkDir) ?? linkDir, rawTarget);
+			ompRealpath = tryRealpath(ompPath);
+		}
+	} catch {}
+
+	const method = resolveUpdateMethod(ompPath, bunBinDir, {
+		...options,
+		ompIsRegularFile,
+		ompLinkTarget,
+	});
+	if (method === "binary") {
+		// A package-manager-enabled update follows a foreign alias to replace
+		// its standalone binary. Binary-only releases intentionally replace the
+		// selected manager launcher in place.
+		const binaryPath = options.allowPackageManagers && ompIsSymlink ? (ompRealpath ?? ompPath) : ompPath;
+		return { method, path: binaryPath, replacesSymlink: ompIsSymlink && binaryPath === ompPath };
+	}
+	if (method === "bun" || method === "npm") return { method, path: ompPath };
+	return { method };
+}
 /**
  * Resolve how the running install should be updated.
  *
@@ -545,27 +639,14 @@ async function resolveUpdateTarget(options: { allowPackageManagers: boolean }):
 	const ompPath = resolveOmpPath();
 
 	if (ompPath) {
-		// Package-manager installs symlink the bin entry into node_modules; the
-		// standalone installer writes a plain executable. When the global bin dir
-		// overlaps the installer's default (~/.local/bin), that file type — not
-		// directory containment — distinguishes a binary install from npm/bun.
-		let ompIsRegularFile = false;
-		let ompIsSymlink = false;
-		try {
-			const stat = fs.lstatSync(ompPath);
-			ompIsRegularFile = stat.isFile() && !stat.isSymbolicLink();
-			ompIsSymlink = stat.isSymbolicLink();
-		} catch {}
-		const method = resolveUpdateMethod(ompPath, bunBinDir, {
+		return resolveUpdateTargetFromPath(ompPath, bunBinDir, {
+			allowPackageManagers: options.allowPackageManagers,
+			bunGlobalDir: options.allowPackageManagers ? process.env.BUN_INSTALL_GLOBAL_DIR : undefined,
 			homebrewPrefix,
 			miseBinDirs,
 			miseDataDir,
 			npmBinDir,
-			ompIsRegularFile,
 		});
-		if (method === "binary") return { method, path: ompPath, replacesSymlink: ompIsSymlink };
-		if (method === "bun" || method === "npm") return { method, path: ompPath };
-		return { method };
 	}
 
 	if (bunBinDir) return { method: "bun" };
@@ -794,10 +875,19 @@ async function resolveBunInstallCacheDir(): Promise<string | undefined> {
 	}
 }
 
-export function resolveBunGlobalNodeModulesDirFromLocations(
-	globalBinDir: string | undefined,
-	cacheDir: string | undefined,
-): string | undefined {
+interface BunGlobalInstallLocations {
+	globalDir?: string;
+	globalBinDir?: string;
+	cacheDir?: string;
+}
+
+/** Resolve Bun's global node_modules root from explicit, default, or cache locations. */
+export function resolveBunGlobalNodeModulesDirFromLocations({
+	globalDir,
+	globalBinDir,
+	cacheDir,
+}: BunGlobalInstallLocations): string | undefined {
+	if (globalDir && globalDir.length > 0) return path.join(globalDir, "node_modules");
 	if (globalBinDir && globalBinDir.length > 0) {
 		return path.join(path.dirname(globalBinDir), "install", "global", "node_modules");
 	}
@@ -811,9 +901,16 @@ async function resolveBunGlobalNodeModulesDir(cacheDir: string): Promise<string
 	try {
 		const result = await $`bun pm bin -g`.quiet().nothrow();
 		const globalBinDir = result.exitCode === 0 ? result.text().trim() : undefined;
-		return resolveBunGlobalNodeModulesDirFromLocations(globalBinDir, cacheDir);
+		return resolveBunGlobalNodeModulesDirFromLocations({
+			globalDir: process.env.BUN_INSTALL_GLOBAL_DIR,
+			globalBinDir,
+			cacheDir,
+		});
 	} catch {
-		return resolveBunGlobalNodeModulesDirFromLocations(undefined, cacheDir);
+		return resolveBunGlobalNodeModulesDirFromLocations({
+			globalDir: process.env.BUN_INSTALL_GLOBAL_DIR,
+			cacheDir,
+		});
 	}
 }
 
@@ -987,8 +1084,8 @@ async function unlinkIfExists(filePath: string): Promise<void> {
  * running process image, so unlinking it fails with EPERM/EACCES until this
  * process exits (issue #845). The replacement and verification already
  * succeeded by the time we get here, so every error is swallowed; the leftover
- * is reclaimed by {@link sweepStaleBackups} on the next update once it is no
- * longer in use. Returns whether the file is gone.
+ * is reclaimed by {@link sweepStaleUpdateArtifacts} on the next update once it
+ * is no longer in use. Returns whether the file is gone.
  */
 async function removeBackupBestEffort(filePath: string): Promise<boolean> {
 	try {
@@ -1000,16 +1097,21 @@ async function removeBackupBestEffort(filePath: string): Promise<boolean> {
 }
 
 /**
- * Best-effort removal of binary-update backups left by earlier runs.
+ * Best-effort removal of binary-update leftovers from earlier runs.
  *
- * Each self-update moves the previous executable to `<binary>.<timestamp>.<pid>.bak`
- * before swapping the new one in. On Windows that backup cannot be deleted
- * while the updating process is alive, so it is left for a later run to reclaim
- * once its owning process has exited. Also matches the legacy fixed
- * `<binary>.bak` name produced before backups were timestamped, so users
- * upgrading from a buggy release get the orphaned file cleaned up.
+ * Each self-update writes to `<binary>.<timestamp>.<pid>.new` and moves the
+ * previous executable to `<binary>.<timestamp>.<pid>.bak` before swapping the
+ * new one in. On Windows a backup cannot be deleted while the updating process
+ * is alive (it is the running process image), so it is left for a later run to
+ * reclaim once its owning process has exited. A `.new` temp file only survives
+ * a hard kill mid-download; it is reaped once older than the download window,
+ * which a live download cannot exceed without timing out and cleaning up after
+ * itself — so a concurrent run's in-progress temp is never deleted. Legacy
+ * fixed `<binary>.bak` / `<binary>.new` names (from before suffixes were made
+ * unique) are matched too, so users upgrading from a buggy release get the
+ * orphaned files cleaned up.
  */
-export async function sweepStaleBackups(targetPath: string): Promise<void> {
+export async function sweepStaleUpdateArtifacts(targetPath: string): Promise<void> {
 	const dir = path.dirname(targetPath);
 	const base = path.basename(targetPath);
 	let entries: string[];
@@ -1018,13 +1120,28 @@ export async function sweepStaleBackups(targetPath: string): Promise<void> {
 	} catch {
 		return;
 	}
+	const now = Date.now();
 	for (const entry of entries) {
-		if (!entry.startsWith(`${base}.`) || !entry.endsWith(".bak")) continue;
-		// Legacy "<base>.bak" → empty middle; new "<base>.<timestamp>.<pid>.bak"
-		// → dot-separated numeric run. Anything else is an unrelated *.bak file.
-		const middle = entry.slice(base.length + 1, entry.length - ".bak".length);
+		if (!entry.startsWith(`${base}.`)) continue;
+		const suffix = entry.endsWith(".bak") ? ".bak" : entry.endsWith(".new") ? ".new" : undefined;
+		if (!suffix) continue;
+		// Legacy "<base><suffix>" → empty middle; new "<base>.<timestamp>.<pid><suffix>"
+		// → dot-separated numeric run. Anything else is an unrelated file.
+		const middle = entry.slice(base.length + 1, entry.length - suffix.length);
 		if (middle.length > 0 && !/^\d+(\.\d+)*$/.test(middle)) continue;
-		await removeBackupBestEffort(path.join(dir, entry));
+		const full = path.join(dir, entry);
+		if (suffix === ".new") {
+			// A temp file may belong to a concurrent update still downloading, so
+			// only reap ones older than the download window.
+			let mtimeMs: number;
+			try {
+				mtimeMs = (await fs.promises.stat(full)).mtimeMs;
+			} catch {
+				continue;
+			}
+			if (now - mtimeMs < BINARY_DOWNLOAD_TIMEOUT_MS) continue;
+		}
+		await removeBackupBestEffort(full);
 	}
 }
 
@@ -1334,6 +1451,11 @@ async function updateViaMise(expectedVersion: string, force: boolean): Promise<v
 	await printVerification(expectedVersion);
 }
 
+// Monotonic within this process so two updates started in the same millisecond
+// (same pid, same `Date.now()`) still get distinct temp/backup paths. Kept
+// numeric so the artifact sweep's `\d+(\.\d+)*` matcher still reclaims them.
+let updateAttemptSeq = 0;
+
 /**
  * Download a release binary to a target path, replacing an existing file.
  */
@@ -1348,12 +1470,18 @@ export async function updateViaBinaryAt(
 	} = {},
 ): Promise<void> {
 	const binaryName = options.binaryName ?? getBinaryName();
-	const tempPath = `${targetPath}.new`;
-	// Unique per attempt: a stale backup from an earlier update may still be
-	// locked (it is the previous process image on Windows), and a fixed name
-	// would force the move-aside rename to overwrite it. pid + timestamp keeps
-	// two forced updates in the same millisecond from colliding.
-	const backupPath = `${targetPath}.${Date.now()}.${process.pid}.bak`;
+	// Unique per attempt so two overlapping `omp update` runs never share a temp
+	// or backup path. A fixed temp name (`<binary>.new`) let the second run's
+	// pre-download unlink delete the first run's still-downloading temp file; the
+	// first kept writing to its open fd (size + digest still passed), then chmod
+	// hit the missing path and the update aborted (issue #8434). The backup needs
+	// the same uniqueness: a stale backup from an earlier update may still be
+	// locked (the previous process image on Windows), so a fixed name would force
+	// the move-aside rename to overwrite it. pid, timestamp, and a process-local
+	// counter keep two updates started in the same millisecond from colliding.
+	const attempt = `${Date.now()}.${process.pid}.${updateAttemptSeq++}`;
+	const tempPath = `${targetPath}.${attempt}.new`;
+	const backupPath = `${targetPath}.${attempt}.bak`;
 	const asset = await getReleaseBinaryAsset(expectedVersion, binaryName, options.fetchImpl, options.githubToken);
 	console.log(chalk.dim(`Downloading ${binaryName}…`));
 	await downloadVerifiedBinary({
@@ -1365,16 +1493,22 @@ export async function updateViaBinaryAt(
 	});
 	console.log(chalk.dim(`Verified ${asset.digest}`));
 
-	console.log(chalk.dim("Installing update..."));
-	await replaceBinaryForUpdate({
-		targetPath,
-		tempPath,
-		backupPath,
-		expectedVersion,
-		verifyInstalledVersion: options.verifyInstalledVersion ?? verifyInstalledVersion,
+	// Serialize the target swap and stale-artifact sweep per target so two
+	// overlapping `omp update` runs never replace the same binary concurrently
+	// or reclaim each other's live backup/temp files. The download above writes
+	// to a unique temp path and is safe to overlap; only the swap is shared.
+	await withFileLock(targetPath, async () => {
+		console.log(chalk.dim("Installing update..."));
+		await replaceBinaryForUpdate({
+			targetPath,
+			tempPath,
+			backupPath,
+			expectedVersion,
+			verifyInstalledVersion: options.verifyInstalledVersion ?? verifyInstalledVersion,
+		});
+		// Reclaim backups from earlier updates whose owning process has since exited.
+		await sweepStaleUpdateArtifacts(targetPath);
 	});
-	// Reclaim backups from earlier updates whose owning process has since exited.
-	await sweepStaleBackups(targetPath);
 	printVerifiedVersion(expectedVersion);
 	console.log(chalk.dim(`Restart ${APP_NAME} to use the new version`));
 }
@@ -1421,7 +1555,8 @@ export async function updateViaShimTakeover(
 	const binaryName = options.binaryName ?? getBinaryName();
 	const launcherDir = path.dirname(shimPath);
 	const exePath = path.join(launcherDir, `${APP_NAME}.exe`);
-	const tempPath = `${exePath}.new`;
+	const attempt = `${Date.now()}.${process.pid}.${updateAttemptSeq++}`;
+	const tempPath = `${exePath}.${attempt}.new`;
 	const asset = await getReleaseBinaryAsset(expectedVersion, binaryName, options.fetchImpl, options.githubToken);
 	console.log(chalk.dim(`Downloading ${binaryName}…`));
 	await downloadVerifiedBinary({
@@ -1432,65 +1567,69 @@ export async function updateViaShimTakeover(
 		fetchImpl: options.fetchImpl,
 	});
 	console.log(chalk.dim(`Verified ${asset.digest}`));
-
-	console.log(chalk.dim(`Installing ${APP_NAME}.exe beside the script launcher...`));
-	await fs.promises.rename(tempPath, exePath);
-	// Retire the shims so PATH resolution lands on the new exe. Renamed, not
-	// deleted: restorable on verification failure, and Windows permits
-	// renaming a batch file that is still executing. A shim that cannot be
-	// renamed (held open without delete sharing) is rewritten in place as a
-	// forwarder to the exe — write and rename take different Windows locks,
-	// so one can succeed where the other fails.
-	const backupSuffix = `${Date.now()}.${process.pid}.bak`;
-	const retired: Array<{ launcher: string; backup: string }> = [];
 	const forwarded: Array<{ launcher: string; original: string }> = [];
 	const stuck: string[] = [];
-	for (const ext of ["", ".cmd", ".ps1", ".bat"]) {
-		const launcher = path.join(launcherDir, `${APP_NAME}${ext}`);
-		const backup = `${launcher}.${backupSuffix}`;
-		try {
-			await fs.promises.rename(launcher, backup);
-			retired.push({ launcher, backup });
-		} catch (err) {
-			if (isEnoent(err)) continue;
+	// Serialize the launcher swap and artifact sweep so two overlapping updates
+	// never retire the same shims or reclaim a live run's backup before its
+	// verification can roll it back.
+	await withFileLock(exePath, async () => {
+		console.log(chalk.dim(`Installing ${APP_NAME}.exe beside the script launcher...`));
+		await fs.promises.rename(tempPath, exePath);
+		// Retire the shims so PATH resolution lands on the new exe. Renamed, not
+		// deleted: restorable on verification failure, and Windows permits
+		// renaming a batch file that is still executing. A shim that cannot be
+		// renamed (held open without delete sharing) is rewritten in place as a
+		// forwarder to the exe — write and rename take different Windows locks,
+		// so one can succeed where the other fails.
+		const backupSuffix = `${attempt}.bak`;
+		const retired: Array<{ launcher: string; backup: string }> = [];
+		for (const ext of ["", ".cmd", ".ps1", ".bat"]) {
+			const launcher = path.join(launcherDir, `${APP_NAME}${ext}`);
+			const backup = `${launcher}.${backupSuffix}`;
 			try {
-				const original = await Bun.file(launcher).text();
-				await Bun.write(launcher, SHIM_FORWARDERS[ext]);
-				forwarded.push({ launcher, original });
-			} catch {
-				stuck.push(launcher);
+				await fs.promises.rename(launcher, backup);
+				retired.push({ launcher, backup });
+			} catch (err) {
+				if (isEnoent(err)) continue;
+				try {
+					const original = await Bun.file(launcher).text();
+					await Bun.write(launcher, SHIM_FORWARDERS[ext]);
+					forwarded.push({ launcher, original });
+				} catch {
+					stuck.push(launcher);
+				}
 			}
 		}
-	}
 
-	// Verify the exe by its explicit path: $which cached the shim path when
-	// the update target was resolved, and the shim was just renamed away, so
-	// a PATH re-resolution here would test a file that no longer exists.
-	const verify = options.verifyBinary ?? verifyBinaryAtPath;
-	const verification = await verify(exePath, expectedVersion);
-	if (!verification.ok) {
-		for (const { launcher, backup } of retired) {
-			try {
-				await fs.promises.rename(backup, launcher);
-			} catch {}
+		// Verify the exe by its explicit path: $which cached the shim path when
+		// the update target was resolved, and the shim was just renamed away, so
+		// a PATH re-resolution here would test a file that no longer exists.
+		const verify = options.verifyBinary ?? verifyBinaryAtPath;
+		const verification = await verify(exePath, expectedVersion);
+		if (!verification.ok) {
+			for (const { launcher, backup } of retired) {
+				try {
+					await fs.promises.rename(backup, launcher);
+				} catch {}
+			}
+			for (const { launcher, original } of forwarded) {
+				try {
+					await Bun.write(launcher, original);
+				} catch {}
+			}
+			await unlinkIfExists(exePath);
+			throw new Error(
+				`${formatVerificationFailure(verification, expectedVersion)}; restored previous ${APP_NAME} launcher`,
+			);
 		}
-		for (const { launcher, original } of forwarded) {
-			try {
-				await Bun.write(launcher, original);
-			} catch {}
+		for (const { backup } of retired) {
+			await removeBackupBestEffort(backup);
 		}
-		await unlinkIfExists(exePath);
-		throw new Error(
-			`${formatVerificationFailure(verification, expectedVersion)}; restored previous ${APP_NAME} launcher`,
-		);
-	}
-	for (const { backup } of retired) {
-		await removeBackupBestEffort(backup);
-	}
-	// Reclaim exe backups and retired-shim leftovers from earlier attempts.
-	for (const ext of [".exe", "", ".cmd", ".ps1", ".bat"]) {
-		await sweepStaleBackups(path.join(launcherDir, `${APP_NAME}${ext}`));
-	}
+		// Reclaim exe backups and retired-shim leftovers from earlier attempts.
+		for (const ext of [".exe", "", ".cmd", ".ps1", ".bat"]) {
+			await sweepStaleUpdateArtifacts(path.join(launcherDir, `${APP_NAME}${ext}`));
+		}
+	});
 	for (const { launcher } of forwarded) {
 		console.log(chalk.dim(`Converted ${launcher} to a forwarder (it could not be removed).`));
 	}

package/src/commands/completions.ts

@@ -15,6 +15,21 @@ import { commands } from "../cli-commands";
 const ROOT_COMMAND = "launch";
 const SHELLS = ["bash", "zsh", "fish"] as const;
 
+/** Generate a completion script from the live command registry. */
+export async function generateLiveCompletion(shell: Shell): Promise<string> {
+	const loaded = await Promise.all(commands.map(async entry => ({ entry, Cmd: await entry.load() })));
+	const map = new Map<string, CommandCtor>();
+	const aliasMap = new Map<string, readonly string[]>();
+	for (const { entry, Cmd } of loaded) {
+		map.set(entry.name, Cmd);
+		const merged = new Set<string>([...(Cmd.aliases ?? []), ...(entry.aliases ?? [])]);
+		aliasMap.set(entry.name, [...merged]);
+	}
+
+	const config: CliConfig = { bin: APP_NAME, version: VERSION, commands: map };
+	return generateCompletion(shell, buildSpec(config, ROOT_COMMAND, aliasMap));
+}
+
 export default class Completions extends Command {
 	static description = commandHelp.description;
 	static args = {
@@ -39,20 +54,7 @@ export default class Completions extends Command {
 			return;
 		}
 
-		// Load every command class so we can read its static flag/arg descriptors,
-		// and collect aliases from both the registration table and the class.
-		const loaded = await Promise.all(commands.map(async entry => ({ entry, Cmd: await entry.load() })));
-		const map = new Map<string, CommandCtor>();
-		const aliasMap = new Map<string, readonly string[]>();
-		for (const { entry, Cmd } of loaded) {
-			map.set(entry.name, Cmd);
-			const merged = new Set<string>([...(Cmd.aliases ?? []), ...(entry.aliases ?? [])]);
-			aliasMap.set(entry.name, [...merged]);
-		}
-
-		const config: CliConfig = { bin: APP_NAME, version: VERSION, commands: map };
-		const spec = buildSpec(config, ROOT_COMMAND, aliasMap);
-		await Bun.write(Bun.stdout, generateCompletion(shell, spec));
+		await Bun.write(Bun.stdout, await generateLiveCompletion(shell));
 	}
 }
 

package/src/config/claude-paths.ts

@@ -0,0 +1,18 @@
+import * as os from "node:os";
+import * as path from "node:path";
+
+/** Paths to Claude Code's user data and configuration file. */
+export interface ClaudePaths {
+	configDir: string;
+	configFile: string;
+}
+
+/** Resolves Claude Code's user paths, honoring `CLAUDE_CONFIG_DIR`. */
+export function resolveClaudePaths(home: string = os.homedir()): ClaudePaths {
+	const override = process.env.CLAUDE_CONFIG_DIR?.trim();
+	if (override) {
+		const configDir = path.resolve(override);
+		return { configDir, configFile: path.join(configDir, ".claude.json") };
+	}
+	return { configDir: path.join(home, ".claude"), configFile: path.join(home, ".claude.json") };
+}

package/src/config/model-registry.ts

@@ -32,7 +32,7 @@ import {
 	resolveOllamaModelCacheProviderId,
 } from "@oh-my-pi/pi-catalog/provider-models";
 import { collapseBuiltModelVariants } from "@oh-my-pi/pi-catalog/variant-collapse";
-import { isBunTestRuntime, logger, wrapFetchForExtraCa } from "@oh-my-pi/pi-utils";
+import { getAgentDir, isBunTestRuntime, logger, wrapFetchForExtraCa } from "@oh-my-pi/pi-utils";
 import { resolveProviderModelReference } from "../config/model-resolver";
 import { generateCodexAttestation } from "../live/attestation";
 import type { AuthStorage } from "../session/auth-storage";
@@ -246,7 +246,7 @@ export class ModelRegistry {
 			(isBunTestRuntime()
 				? () => Promise.reject(new Error("network disabled in model-registry runtime test"))
 				: wrapFetchForExtraCa(fetch));
-		this.#modelsConfigFile = ModelsConfigFile.relocate(modelsPath);
+		this.#modelsConfigFile = ModelsConfigFile.relocate(modelsPath ?? path.join(getAgentDir(), "models.yml"));
 		this.#cacheDbPath = modelsPath ? path.join(path.dirname(modelsPath), "models.db") : undefined;
 		// Set up fallback resolver for custom provider API keys
 		this.authStorage.setFallbackResolver(provider => {