rea-agents 6.3.0 → 6.4.0

package/dist/application/SetupPlan.js

@@ -1,7 +1,6 @@
 import { join } from "node:path";
 import { isOwnedClientRegistrationCommand } from "./ClientRegistrationIdentity.js";
 import { linuxHopperInstallDisclosure, } from "./LinuxHopper.js";
-import { skillDestinations } from "./SetupSkill.js";
 import { macHopperInstallDisclosure } from "./MacHopper.js";
 /** Discover supported clients and current registrations without mutation. */
 export const discoverSetupState = async (input) => {
@@ -118,7 +117,7 @@ export const planSetupActions = async (input) => {
             installHopper: input.discovery.installHopper,
             installSkill: input.installSkill,
             skillClientIds: input.skillClientIds,
-            claudeCodeSkillsDirectory: input.host.claudeCodeSkillsDirectory,
+            skillDestinations: input.host.skillDestinations(input.skillClientIds),
             clients: clientPlans,
             providerEnvironment: input.providerEnvironment,
             ...(input.discovery.linuxPackageFamily === undefined
@@ -170,10 +169,8 @@ const setupPlan = (input) => [
         ...(backupPath === undefined ? {} : { backupPath }),
     })),
     ...(input.installSkill
-        ? skillDestinations(input.homeDirectory, input.skillClientIds, input.claudeCodeSkillsDirectory).map(({ client, path }) => ({
-            id: client === "claude_code"
-                ? "install_skill:claude_code"
-                : "install_skill",
+        ? input.skillDestinations.map(({ client, path }) => ({
+            id: client === "shared" ? "install_skill" : `install_skill:${client}`,
             kind: "install_skill",
             label: client === "claude_code"
                 ? "REA skill for Claude Code"
@@ -201,8 +198,8 @@ const clientConfigurationDetail = (client, command, environment, installHopper)
         .sort(([left], [right]) => left.localeCompare(right))
         .map(([name, value]) => `${name}=${value}`);
     const environmentDetail = entries.length === 0
-        ? " No additional environment variables."
-        : ` Environment: ${entries.join(", ")}.`;
+        ? " No additional provider environment variables. Existing server environment overrides are retained."
+        : ` Detected provider environment: ${entries.join(", ")}. Existing server environment overrides are retained; detected values replace matching keys.`;
     const hopperDetail = installHopper
         ? environment.HOPPER_LAUNCHER_PATH === undefined
             ? " If this plan installs Hopper, REA will add HOPPER_LAUNCHER_PATH using the launcher path reported by that installation."

package/dist/application/SetupSkill.js

@@ -1,45 +1,54 @@
-import { mkdir, readFile, rm } from "node:fs/promises";
+import { copyFile, lstat, mkdir, readFile, rm } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
 import { dirname, join } from "node:path";
 import writeFileAtomic from "write-file-atomic";
 import { PRODUCT_IDENTITY } from "../identity.js";
-const SKILL_FILES = [
+import { NonRegularFileReadError } from "../filesystem/RegularFile.js";
+import { readRegularFileText } from "./RegularFileRead.js";
+import { clientSkillDirectories } from "./SupportedClients.js";
+export const MANAGED_SKILL_FILES = [
     "SKILL.md",
+    "references/connection-and-recovery.md",
     "references/native-and-artifacts.md",
     "references/javascript-applications.md",
     "references/android-applications.md",
     "references/runtime-observation.md",
     "references/evidence-workflows.md",
 ];
-/** Resolve Claude Code personal skills from the selected environment. */
-export const claudeCodeSkillsDirectory = (home, environment = {}) => join(environment.CLAUDE_CONFIG_DIR ?? join(home, ".claude"), "skills");
+export const isManagedSkillManifest = (content) => content.startsWith(`---\nname: ${PRODUCT_IDENTITY.skillName}\n`) ||
+    content.startsWith(`---\r\nname: ${PRODUCT_IDENTITY.skillName}\r\n`);
+export const readSkillFile = (path) => readRegularFileText(path, { symlinks: "reject" });
 /** Resolve the skill roots required by a client selection, or all owned roots. */
-export const skillDestinations = (home, clientIds, claudeSkillsDirectory = claudeCodeSkillsDirectory(home)) => {
-    const includeClaude = clientIds === undefined || clientIds.includes("claude_code");
-    const includeShared = clientIds === undefined ||
-        clientIds.length === 0 ||
-        clientIds.some((clientId) => clientId !== "claude_code");
-    return [
-        ...(includeShared
-            ? [
-                {
-                    client: "shared",
-                    path: join(home, ".agents/skills", PRODUCT_IDENTITY.skillName),
-                },
-            ]
-            : []),
-        ...(includeClaude
-            ? [
-                {
-                    client: "claude_code",
-                    path: join(claudeSkillsDirectory, PRODUCT_IDENTITY.skillName),
-                },
-            ]
-            : []),
-    ];
+export const skillDestinations = (home, clientIds, environment = {}, platform = process.platform) => clientSkillDirectories(home, clientIds, environment, platform).map(({ client, directory }) => ({
+    client,
+    path: join(directory, PRODUCT_IDENTITY.skillName),
+}));
+/** Resolve existing REA-owned skill roots using setup's canonical destinations. */
+export const existingSkillDestinations = async (home, environment = {}, platform = process.platform) => {
+    const existing = [];
+    for (const destination of skillDestinations(home, undefined, environment, platform)) {
+        try {
+            const root = await lstat(destination.path);
+            if (root.isSymbolicLink() || !root.isDirectory())
+                continue;
+            const manifest = join(destination.path, "SKILL.md");
+            const content = await readSkillFile(manifest);
+            if (isManagedSkillManifest(content))
+                existing.push(destination);
+        }
+        catch (cause) {
+            if (cause instanceof Error && "code" in cause && cause.code === "ENOENT")
+                continue;
+            if (cause instanceof NonRegularFileReadError)
+                continue;
+            throw cause;
+        }
+    }
+    return existing;
 };
 const readOptionalText = async (path) => {
     try {
-        return await readFile(path, "utf8");
+        return await readSkillFile(path);
     }
     catch (cause) {
         if (cause instanceof Error && "code" in cause && cause.code === "ENOENT")
@@ -47,7 +56,7 @@ const readOptionalText = async (path) => {
         throw cause;
     }
 };
-const canonicalSkillFiles = async (home, clientIds, claudeSkillsDirectory) => Promise.all(skillDestinations(home, clientIds, claudeSkillsDirectory).flatMap(({ path: root }) => SKILL_FILES.map(async (relativePath) => {
+const canonicalSkillFiles = async (home, clientIds, environment = {}, platform = process.platform) => Promise.all(skillDestinations(home, clientIds, environment, platform).flatMap(({ path: root }) => MANAGED_SKILL_FILES.map(async (relativePath) => {
     const destination = join(root, relativePath);
     return {
         destination,
@@ -56,9 +65,9 @@ const canonicalSkillFiles = async (home, clientIds, claudeSkillsDirectory) => Pr
     };
 })));
 /** Report whether setup would change any file in the managed REA skill bundle. */
-export const canonicalSkillNeedsInstall = async (home, clientIds = [], claudeSkillsDirectory) => {
+export const canonicalSkillNeedsInstall = async (home, clientIds = [], environment = {}, platform = process.platform) => {
     try {
-        return (await canonicalSkillFiles(home, clientIds, claudeSkillsDirectory)).some(({ content, original }) => original !== content);
+        return (await canonicalSkillFiles(home, clientIds, environment, platform)).some(({ content, original }) => original !== content);
     }
     catch (cause) {
         // Unreadable skill state fails open to install so setup can repair it.
@@ -67,6 +76,16 @@ export const canonicalSkillNeedsInstall = async (home, clientIds = [], claudeSki
     }
 };
 const writeText = (path, content) => writeFileAtomic(path, content, { encoding: "utf8", mode: 0o600 });
+const preserveSkillBackup = async (source, destination) => {
+    try {
+        await copyFile(source, destination, fsConstants.COPYFILE_EXCL);
+    }
+    catch (cause) {
+        if (cause instanceof Error && "code" in cause && cause.code === "EEXIST")
+            return;
+        throw cause;
+    }
+};
 const restoreSkillFiles = async (changed) => {
     for (const { destination, original } of [...changed].reverse()) {
         if (original === undefined)
@@ -76,22 +95,22 @@ const restoreSkillFiles = async (changed) => {
     }
 };
 /** Transactionally install or upgrade the canonical REA skill and references. */
-export const installCanonicalSkill = async (home, clientIds = [], claudeSkillsDirectory) => {
+export const installCanonicalSkill = async (home, clientIds = [], environment = {}, platform = process.platform) => {
     let changed = [];
     try {
-        const canonical = await canonicalSkillFiles(home, clientIds, claudeSkillsDirectory);
+        const canonical = await canonicalSkillFiles(home, clientIds, environment, platform);
         changed = canonical.filter(({ content, original }) => original !== content);
         if (changed.length === 0)
             return "unchanged";
         for (const { destination, original } of changed) {
             await mkdir(dirname(destination), { recursive: true });
             if (original !== undefined)
-                await writeText(`${destination}.rea.backup`, original);
+                await preserveSkillBackup(destination, `${destination}.rea.backup`);
         }
         for (const { destination, content } of changed)
             await writeText(destination, content);
         for (const { destination, content } of changed)
-            if ((await readFile(destination, "utf8")) !== content)
+            if ((await readSkillFile(destination)) !== content)
                 throw new Error(`skill readback mismatch: ${destination}`);
         return "installed";
     }
@@ -109,12 +128,12 @@ export const installCanonicalSkill = async (home, clientIds = [], claudeSkillsDi
     }
 };
 /** Read installed skill metadata and compare every managed location. */
-export const readInstalledSkillIdentity = async (home, clientIds, claudeSkillsDirectory) => {
-    const destinations = skillDestinations(home, clientIds, claudeSkillsDirectory);
+export const readInstalledSkillIdentity = async (home, clientIds, environment = {}, platform = process.platform) => {
+    const destinations = skillDestinations(home, clientIds, environment, platform);
     let content;
     for (const destination of destinations) {
         try {
-            content = await readFile(join(destination.path, "SKILL.md"), "utf8");
+            content = await readSkillFile(join(destination.path, "SKILL.md"));
             break;
         }
         catch {
@@ -126,7 +145,7 @@ export const readInstalledSkillIdentity = async (home, clientIds, claudeSkillsDi
         return undefined;
     const toolCount = /^\s{2}tool_count:\s*(\d+)\s*$/mu.exec(content)?.[1];
     return {
-        canonical: !(await canonicalSkillNeedsInstall(home, clientIds, claudeSkillsDirectory)),
+        canonical: !(await canonicalSkillNeedsInstall(home, clientIds, environment, platform)),
         version: /^\s{2}version:\s*"([^"]+)"\s*$/mu.exec(content)?.[1] ?? null,
         toolCount: toolCount === undefined ? null : Number.parseInt(toolCount, 10),
     };

package/dist/application/SupportedClients.js

@@ -1,5 +1,8 @@
-import { isAbsolute, join } from "node:path";
+import { dirname, isAbsolute, join, resolve, win32 } from "node:path";
+import { fileURLToPath } from "node:url";
 import { lstatSync } from "node:fs";
+import { err, ok } from "../domain/result.js";
+import { HermesClientPathError, resolveHermesClientHome, } from "./HermesClientHome.js";
 const vscodeUserDirectory = ({ home, platform, env, }) => {
     if (platform === "win32")
         return join(env.APPDATA ?? join(home, "AppData", "Roaming"), "Code", "User");
@@ -16,8 +19,24 @@ const claudeDesktopDirectory = ({ home, platform, env, }) => {
 };
 const claudeCodeConfigDirectory = ({ home, env }) => env.CLAUDE_CONFIG_DIR ?? home;
 const claudeCodeMarkerDirectory = ({ home, env }) => env.CLAUDE_CONFIG_DIR ?? join(home, ".claude");
-const codexDirectory = ({ home, env }) => env.CODEX_HOME ?? join(home, ".codex");
-const grokDirectory = ({ home, env }) => env.GROK_HOME ?? join(home, ".grok");
+const codexDirectory = ({ home, env }) => env.CODEX_HOME || join(home, ".codex");
+/** Match Qwen Code's home override, including tilde and cwd-relative paths. */
+const qwenCodeDirectory = ({ home, env }) => {
+    const override = env.QWEN_HOME;
+    if (!override)
+        return join(home, ".qwen");
+    const expanded = override === "~"
+        ? home
+        : override.startsWith("~/") || override.startsWith("~\\")
+            ? join(home, ...override
+                .slice(2)
+                .split(/[/\\]+/)
+                .filter(Boolean))
+            : override;
+    return isAbsolute(expanded) ? expanded : resolve(expanded);
+};
+const grokDirectory = ({ home, env }) => env.GROK_HOME || join(home, ".grok");
+const hermesDirectory = ({ home, platform, env }) => resolveHermesClientHome(home, platform, env);
 /** Grok Bot uses an absolute SAND_DATA_ROOT; anything else stays ~/.grokbot. */
 const grokBotDirectory = ({ home, env }) => {
     const root = env.SAND_DATA_ROOT;
@@ -35,51 +54,101 @@ export const manualRegistrationRemediation = (clientName) => clientName === "gro
     ? GROK_BOT_MANUAL_REGISTRATION_REMEDIATION
     : undefined;
 const OMP_PROFILE_NAME = /^[a-z0-9][a-z0-9._-]{0,63}$/u;
-/**
- * OMP's active named profile. OMP_PROFILE wins over the legacy PI_PROFILE even
- * when empty; empty and "default" select the default profile. OMP refuses to
- * start with an invalid name, so one leaves the default location in place.
- */
-const ompProfile = ({ env }) => {
-    const name = (env.OMP_PROFILE ?? env.PI_PROFILE)?.trim();
-    return name === undefined ||
-        name === "" ||
-        name === "default" ||
-        name.endsWith(".") ||
-        !OMP_PROFILE_NAME.test(name)
-        ? undefined
-        : name;
-};
+const OMP_RESERVED_PROFILE = /^(?:CON|PRN|AUX|NUL|COM[0-9]|LPT[0-9])(?:\..*)?$/iu;
 /**
  * The OMP agent directory whose `mcp.json` holds user-scope MCP servers. OMP
  * joins PI_CONFIG_DIR to the home directory, and a named profile ignores
- * PI_CODING_AGENT_DIR. OMP resolves a relative agent directory against each
- * process's working directory, so only an absolute override names one file.
+ * PI_CODING_AGENT_DIR. Relative overrides use the setup process working directory.
  */
 const ompAgentDirectory = (context) => {
     const root = join(context.home, context.env.PI_CONFIG_DIR || ".omp");
-    const profile = ompProfile(context);
-    if (profile !== undefined)
-        return join(root, "profiles", profile, "agent");
+    // OMP_PROFILE wins even when empty. Match OMP's validation on every host.
+    const profile = (context.env.OMP_PROFILE ?? context.env.PI_PROFILE)?.trim();
+    if (profile !== undefined && profile !== "" && profile !== "default") {
+        if (!OMP_PROFILE_NAME.test(profile) ||
+            profile.endsWith(".") ||
+            OMP_RESERVED_PROFILE.test(profile))
+            return err({
+                path: root,
+                message: `Invalid OMP profile ${JSON.stringify(profile)}: names must match ^[a-z0-9][a-z0-9._-]{0,63}$, cannot end with ".", and cannot be a Windows reserved device name (CON, PRN, AUX, NUL, COM0-9, LPT0-9, including extensions). Repair OMP_PROFILE or PI_PROFILE before configuring OMP.`,
+            });
+        return ok(join(root, "profiles", profile, "agent"));
+    }
     const override = context.env.PI_CODING_AGENT_DIR;
-    return override !== undefined && override !== "" && isAbsolute(override)
-        ? override
-        : join(root, "agent");
+    return ok(override ? resolve(override) : join(root, "agent"));
+};
+/**
+ * Pi's public getAgentDir()/normalizePath semantics, not OMP's profiles.
+ * Keep relative overrides relative: filesystem consumers resolve them in cwd.
+ */
+const piAgentDirectory = ({ home, platform, env, }) => {
+    const paths = platform === "win32" ? win32 : { join };
+    let directory = env.PI_CODING_AGENT_DIR;
+    if (!directory)
+        return paths.join(home, ".pi", "agent");
+    if (platform === "win32" &&
+        directory.startsWith("/") &&
+        !directory.startsWith("//") &&
+        !directory.includes("\\")) {
+        const drive = /^\/(?:mnt\/|cygdrive\/)?([a-z])(?:\/(.*))?$/iu.exec(directory);
+        if (drive !== null)
+            directory = `${drive[1]?.toUpperCase()}:\\${drive[2]?.replaceAll("/", "\\") ?? ""}`;
+    }
+    if (directory === "~")
+        return home;
+    if (directory.startsWith("~/") ||
+        (platform === "win32" && directory.startsWith("~\\")))
+        return paths.join(home, directory.slice(2));
+    if (directory.startsWith("file://"))
+        return fileURLToPath(directory, { windows: platform === "win32" });
+    return directory;
 };
 const copilotDirectory = ({ home, env }) => env.COPILOT_HOME ?? join(home, ".copilot");
 const commandCodeDirectory = ({ home }) => join(home, ".commandcode");
-const opencodeDirectory = ({ home, env }) => join(env.XDG_CONFIG_HOME ?? join(home, ".config"), "opencode");
+/**
+ * OpenCode appends `OPENCODE_CONFIG_DIR` only when the value is non-empty.
+ * An empty variable is the same as unset and leaves the XDG directory in place.
+ */
+const openCodeOverrideDirectory = (env) => {
+    const directory = env.OPENCODE_CONFIG_DIR;
+    return directory === undefined || directory === "" ? undefined : directory;
+};
+const opencodeDirectory = (context) => openCodeOverrideDirectory(context.env) ??
+    join(context.env.XDG_CONFIG_HOME ?? join(context.home, ".config"), "opencode");
+/** OpenCode loads global JSON before JSONC, then explicit file and directory overrides. */
+const openCodeConfigurationPaths = (context) => {
+    const directory = join(context.env.XDG_CONFIG_HOME ?? join(context.home, ".config"), "opencode");
+    const overrideDirectory = openCodeOverrideDirectory(context.env);
+    const paths = [
+        join(directory, "config.json"),
+        join(directory, "opencode.json"),
+        join(directory, "opencode.jsonc"),
+        ...(context.env.OPENCODE_CONFIG ? [context.env.OPENCODE_CONFIG] : []),
+        ...(overrideDirectory !== undefined
+            ? [
+                join(overrideDirectory, "opencode.json"),
+                join(overrideDirectory, "opencode.jsonc"),
+            ]
+            : []),
+    ];
+    const resolved = paths.map((path) => resolve(path));
+    return resolved.filter((path, index) => resolved.lastIndexOf(path) === index);
+};
 const existingOpenCodeConfigPath = (context) => {
-    if (context.env.OPENCODE_CONFIG !== undefined)
-        return context.env.OPENCODE_CONFIG;
-    const directory = opencodeDirectory(context);
-    const candidates = [
-        "opencode.json",
-        "opencode.jsonc",
-        ".opencode.json",
-        ".opencode.jsonc",
-    ].map((filename) => join(directory, filename));
-    return (candidates.find((path) => {
+    // The selected directory is loaded after an explicit file by OpenCode V1.
+    const overrideDirectory = openCodeOverrideDirectory(context.env);
+    const candidates = overrideDirectory !== undefined
+        ? [
+            join(overrideDirectory, "opencode.json"),
+            join(overrideDirectory, "opencode.jsonc"),
+        ].map((path) => resolve(path))
+        : context.env.OPENCODE_CONFIG
+            ? [resolve(context.env.OPENCODE_CONFIG)]
+            : [
+                join(opencodeDirectory(context), "opencode.json"),
+                join(opencodeDirectory(context), "opencode.jsonc"),
+            ].map((path) => resolve(path));
+    return ([...candidates].reverse().find((path) => {
         try {
             lstatSync(path);
             return true;
@@ -90,17 +159,44 @@ const existingOpenCodeConfigPath = (context) => {
                 cause.code === "ENOENT");
         }
     }) ??
-        candidates[0] ??
-        join(directory, "opencode.json"));
+        resolve(overrideDirectory !== undefined
+            ? join(overrideDirectory, "opencode.json")
+            : context.env.OPENCODE_CONFIG ||
+                join(opencodeDirectory(context), "opencode.json")));
+};
+const geminiSettings = ({ home, platform, env, }) => {
+    const system = env.GEMINI_CLI_SYSTEM_SETTINGS_PATH ||
+        (platform === "darwin"
+            ? "/Library/Application Support/GeminiCli/settings.json"
+            : platform === "win32"
+                ? "C:\\ProgramData\\gemini-cli\\settings.json"
+                : "/etc/gemini-cli/settings.json");
+    const trustOverride = env.GEMINI_RESTRICTED_MODE === "true" ||
+        env.GEMINI_CLI_TRUST_WORKSPACE === "false"
+        ? false
+        : env.GEMINI_CLI_TRUST_WORKSPACE === "true"
+            ? true
+            : undefined;
+    return {
+        systemPath: system,
+        defaultsPath: env.GEMINI_CLI_SYSTEM_DEFAULTS_PATH ||
+            join(dirname(system), "system-defaults.json"),
+        workspaceDirectory: process.cwd(),
+        trustedFoldersPath: env.GEMINI_CLI_TRUSTED_FOLDERS_PATH ||
+            join(env.GEMINI_CLI_HOME || home, ".gemini", "trustedFolders.json"),
+        ...(trustOverride === undefined ? {} : { trustOverride }),
+        platform,
+    };
 };
 const devinDirectory = ({ home, platform, env }) => platform === "win32"
     ? join(env.APPDATA ?? join(home, "AppData", "Roaming"), "devin")
-    : join(home, ".config", "devin");
+    : join(env.XDG_CONFIG_HOME || join(home, ".config"), "devin");
 /** Stable product metadata used to derive setup discovery and documentation. */
 export const SUPPORTED_CLIENT_DEFINITIONS = [
     {
         name: "claude_code",
         displayName: "Claude Code",
+        skillPath: ({ home, env }) => join(env.CLAUDE_CONFIG_DIR ?? join(home, ".claude"), "skills"),
         configPath: (context) => join(claudeCodeConfigDirectory(context), ".claude.json"),
         markerPath: claudeCodeMarkerDirectory,
         format: "json",
@@ -129,8 +225,10 @@ export const SUPPORTED_CLIENT_DEFINITIONS = [
     {
         name: "gemini_cli",
         displayName: "Gemini CLI",
-        configPath: [".gemini", "settings.json"],
-        markerPath: [".gemini"],
+        geminiSettings,
+        configPath: ({ home, env }) => join(env.GEMINI_CLI_HOME || home, ".gemini", "settings.json"),
+        markerPath: ({ home, env }) => join(env.GEMINI_CLI_HOME || home, ".gemini"),
+        skillPath: ({ home, env }) => join(env.GEMINI_CLI_HOME || home, ".agents", "skills"),
         format: "json",
     },
     {
@@ -151,12 +249,14 @@ export const SUPPORTED_CLIENT_DEFINITIONS = [
         name: "opencode",
         displayName: "OpenCode",
         configPath: existingOpenCodeConfigPath,
+        configPaths: openCodeConfigurationPaths,
         markerPath: opencodeDirectory,
         format: "opencode",
     },
     {
         name: "antigravity",
         displayName: "Antigravity",
+        skillPath: [".gemini", "config", "skills"],
         configPath: [".gemini", "config", "mcp_config.json"],
         markerPath: [".gemini", "config"],
         format: "json",
@@ -175,6 +275,13 @@ export const SUPPORTED_CLIENT_DEFINITIONS = [
         markerPath: commandCodeDirectory,
         format: "commandcode",
     },
+    {
+        name: "qwen_code",
+        displayName: "Qwen Code",
+        configPath: (context) => join(qwenCodeDirectory(context), "settings.json"),
+        markerPath: qwenCodeDirectory,
+        format: "json",
+    },
     {
         name: "vscode",
         displayName: "VS Code",
@@ -192,10 +299,28 @@ export const SUPPORTED_CLIENT_DEFINITIONS = [
     {
         name: "omp",
         displayName: "OMP",
-        configPath: (context) => join(ompAgentDirectory(context), "mcp.json"),
+        configPath: (context) => {
+            const directory = ompAgentDirectory(context);
+            return directory.ok ? ok(join(directory.value, "mcp.json")) : directory;
+        },
         markerPath: ompAgentDirectory,
         format: "omp",
     },
+    {
+        name: "pi",
+        displayName: "Pi",
+        configPath: (context) => (context.platform === "win32" ? win32 : { join }).join(piAgentDirectory(context), "mcp.json"),
+        markerPath: piAgentDirectory,
+        format: "pi",
+    },
+    {
+        name: "hermes",
+        displayName: "Hermes",
+        skillPath: (context) => join(hermesDirectory(context), "skills"),
+        configPath: (context) => join(hermesDirectory(context), "config.yaml"),
+        markerPath: hermesDirectory,
+        format: "hermes",
+    },
     {
         name: "grok_bot",
         displayName: "Grok Bot",
@@ -204,28 +329,128 @@ export const SUPPORTED_CLIENT_DEFINITIONS = [
         format: "unsupported",
     },
 ];
-const resolvePath = (path, context) => typeof path === "function" ? path(context) : join(context.home, ...path);
+/**
+ * Paths whose presence means doctor and setup should inspect the client.
+ * Layered sources count: OpenCode still loads its XDG files when a custom
+ * directory override does not exist.
+ */
+export const clientEvidencePaths = (client) => [
+    ...new Set([
+        client.configPath,
+        ...(client.configPaths ?? []),
+        client.markerPath,
+    ].filter((path) => path !== undefined && path.length > 0)),
+];
+const resolvePath = (path, context) => {
+    const resolved = typeof path === "function" ? path(context) : join(context.home, ...path);
+    return typeof resolved === "string" ? ok(resolved) : resolved;
+};
 /** Describe every client location that setup, doctor, or uninstall may inspect. */
-export const supportedClients = (home, platform = process.platform, env = {
-    APPDATA: process.env.APPDATA,
-    CLAUDE_CONFIG_DIR: process.env.CLAUDE_CONFIG_DIR,
-    CODEX_HOME: process.env.CODEX_HOME,
-    COPILOT_HOME: process.env.COPILOT_HOME,
-    GROK_HOME: process.env.GROK_HOME,
-    OMP_PROFILE: process.env.OMP_PROFILE,
-    OPENCODE_CONFIG: process.env.OPENCODE_CONFIG,
-    PI_CODING_AGENT_DIR: process.env.PI_CODING_AGENT_DIR,
-    PI_CONFIG_DIR: process.env.PI_CONFIG_DIR,
-    PI_PROFILE: process.env.PI_PROFILE,
-    SAND_DATA_ROOT: process.env.SAND_DATA_ROOT,
-    XDG_CONFIG_HOME: process.env.XDG_CONFIG_HOME,
-}) => {
+export const supportedClients = (home, platform = process.platform, env = process.env) => {
     const context = { home, platform, env };
-    return SUPPORTED_CLIENT_DEFINITIONS.map((definition) => ({
-        name: definition.name,
-        displayName: definition.displayName,
-        configPath: resolvePath(definition.configPath, context),
-        markerPath: resolvePath(definition.markerPath, context),
-        format: definition.format,
-    }));
+    const definitions = SUPPORTED_CLIENT_DEFINITIONS;
+    return definitions.map((definition) => {
+        try {
+            const config = resolvePath(definition.configPath, context);
+            const marker = config.ok
+                ? resolvePath(definition.markerPath, context)
+                : config;
+            if (!config.ok)
+                return {
+                    name: definition.name,
+                    displayName: definition.displayName,
+                    format: definition.format,
+                    configPath: config.error.path,
+                    configPathError: config.error.message,
+                };
+            if (!marker.ok)
+                return {
+                    name: definition.name,
+                    displayName: definition.displayName,
+                    format: definition.format,
+                    configPath: marker.error.path,
+                    configPathError: marker.error.message,
+                };
+            const configPath = config.value;
+            return {
+                name: definition.name,
+                displayName: definition.displayName,
+                configPath,
+                ...(definition.geminiSettings === undefined
+                    ? {}
+                    : { geminiSettings: definition.geminiSettings(context) }),
+                ...(definition.configPaths === undefined
+                    ? {}
+                    : {
+                        configPaths: [
+                            ...new Set([...definition.configPaths(context), configPath]),
+                        ],
+                    }),
+                markerPath: marker.value,
+                format: definition.format,
+            };
+        }
+        catch (cause) {
+            if (cause instanceof HermesClientPathError)
+                return {
+                    name: definition.name,
+                    displayName: definition.displayName,
+                    format: definition.format,
+                    configPath: cause.path,
+                    configPathError: cause.message,
+                };
+            if (definition.name !== "pi")
+                throw cause;
+            return {
+                name: definition.name,
+                displayName: definition.displayName,
+                format: definition.format,
+                configPath: env.PI_CODING_AGENT_DIR ?? "",
+                configPathError: `Invalid PI_CODING_AGENT_DIR: ${cause instanceof Error ? cause.message : String(cause)}. Repair the override before configuring Pi.`,
+            };
+        }
+    });
+};
+/** Resolve personal skill roots using the same client environment as setup. */
+export const clientSkillDirectories = (home, clientIds, environment = {}, platform = process.platform) => {
+    const definitions = SUPPORTED_CLIENT_DEFINITIONS;
+    const selected = clientIds === undefined
+        ? [
+            "shared",
+            ...definitions
+                .filter(({ skillPath }) => skillPath !== undefined)
+                .map(({ name }) => name),
+        ]
+        : clientIds.length === 0
+            ? ["shared"]
+            : clientIds;
+    const destinations = new Map();
+    for (const client of selected) {
+        const definition = definitions.find(({ name }) => name === client);
+        let directory;
+        try {
+            const resolved = definition?.skillPath === undefined
+                ? ok(join(home, ".agents", "skills"))
+                : resolvePath(definition.skillPath, {
+                    home,
+                    platform,
+                    env: environment,
+                });
+            if (!resolved.ok)
+                continue;
+            directory = resolved.value;
+        }
+        catch (cause) {
+            // Registration diagnostics own an unresolved profile; never fall back to another skill root.
+            if (cause instanceof HermesClientPathError)
+                continue;
+            throw cause;
+        }
+        if (!destinations.has(directory))
+            destinations.set(directory, {
+                client: directory === join(home, ".agents", "skills") ? "shared" : client,
+                directory,
+            });
+    }
+    return [...destinations.values()].sort((left, right) => left.directory.localeCompare(right.directory));
 };