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

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";
@@ -987,8 +988,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 +1001,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 +1024,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 +1355,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 +1374,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 +1397,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 +1459,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 +1471,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 => {

package/src/config.ts

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { CONFIG_DIR_NAME, getConfigAgentDirName, getProjectDir } from "@oh-my-pi/pi-utils";
+import { resolveClaudePaths } from "./config/claude-paths";
 import { expandTilde } from "./tools/path-utils";
 
 export * from "./config/config-file";
@@ -76,12 +77,12 @@ export function getChangelogPath(): string | undefined {
 // =============================================================================
 
 /**
- * Config directory bases in priority order (highest first).
- * User-level: ~/.omp/agent, ~/.claude, ~/.codex, ~/.gemini
+ * User-level: ~/.omp/agent, Claude's active config directory, ~/.codex, ~/.gemini
  * Project-level: .omp, .claude, .codex, .gemini
  */
 const USER_CONFIG_BASES = priorityList.map(({ dir, globalAgentDir }) => ({
-	base: () => path.join(os.homedir(), globalAgentDir ? globalAgentDir() : dir),
+	base: () =>
+		dir === ".claude" ? resolveClaudePaths().configDir : path.join(os.homedir(), globalAgentDir?.() ?? dir),
 	name: dir,
 }));
 

package/src/discovery/agents.ts

@@ -67,18 +67,18 @@ const HOST_PROBE_TIMEOUT_MS = 500;
 
 /**
  * Run a best-effort discovery probe and return its trimmed stdout, or
- * `undefined` when the command fails, produces no output, or exceeds
- * {@link HOST_PROBE_TIMEOUT_MS}. On timeout the child is killed with SIGKILL so
- * a wedged interop pipe cannot hang startup; the killed/non-zero exit is then
- * reported as "unavailable" and discovery falls back to the Linux
- * `$HOME`/`~/.omp` candidates.
+ * `undefined` when the command fails, produces no output, or exceeds the
+ * timeout. On timeout the child is killed with SIGKILL so a wedged interop pipe
+ * cannot hang startup; the killed/non-zero exit is then reported as
+ * "unavailable" and discovery falls back to the Linux `$HOME`/`~/.omp`
+ * candidates.
  */
-export function runHostProbe(cmd: string[]): string | undefined {
+export function runHostProbe(cmd: string[], timeoutMs = HOST_PROBE_TIMEOUT_MS): string | undefined {
 	try {
 		const result = Bun.spawnSync(cmd, {
 			stdout: "pipe",
 			stderr: "ignore",
-			timeout: HOST_PROBE_TIMEOUT_MS,
+			timeout: timeoutMs,
 			killSignal: "SIGKILL",
 		});
 		if (result.exitCode !== 0) return undefined;

package/src/discovery/claude.ts

@@ -18,6 +18,7 @@ import { type SlashCommand, slashCommandCapability } from "../capability/slash-c
 import { type SystemPrompt, systemPromptCapability } from "../capability/system-prompt";
 import { type CustomTool, toolCapability } from "../capability/tool";
 import type { LoadContext, LoadResult } from "../capability/types";
+import { resolveClaudePaths } from "../config/claude-paths";
 import { settings } from "../config/settings";
 import {
 	calculateDepth,
@@ -34,11 +35,10 @@ const DISPLAY_NAME = "Claude Code";
 const PRIORITY = 80;
 const CONFIG_DIR = ".claude";
 
-/**
- * Get user-level .claude path.
- */
+/** Get the active user-level Claude Code directory. */
 function getUserClaude(ctx: LoadContext): string {
-	return path.join(ctx.home, CONFIG_DIR);
+	const { configDir } = resolveClaudePaths(ctx.home);
+	return configDir;
 }
 
 /**
@@ -60,8 +60,7 @@ async function loadMCPServers(ctx: LoadContext): Promise<LoadResult<MCPServer>>
 	const items: MCPServer[] = [];
 	const warnings: string[] = [];
 
-	const userBase = getUserClaude(ctx);
-	const userClaudeJson = path.join(ctx.home, ".claude.json");
+	const { configDir: userBase, configFile: userClaudeJson } = resolveClaudePaths(ctx.home);
 	const userMcpJson = path.join(userBase, "mcp.json");
 
 	const projectBase = path.join(ctx.cwd, CONFIG_DIR);

package/src/discovery/helpers.ts

@@ -16,6 +16,7 @@ import { invalidate as invalidateFsCache, readDirEntries, readFile } from "../ca
 import { parseRuleConditionAndScope, type Rule, type RuleFrontmatter } from "../capability/rule";
 import type { Skill, SkillFrontmatter } from "../capability/skill";
 import type { LoadContext, LoadResult, SourceMeta } from "../capability/types";
+import { resolveClaudePaths } from "../config/claude-paths";
 import type { MCPRequestIdFormat } from "../mcp/types";
 import { type ConfiguredThinkingLevel, parseConfiguredThinkingLevel } from "../thinking";
 import { normalizeToolNames } from "../tools/builtin-names";
@@ -90,10 +91,9 @@ export type SourceId = keyof typeof SOURCE_PATHS;
  */
 export function getUserPath(ctx: LoadContext, source: SourceId, subpath: string): string | null {
 	// Native user config is profile-scoped via getAgentDir() (the active profile's
-	// agent dir), matching builtin.ts and getMCPConfigPath("user"). External tools
-	// (~/.claude, ~/.gemini, …) are intentionally not profile-scoped, so they keep
-	// resolving against ctx.home below.
+	// agent dir), matching builtin.ts and getMCPConfigPath("user").
 	if (source === "native") return path.join(getAgentDir(), subpath);
+	if (source === "claude") return path.join(resolveClaudePaths(ctx.home).configDir, subpath);
 	const paths = SOURCE_PATHS[source];
 	if (!paths.userAgent) return null;
 	return path.join(ctx.home, paths.userAgent, subpath);
@@ -903,20 +903,21 @@ export function registerPluginCacheInvalidator(invalidator: () => void): void {
 }
 
 /**
- * List all installed Claude Code plugin roots from the plugin cache.
- * Reads ~/.claude/plugins/installed_plugins.json and ~/.omp/plugins/installed_plugins.json,
- * and optionally the nearest project-scoped registry resolved from `cwd`.
+ * List all installed Claude Code plugin roots from its active plugin cache and
+ * ~/.omp/plugins/installed_plugins.json, plus the nearest project registry when present.
  *
- * Results are cached per home, project registry, and canonical active project.
+ * Results are cached per Claude and OMP config directories, project registry, and canonical active project.
  */
 export async function listClaudePluginRoots(
 	home: string,
 	cwd?: string,
 ): Promise<{ roots: ClaudePluginRoot[]; warnings: string[] }> {
+	const claudeConfigDir = resolveClaudePaths(home).configDir;
+	const ompRegistryPath = path.join(getPluginsDir(home), "installed_plugins.json");
 	const resolvedProjectPath = cwd ? await resolveActiveProjectRegistryPath(cwd) : null;
 	const projectRoot = resolvedProjectPath ? path.dirname(path.dirname(path.dirname(resolvedProjectPath))) : cwd;
 	const activeClaudeProjectPath = projectRoot ? await canonicalClaudeProjectPath(projectRoot) : null;
-	const cacheKey = `${home}:${resolvedProjectPath ?? ""}:${activeClaudeProjectPath ?? ""}`;
+	const cacheKey = `${claudeConfigDir}:${ompRegistryPath}:${resolvedProjectPath ?? ""}:${activeClaudeProjectPath ?? ""}`;
 	const cached = pluginRootsCache.get(cacheKey);
 	if (cached) return cached;
 
@@ -926,7 +927,7 @@ export async function listClaudePluginRoots(
 	const canonicalClaudeProjectPaths = new Map<string, string | null>();
 
 	// ── Claude Code registry ──────────────────────────────────────────────────
-	const registryPath = path.join(home, ".claude", "plugins", "installed_plugins.json");
+	const registryPath = path.join(claudeConfigDir, "plugins", "installed_plugins.json");
 	const content = await readFile(registryPath);
 
 	if (content) {
@@ -983,7 +984,7 @@ export async function listClaudePluginRoots(
 	// In production `home` is `os.homedir()`, so `getPluginsDir(home)` resolves to the
 	// same XDG-aware path the marketplace writer uses (reads and writes always agree).
 	// Tests pass a temp dir, which short-circuits the resolver for deterministic isolation.
-	const ompRegistryPath = path.join(getPluginsDir(home), "installed_plugins.json");
+	// Computed before the cache lookup because isolated SDK homes select distinct OMP registries.
 	const ompContent = await readFile(ompRegistryPath);
 	if (ompContent) {
 		const ompRegistry = parseClaudePluginsRegistry(ompContent);
@@ -1107,7 +1108,7 @@ export function clearClaudePluginRootsCache(): void {
  * installing/uninstalling/enabling/disabling plugins.
  */
 export function clearPluginRootsAndCaches(extraPaths?: readonly string[]): void {
-	invalidateFsCache(path.join(os.homedir(), ".claude", "plugins", "installed_plugins.json"));
+	invalidateFsCache(path.join(resolveClaudePaths().configDir, "plugins", "installed_plugins.json"));
 	invalidateFsCache(path.join(getPluginsDir(), "installed_plugins.json"));
 	for (const p of extraPaths ?? []) invalidateFsCache(p);
 	clearClaudePluginRootsCache();

package/src/extensibility/extensions/runner.ts

@@ -42,6 +42,7 @@ import type {
 	ExtensionError,
 	ExtensionEvent,
 	ExtensionFlag,
+	ExtensionMode,
 	ExtensionRuntime,
 	ExtensionShortcut,
 	ExtensionUIContext,
@@ -342,6 +343,7 @@ interface ToolRegistrationScope {
 
 export class ExtensionRunner {
 	#uiContext: ExtensionUIContext;
+	#mode: ExtensionMode = "print";
 	#toolApprovalPreviewWaiter?: (toolCallId: string) => Promise<void>;
 	#errorListeners: Set<ExtensionErrorListener> = new Set();
 	#getModel: () => Model | undefined = () => undefined;
@@ -525,6 +527,7 @@ export class ExtensionRunner {
 		contextActions: ExtensionContextActions,
 		commandContextActions?: ExtensionCommandContextActions,
 		uiContext?: ExtensionUIContext,
+		mode: ExtensionMode = "print",
 	): void {
 		// Copy actions into the shared runtime (all extension APIs reference this)
 		this.runtime.sendMessage = actions.sendMessage;
@@ -573,6 +576,7 @@ export class ExtensionRunner {
 		}
 
 		this.#uiContext = uiContext ?? noOpUIContext;
+		this.#mode = mode;
 		this.#initialized = true;
 
 		// Drain events buffered by emitCredentialDisabled() before initialize ran. The
@@ -953,6 +957,7 @@ export class ExtensionRunner {
 		const getModel = model ? () => model : this.#getModel;
 		return {
 			ui: this.#uiContext,
+			mode: this.#mode,
 			getContextUsage: () => this.#getContextUsageFn(),
 			compact: instructionsOrOptions => this.#compactFn(instructionsOrOptions),
 			getAsyncJobSnapshot: () => this.#getAsyncJobSnapshotFn(),

package/src/extensibility/extensions/types.ts

@@ -434,9 +434,14 @@ export interface ExtensionModelQuery {
 	family(model: Model): string;
 }
 
+/** Runtime host mode exposed to Pi-compatible extensions. */
+export type ExtensionMode = "tui" | "rpc" | "json" | "print";
+
 export interface ExtensionContext {
 	/** UI methods for user interaction */
 	ui: ExtensionUIContext;
+	/** Current run mode. Use `"tui"` to guard terminal-only UI such as custom components. */
+	mode: ExtensionMode;
 	/** Get current context usage for the active model. */
 	getContextUsage(): ContextUsage | undefined;
 	/** Get a read-only snapshot of async jobs owned by this session. */