@evo-dev/evodev 0.0.1-alpha → 0.0.1-alpha.2

package/dist/plugins/evodev/hooks/codex.ts

@@ -1,8 +1,12 @@
+import type { Dirent } from "node:fs";
+import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
 import type {
   CodeAgentCapabilities,
   CodeAgentPlugin,
   DoctorCheck,
   DoctorContext,
+  HookEventType,
   PluginDetectionResult,
   PluginInstallInput,
   PluginInstallResult,
@@ -11,9 +15,29 @@ import type {
   SyncSkillsInput,
 } from "@evo-dev/core/plugins";
 import { runNodeCommand } from "./command-runner.ts";
+import { CODEX_HOOK_RUNTIME_COMMAND } from "./hooks.ts";
+import { type CodexPaths, resolveCodexAgentTargetPath, resolveCodexPaths } from "./paths.ts";
+import { transformCodexAgent } from "./transform-agent.ts";
+import {
+  type WorkspaceCoreHydrationResult,
+  hydrateWorkspaceCoreDependency,
+  isSafePluginCacheSegment,
+} from "./workspace-core.ts";
 
-const CODEX_RESERVED_MESSAGE =
-  "Codex asset sync is reserved until Codex capabilities and formats are verified.";
+const CODEX_SKILL_BUNDLE_MESSAGE =
+  "Codex skills are bundled in the EvoDev Codex plugin; direct skill sync is skipped.";
+const CODEX_CAPABILITY_HOOK_EVENTS: HookEventType[] = [
+  "SessionStart",
+  "UserPromptSubmit",
+  "PreToolUse",
+  "PermissionRequest",
+  "PostToolUse",
+  "PreCompact",
+  "PostCompact",
+  "SubagentStart",
+  "SubagentStop",
+  "Stop",
+];
 
 export interface CodexCommandResult {
   exitCode: number;
@@ -29,9 +53,55 @@ export interface CodexPluginOptions {
   commandRunner?: CodexCommandRunner;
   pluginSelector?: string;
   pluginMarketplaceSource?: string;
+  pluginMarketplaceFallbackSource?: string;
+  paths?: CodexPaths;
+  syncFileSystem?: CodexSyncFileSystem;
 }
 
+export interface CodexSyncFileSystem {
+  readFile(path: string): Promise<string>;
+  writeFile(path: string, content: string, options?: { overwrite?: boolean }): Promise<void>;
+  fileExists(path: string): Promise<boolean>;
+  ensureDir(path: string): Promise<void>;
+}
+
+const nodeSyncFileSystem: CodexSyncFileSystem = {
+  async readFile(path: string): Promise<string> {
+    return readFile(path, "utf8");
+  },
+  async writeFile(
+    path: string,
+    content: string,
+    options: { overwrite?: boolean } = {},
+  ): Promise<void> {
+    await writeFile(path, content, {
+      encoding: "utf8",
+      flag: options.overwrite === true ? "w" : "wx",
+    });
+  },
+  async fileExists(path: string): Promise<boolean> {
+    try {
+      const fileStat = await stat(path);
+      return fileStat.isFile();
+    } catch (error) {
+      if (isNotFoundError(error)) {
+        return false;
+      }
+
+      throw error;
+    }
+  },
+  async ensureDir(path: string): Promise<void> {
+    await mkdir(path, { recursive: true });
+  },
+};
+
 export function createCodexPlugin(options: CodexPluginOptions = {}): CodeAgentPlugin {
+  const syncFileSystem = options.syncFileSystem ?? nodeSyncFileSystem;
+  const getSyncPaths = (homeDir?: string) =>
+    options.paths ??
+    (homeDir === undefined ? resolveCodexPathsFromHome() : resolveCodexPaths({ homeDir }));
+
   return {
     id: "codex",
     name: "Codex",
@@ -40,9 +110,9 @@ export function createCodexPlugin(options: CodexPluginOptions = {}): CodeAgentPl
     },
     async getCapabilities(): Promise<CodeAgentCapabilities> {
       return {
-        skills: { supported: false, format: "codex-skill" },
-        agents: { supported: false, format: "codex-agent" },
-        hooks: { supported: false, events: [] },
+        skills: { supported: true, format: "codex-skill" },
+        agents: { supported: true, format: "codex-agent" },
+        hooks: { supported: true, events: [...CODEX_CAPABILITY_HOOK_EVENTS] },
       };
     },
     async doctor(context: DoctorContext): Promise<DoctorCheck[]> {
@@ -52,29 +122,30 @@ export function createCodexPlugin(options: CodexPluginOptions = {}): CodeAgentPl
       return [
         detectionToDoctorCheck(detection),
         {
-          id: "codex.assets.reserved",
-          status: enabled ? "warn" : "skip",
+          id: "codex.skills.plugin-bundled",
+          status: enabled ? "pass" : "skip",
           message: enabled
-            ? `${CODEX_RESERVED_MESSAGE} Code Agent plugin install is supported, but Codex skill/agent asset sync remains disabled.`
-            : `${CODEX_RESERVED_MESSAGE} Codex is disabled in settings.`,
+            ? "Codex skills are packaged in the EvoDev plugin and loaded through Codex plugin installation."
+            : `${CODEX_SKILL_BUNDLE_MESSAGE} Codex is disabled in settings.`,
         },
+        codexAgentsDoctorCheck(enabled, getSyncPaths(context.homeDir)),
+        await codexStopHooksDoctorCheck(getSyncPaths(context.homeDir)),
       ];
     },
     async syncSkills(input: SyncSkillsInput): Promise<SyncResult> {
-      const result = createSkippedSyncResult(input.targetPlugin);
+      const result = createEmptySyncResult(input.targetPlugin);
       for (const skill of input.skills) {
         result.skipped.push(skill.registryKey);
+        if (skill.manifest.targets.includes("codex")) {
+          result.warnings.push(
+            `${CODEX_SKILL_BUNDLE_MESSAGE} Refresh or reinstall the Codex plugin to update ${skill.registryKey}.`,
+          );
+        }
       }
-      addCodexSyncDiagnostic(result, input.dryRun, "skill");
       return result;
     },
     async syncAgents(input: SyncAgentsInput): Promise<SyncResult> {
-      const result = createSkippedSyncResult(input.targetPlugin);
-      for (const agent of input.agents) {
-        result.skipped.push(agent.registryKey);
-      }
-      addCodexSyncDiagnostic(result, input.dryRun, "agent");
-      return result;
+      return syncCodexAgents(input, getSyncPaths(), syncFileSystem);
     },
     async installPlugin(input: PluginInstallInput): Promise<PluginInstallResult> {
       return installCodexPlugin(input, options);
@@ -118,24 +189,116 @@ async function detectCodex(
 
 async function installCodexPlugin(
   input: PluginInstallInput,
-  options: Pick<CodexPluginOptions, "commandRunner" | "pluginSelector" | "pluginMarketplaceSource">,
+  options: Pick<
+    CodexPluginOptions,
+    | "commandRunner"
+    | "pluginSelector"
+    | "pluginMarketplaceSource"
+    | "pluginMarketplaceFallbackSource"
+    | "paths"
+  >,
 ): Promise<PluginInstallResult> {
   const command = "codex";
   const selector = options.pluginSelector ?? "evodev@evodev";
   const args = ["plugin", "add", selector];
   const runner = options.commandRunner ?? new NodeCodexCommandRunner();
+  const primaryResult = await installCodexPluginOnce({
+    input,
+    command,
+    selector,
+    args,
+    runner,
+    marketplaceSource: options.pluginMarketplaceSource,
+    paths: options.paths,
+  });
+
+  const fallbackSource = options.pluginMarketplaceFallbackSource;
+  if (
+    primaryResult.status !== "failed" ||
+    options.pluginMarketplaceSource === undefined ||
+    fallbackSource === undefined ||
+    fallbackSource === options.pluginMarketplaceSource ||
+    !isSshGitMarketplaceSource(options.pluginMarketplaceSource)
+  ) {
+    return primaryResult;
+  }
+
+  const fallbackResult = await installCodexPluginOnce({
+    input,
+    command,
+    selector,
+    args,
+    runner,
+    marketplaceSource: fallbackSource,
+    removeMarketplaceBeforeAdd: true,
+    paths: options.paths,
+  });
+
+  return {
+    ...fallbackResult,
+    warnings: [
+      `Codex SSH marketplace source failed (${primaryResult.message}); retried with fallback source: ${fallbackSource}.`,
+      ...fallbackResult.warnings,
+    ],
+  };
+}
+
+async function installCodexPluginOnce(input: {
+  input: PluginInstallInput;
+  command: string;
+  selector: string;
+  args: string[];
+  runner: CodexCommandRunner;
+  marketplaceSource?: string;
+  removeMarketplaceBeforeAdd?: boolean;
+  paths?: CodexPaths;
+}): Promise<PluginInstallResult> {
+  const { command, selector, args, runner } = input;
+  const warnings: string[] = [];
 
   try {
-    if (options.pluginMarketplaceSource !== undefined) {
+    if (input.marketplaceSource !== undefined) {
+      if (
+        input.removeMarketplaceBeforeAdd === true ||
+        (input.input.force === true && isGitMarketplaceSource(input.marketplaceSource))
+      ) {
+        const marketplaceName = extractMarketplaceNameFromSelector(selector);
+        if (marketplaceName === undefined) {
+          warnings.push(
+            `Skipped Codex marketplace remove before refresh because selector does not include a marketplace name: ${selector}`,
+          );
+        } else {
+          const removeMarketplaceResult = await runner.run(command, [
+            "plugin",
+            "marketplace",
+            "remove",
+            marketplaceName,
+          ]);
+          const removeMarketplaceMessage =
+            removeMarketplaceResult.stderr ?? removeMarketplaceResult.stdout;
+          if (
+            removeMarketplaceResult.exitCode !== 0 &&
+            !isNotInstalledMessage(removeMarketplaceMessage)
+          ) {
+            warnings.push(
+              `Codex marketplace refresh remove did not complete: ${
+                removeMarketplaceMessage ??
+                `Codex marketplace remove exited with code ${removeMarketplaceResult.exitCode}`
+              }`,
+            );
+          }
+        }
+      }
+
       const marketplaceResult = await runner.run(command, [
         "plugin",
         "marketplace",
         "add",
-        options.pluginMarketplaceSource,
+        input.marketplaceSource,
       ]);
       if (marketplaceResult.exitCode !== 0) {
         return createPluginInstallResult(
-          input.targetPlugin,
+          input.input.targetPlugin,
           "failed",
           command,
           args,
@@ -144,21 +307,78 @@ async function installCodexPlugin(
             `Codex marketplace add exited with code ${marketplaceResult.exitCode}`,
         );
       }
+
+      if (isGitMarketplaceSource(input.marketplaceSource)) {
+        const marketplaceName = extractMarketplaceNameFromSelector(selector);
+        if (marketplaceName === undefined) {
+          warnings.push(
+            `Skipped Codex marketplace upgrade because selector does not include a marketplace name: ${selector}`,
+          );
+        } else {
+          const upgradeResult = await runner.run(command, [
+            "plugin",
+            "marketplace",
+            "upgrade",
+            marketplaceName,
+          ]);
+          if (upgradeResult.exitCode !== 0) {
+            return createPluginInstallResult(
+              input.input.targetPlugin,
+              "failed",
+              command,
+              args,
+              upgradeResult.stderr ??
+                upgradeResult.stdout ??
+                `Codex marketplace upgrade exited with code ${upgradeResult.exitCode}`,
+            );
+          }
+        }
+      }
+    }
+
+    if (input.input.force === true) {
+      const removeArgs = ["plugin", "remove", selector];
+      const removeResult = await runner.run(command, removeArgs);
+      const removeMessage = removeResult.stderr ?? removeResult.stdout;
+      if (removeResult.exitCode !== 0 && !isNotInstalledMessage(removeMessage)) {
+        warnings.push(
+          `Codex plugin refresh remove did not complete: ${
+            removeMessage ?? `Codex plugin remove exited with code ${removeResult.exitCode}`
+          }`,
+        );
+      }
     }
 
     const result = await runner.run(command, args);
     if (result.exitCode === 0) {
+      const hydration = await hydrateCodexWorkspaceCoreDependency({
+        paths: input.paths,
+        selector,
+      });
+      warnings.push(...hydration.warnings);
+      if (hydration.errors.length > 0) {
+        return createPluginInstallResult(
+          input.input.targetPlugin,
+          "failed",
+          command,
+          args,
+          hydration.errors.join("\n"),
+          warnings,
+        );
+      }
+
       return createPluginInstallResult(
-        input.targetPlugin,
+        input.input.targetPlugin,
         "installed",
         command,
         args,
         result.stdout,
+        warnings,
       );
     }
 
     return createPluginInstallResult(
-      input.targetPlugin,
+      input.input.targetPlugin,
       "failed",
       command,
       args,
@@ -166,7 +386,7 @@ async function installCodexPlugin(
     );
   } catch (error) {
     return createPluginInstallResult(
-      input.targetPlugin,
+      input.input.targetPlugin,
       "failed",
       command,
       args,
@@ -175,6 +395,149 @@ async function installCodexPlugin(
   }
 }
 
+async function hydrateCodexWorkspaceCoreDependency(input: {
+  paths?: CodexPaths;
+  selector: string;
+}): Promise<WorkspaceCoreHydrationResult> {
+  const warnings: string[] = [];
+  const errors: string[] = [];
+
+  if (input.paths === undefined) {
+    return { warnings, errors };
+  }
+
+  const marketplaceName = extractMarketplaceNameFromSelector(input.selector);
+  const pluginName = extractPluginNameFromSelector(input.selector);
+  if (marketplaceName === undefined || pluginName === undefined) {
+    warnings.push(
+      `Skipped @evo-dev/core hydration because Codex plugin selector is not marketplace-qualified: ${input.selector}`,
+    );
+    return { warnings, errors };
+  }
+  if (!isSafePluginCacheSegment(marketplaceName) || !isSafePluginCacheSegment(pluginName)) {
+    warnings.push(
+      `Skipped @evo-dev/core hydration because Codex plugin selector contains an unsafe cache segment: ${input.selector}`,
+    );
+    return { warnings, errors };
+  }
+
+  const cachePluginRoot = `${input.paths.codexDir}/plugins/cache/${marketplaceName}/${pluginName}`;
+  const marketplaceCoreRoot = `${input.paths.codexDir}/.tmp/marketplaces/${marketplaceName}/packages/core`;
+  const hydration = await hydrateWorkspaceCoreDependency({
+    sourceCoreRoot: marketplaceCoreRoot,
+    cachePluginRoot,
+    runtimeLabel: "Codex",
+  });
+  const hookPatch = await patchCodexInstalledHookRuntimeCommands({ cachePluginRoot });
+  return {
+    warnings: [...warnings, ...hydration.warnings, ...hookPatch.warnings],
+    errors: [...errors, ...hydration.errors, ...hookPatch.errors],
+  };
+}
+
+async function patchCodexInstalledHookRuntimeCommands(input: {
+  cachePluginRoot: string;
+}): Promise<WorkspaceCoreHydrationResult> {
+  const warnings: string[] = [];
+  const errors: string[] = [];
+  const installedPluginRoot = await findLatestInstalledCodexPluginRoot(input.cachePluginRoot);
+  if (installedPluginRoot === null) {
+    warnings.push(
+      `Skipped Codex hook runtime command patch because the plugin cache was not found: ${input.cachePluginRoot}`,
+    );
+    return { warnings, errors };
+  }
+
+  const hooksPath = `${installedPluginRoot}/hooks/codex-hooks.json`;
+  try {
+    const hooksText = await readTextFileIfExists(hooksPath);
+    if (hooksText === null || hooksText.trim() === "") {
+      warnings.push(
+        `Skipped Codex hook runtime command patch because hooks file is missing: ${hooksPath}`,
+      );
+    } else {
+      const hooksConfig = JSON.parse(hooksText) as unknown;
+      if (rewriteCodexHookRuntimeCommands(hooksConfig)) {
+        await writeFile(hooksPath, `${JSON.stringify(hooksConfig, null, 2)}\n`, "utf8");
+      }
+    }
+  } catch (error) {
+    errors.push(
+      `Cannot patch Codex hook runtime command in installed plugin cache: ${describeError(error)}`,
+    );
+  }
+
+  const hooksSourcePath = `${installedPluginRoot}/hooks/hooks.ts`;
+  try {
+    const hooksSource = await readTextFileIfExists(hooksSourcePath);
+    if (hooksSource !== null) {
+      const next = hooksSource.replaceAll(
+        'bun run "${PLUGIN_ROOT}/hooks/runtime.ts" hook runtime --target codex',
+        CODEX_HOOK_RUNTIME_COMMAND,
+      );
+      if (next !== hooksSource) {
+        await writeFile(hooksSourcePath, next, "utf8");
+      }
+    }
+  } catch (error) {
+    errors.push(
+      `Cannot patch Codex hook runtime source in installed plugin cache: ${describeError(error)}`,
+    );
+  }
+
+  return { warnings, errors };
+}
+
+function rewriteCodexHookRuntimeCommands(value: unknown): boolean {
+  if (!isRecord(value)) return false;
+  const root = isRecord(value.hooks) ? value.hooks : value;
+  let changed = false;
+  for (const groups of Object.values(root)) {
+    if (!Array.isArray(groups)) continue;
+    for (const group of groups) {
+      if (!isRecord(group) || !Array.isArray(group.hooks)) continue;
+      for (const hook of group.hooks) {
+        if (!isRecord(hook) || hook.type !== "command" || typeof hook.command !== "string") {
+          continue;
+        }
+        if (
+          hook.command.includes("hook runtime --target codex") &&
+          hook.command !== CODEX_HOOK_RUNTIME_COMMAND
+        ) {
+          hook.command = CODEX_HOOK_RUNTIME_COMMAND;
+          changed = true;
+        }
+      }
+    }
+  }
+  return changed;
+}
+
+async function findLatestInstalledCodexPluginRoot(cachePluginRoot: string): Promise<string | null> {
+  let entries: Dirent[];
+  try {
+    entries = await readdir(cachePluginRoot, { withFileTypes: true });
+  } catch (error) {
+    if (isNotFoundError(error)) return null;
+    throw error;
+  }
+
+  const versionDirs = await Promise.all(
+    entries
+      .filter((entry) => entry.isDirectory())
+      .map(async (entry) => {
+        const path = `${cachePluginRoot}/${entry.name}`;
+        const pathStat = await stat(path);
+        return { path, mtimeMs: pathStat.mtimeMs };
+      }),
+  );
+  if (versionDirs.length === 0) return null;
+  versionDirs.sort(
+    (left, right) => right.mtimeMs - left.mtimeMs || right.path.localeCompare(left.path),
+  );
+  return versionDirs[0].path;
+}
+
 class NodeCodexCommandRunner implements CodexCommandRunner {
   async run(command: string, args: string[]): Promise<CodexCommandResult> {
     return runNodeCommand(command, args);
@@ -193,7 +556,151 @@ function detectionToDoctorCheck(detection: PluginDetectionResult): DoctorCheck {
   return { id: "codex.available", status: "warn", message: detection.message };
 }
 
-function createSkippedSyncResult(targetPlugin: string): SyncResult {
+async function codexStopHooksDoctorCheck(paths: CodexPaths): Promise<DoctorCheck> {
+  const hooksText = await readTextFileIfExists(paths.hooksPath);
+  if (hooksText === null || hooksText.trim() === "") {
+    return {
+      id: "codex.hooks.stop",
+      status: "skip",
+      message: `No user-level Codex hooks file found at: ${paths.hooksPath}`,
+    };
+  }
+
+  let hooksConfig: unknown;
+  try {
+    hooksConfig = JSON.parse(hooksText) as unknown;
+  } catch {
+    return {
+      id: "codex.hooks.stop",
+      status: "warn",
+      message: `Codex hooks file is not valid JSON; existing Stop hook failures may come from: ${paths.hooksPath}`,
+    };
+  }
+
+  const stopHooks = collectCodexCommandHooks(hooksConfig, "Stop");
+  if (stopHooks.length === 0) {
+    return {
+      id: "codex.hooks.stop",
+      status: "skip",
+      message: `No user-level Codex Stop hooks configured in: ${paths.hooksPath}`,
+    };
+  }
+
+  const hooksMissingTimeout = stopHooks.filter((hook) => hook.timeout === null);
+  if (hooksMissingTimeout.length > 0) {
+    return {
+      id: "codex.hooks.stop",
+      status: "warn",
+      message: `Codex Stop hook command(s) without timeout may be killed by the host and show "hook exited without a status code": ${hooksMissingTimeout
+        .map((hook) => hook.label)
+        .join(", ")}`,
+    };
+  }
+
+  return {
+    id: "codex.hooks.stop",
+    status: "pass",
+    message: `Codex Stop hooks have explicit timeouts in: ${paths.hooksPath}`,
+  };
+}
+
+function collectCodexCommandHooks(
+  hooksConfig: unknown,
+  eventName: string,
+): Array<{ label: string; timeout: number | null }> {
+  if (!isRecord(hooksConfig)) return [];
+  const root = isRecord(hooksConfig.hooks) ? hooksConfig.hooks : hooksConfig;
+  const groups = isRecord(root) && Array.isArray(root[eventName]) ? root[eventName] : [];
+  const hooks: Array<{ label: string; timeout: number | null }> = [];
+
+  groups.forEach((group, groupIndex) => {
+    if (!isRecord(group) || !Array.isArray(group.hooks)) return;
+    group.hooks.forEach((hook, hookIndex) => {
+      if (!isRecord(hook) || typeof hook.command !== "string" || hook.type !== "command") return;
+      hooks.push({
+        label: `${eventName}[${groupIndex}].hooks[${hookIndex}] ${summarizeHookCommand(
+          hook.command,
+        )}`,
+        timeout:
+          typeof hook.timeout === "number" && Number.isFinite(hook.timeout) ? hook.timeout : null,
+      });
+    });
+  });
+
+  return hooks;
+}
+
+function summarizeHookCommand(command: string): string {
+  const compact = command.replace(/\s+/g, " ").trim();
+  if (compact.includes("@dp/ab-agent-collect-event")) return "@dp/ab-agent-collect-event";
+  if (compact.includes("flux-hooks")) return "flux-hooks";
+  if (compact.includes("flux-bits-report")) return "flux-bits-report";
+  if (compact.includes("hook runtime --target codex")) return "evodev codex hook runtime";
+  return compact.length <= 80 ? compact : `${compact.slice(0, 77)}...`;
+}
+
+async function readTextFileIfExists(path: string): Promise<string | null> {
+  try {
+    return await readFile(path, "utf8");
+  } catch (error) {
+    if (isNotFoundError(error)) return null;
+    throw error;
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+async function syncCodexAgents(
+  input: SyncAgentsInput,
+  paths: CodexPaths,
+  fileSystem: CodexSyncFileSystem,
+): Promise<SyncResult> {
+  const result = createEmptySyncResult(input.targetPlugin);
+
+  for (const asset of input.agents) {
+    if (!asset.manifest.targets.includes("codex")) {
+      result.skipped.push(asset.registryKey);
+      continue;
+    }
+
+    try {
+      const source = await fileSystem.readFile(asset.entryPath);
+      const transformed = transformCodexAgent({ asset, source });
+      const targetPath = resolveCodexAgentTargetPath(transformed.name, paths);
+      const targetExists = await fileSystem.fileExists(targetPath);
+
+      if (targetExists && input.force !== true) {
+        result.skipped.push(asset.registryKey);
+        result.warnings.push(`Skipped existing Codex agent target: ${targetPath}`);
+        continue;
+      }
+
+      if (!input.dryRun) {
+        await fileSystem.ensureDir(dirname(targetPath));
+        await fileSystem.writeFile(targetPath, ensureTrailingNewline(transformed.content), {
+          overwrite: input.force === true,
+        });
+      }
+
+      if (targetExists) {
+        result.warnings.push(
+          `${input.dryRun ? "Would update" : "Updated"} existing Codex agent target: ${targetPath}`,
+        );
+      }
+      result.syncedAgents.push(asset.registryKey);
+    } catch (error) {
+      result.errors.push(
+        `Failed to sync Codex agent ${asset.registryKey}: ${describeError(error)}`,
+      );
+    }
+  }
+
+  return result;
+}
+
+function createEmptySyncResult(targetPlugin: string): SyncResult {
   return {
     targetPlugin,
     syncedSkills: [],
@@ -204,14 +711,20 @@ function createSkippedSyncResult(targetPlugin: string): SyncResult {
   };
 }
 
-function addCodexSyncDiagnostic(
-  result: SyncResult,
-  dryRun: boolean,
-  assetKind: "skill" | "agent",
-): void {
-  const message = `Codex ${assetKind} sync unsupported: capabilities are unverified; no writes planned in I10.`;
-  if (dryRun) result.warnings.push(message);
-  else result.errors.push(message);
+function codexAgentsDoctorCheck(enabled: boolean, paths: CodexPaths): DoctorCheck {
+  if (!enabled) {
+    return {
+      id: "codex.paths.agents",
+      status: "skip",
+      message: `Codex agent sync is disabled in settings. Planned user-level path: ${paths.agentsDir}`,
+    };
+  }
+
+  return {
+    id: "codex.paths.agents",
+    status: "pass",
+    message: `Codex agents will sync to user-level TOML files under: ${paths.agentsDir}`,
+  };
 }
 
 function createPluginInstallResult(
@@ -220,6 +733,7 @@ function createPluginInstallResult(
   command: string,
   args: string[],
   message?: string,
+  warnings: string[] = [],
 ): PluginInstallResult {
   const normalizedMessage = message?.trim() || `${command} ${args.join(" ")}`;
   return {
@@ -228,11 +742,39 @@ function createPluginInstallResult(
     command,
     args,
     message: normalizedMessage,
-    warnings: [],
+    warnings,
     errors: status === "failed" ? [normalizedMessage] : [],
   };
 }
 
+function isNotInstalledMessage(message: string | undefined): boolean {
+  return message !== undefined && /(not\s+installed|not\s+found|no\s+installed)/i.test(message);
+}
+
+function extractMarketplaceNameFromSelector(selector: string): string | undefined {
+  const separator = selector.lastIndexOf("@");
+  if (separator <= 0 || separator === selector.length - 1) return undefined;
+  return selector.slice(separator + 1);
+}
+
+function extractPluginNameFromSelector(selector: string): string | undefined {
+  const separator = selector.lastIndexOf("@");
+  const pluginName = separator <= 0 ? selector : selector.slice(0, separator);
+  return pluginName.trim() === "" ? undefined : pluginName;
+}
+
+function isGitMarketplaceSource(source: string): boolean {
+  const trimmed = source.trim();
+  if (/^(https?|ssh|git):\/\//i.test(trimmed)) return true;
+  if (/^git@[^:]+:.+/i.test(trimmed)) return true;
+  return /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+(?:\.git)?$/.test(trimmed);
+}
+
+function isSshGitMarketplaceSource(source: string): boolean {
+  const trimmed = source.trim();
+  return /^ssh:\/\//i.test(trimmed) || /^git@[^:]+:.+/i.test(trimmed);
+}
+
 function isMissingExit(exitCode: number, stderr?: string): boolean {
   if (exitCode === 127) return true;
   const normalized = stderr?.toLowerCase() ?? "";
@@ -248,6 +790,12 @@ function isCommandMissingError(error: unknown): boolean {
   );
 }
 
+function isNotFoundError(error: unknown): boolean {
+  return (
+    error instanceof Error && "code" in error && (error as NodeJS.ErrnoException).code === "ENOENT"
+  );
+}
+
 function describeError(error: unknown): string {
   if (error instanceof Error) {
     return error.message;
@@ -255,3 +803,17 @@ function describeError(error: unknown): string {
 
   return String(error);
 }
+
+function resolveCodexPathsFromHome(): CodexPaths {
+  const home = process.env.HOME;
+
+  if (home === undefined || home.trim() === "") {
+    throw new Error("Cannot resolve Codex paths: HOME is not set");
+  }
+
+  return resolveCodexPaths({ homeDir: home });
+}
+
+function ensureTrailingNewline(content: string): string {
+  return content.endsWith("\n") ? content : `${content}\n`;
+}