helloloop 0.7.2 → 0.8.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "helloloop",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "HelloLoop 的 Claude Code 原生插件元数据，用于多 CLI 宿主分发。",
   "author": {
     "name": "HelloLoop"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "helloloop",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "面向 Codex CLI、Claude Code、Gemini CLI 的多宿主开发工作流插件，Codex 路径为首发与参考实现。",
   "author": {
     "name": "HelloLoop"

package/README.md

@@ -29,10 +29,16 @@
 
 | 宿主 | 安装方式 | 原生入口 | 说明 |
 | --- | --- | --- | --- |
-| `Codex CLI` | `helloloop install` / `helloloop install --host codex` | `$helloloop` / `npx helloloop` | 仅在显式调用时进入 HelloLoop |
+| `Codex CLI` | `helloloop install` / `helloloop install --host codex` | `Codex` 内：`$helloloop`；终端：`npx helloloop` | 仅在显式调用时进入 HelloLoop |
 | `Claude Code` | `helloloop install --host claude` | `/helloloop` | 仅在显式调用时进入 HelloLoop |
 | `Gemini CLI` | `helloloop install --host gemini` | `/helloloop` | 仅在显式调用时进入 HelloLoop |
 
+补充说明：
+
+- `install --host codex` 只会把 `HelloLoop` 注册成 `Codex` 插件，不会把 `helloloop` 写进系统 `PATH`
+- 终端里的 `npx helloloop` 始终是 npm CLI 入口；如果本机未全局安装，首次执行出现 `Need to install the following packages` 属正常行为
+- `Codex` 安装完成后，建议重启 `Codex` 或新开一个会话，再检查 `$helloloop`
+
 ## 最短使用方式
 
 推荐先记住下面四种：
@@ -156,13 +162,10 @@ npx helloloop
 
 `HelloLoop` 会先明确执行引擎，再快速扫描当前目录：
 
-- 当前目录本身就是项目仓库或开发文档目录时，直接进入分析
-- 当前目录更像工作区时，优先利用顶层文档，再提示选择候选项目目录
-- 当前目录没有明确开发文档时，不会直接报错，而是先列出：
-  - 顶层文档文件
-  - 顶层目录
-  - 疑似项目目录
-  然后再询问开发文档路径
+- 当前目录本身就是开发文档目录时，会先尝试从文档反推项目目录
+- 当前目录看起来像普通项目目录时，默认直接把当前目录作为项目目录
+- 当前目录更像工作区或用户主目录时，才会额外询问项目目录
+- 如果当前项目目录下没有明确开发文档，会只提示补充“开发文档”这一项，并说明已检查的常见位置
 
 ### 2. 项目路径只问一次
 
@@ -173,11 +176,22 @@ npx helloloop
 
 不会再额外追问一个“新项目路径”。
 
-### 3. 文档和项目缺一不可时会停下询问
+### 3. 缺什么就只问什么
+
+正常情况下只需要两项信息：
+
+- 项目目录
+- 开发文档
+
+其中：
+
+- 项目目录默认优先使用当前打开的目录
+- 当前目录明显不是项目目录时，才会额外询问项目目录
+- 开发文档缺失时，只会询问开发文档
 
 以下情况不会硬猜：
 
-- 给了开发文档，但无法定位项目仓库
+- 给了开发文档，但仍无法定位项目目录
 - 给了项目路径，但无法定位开发文档
 - 同时出现多个冲突的文档路径或项目路径
 
@@ -217,7 +231,7 @@ npx helloloop --rebuild-existing
 - 执行引擎
 - 需求语义理解
 - 项目匹配判断
-- 目标仓库
+- 项目目录
 - 开发文档
 - 当前进度
 - 已实现事项
@@ -290,11 +304,12 @@ npx helloloop install --host all --force
 说明：
 
 - `--force` 会清理当前宿主里已有安装残留的 `helloloop` 目录后再重装
-- `Codex` 会刷新插件目录和 marketplace 条目
+- `Codex` 会刷新 home 根下的插件源码目录、已安装缓存、`config.toml` 启用项和 marketplace 条目
 - `Claude` 会刷新 marketplace、缓存插件目录，以及 `settings.json` / `known_marketplaces.json` / `installed_plugins.json` 中的 `helloloop` 条目
 - `Gemini` 会刷新 `extensions/helloloop/`，不会动同目录下其他扩展
 - 安装 / 升级 / 重装时，会同步校准 `~/.helloloop/settings.json` 的当前版本结构：补齐缺失项、清理未知项、保留已知项现有值
-- 如果 `~/.helloloop/settings.json` 不是合法 JSON，会先备份原文件，再按当前版本结构重建
+- 如果 `~/.helloloop/settings.json` 被确认不是合法 JSON，会先备份原文件，再按当前版本结构重建
+- 如果只是首次读取时出现瞬时异常，但重读后内容合法，则不会误生成备份文件
 - 如果宿主自己的配置 JSON（如 `Codex marketplace.json`、`Claude settings.json`、`known_marketplaces.json`、`installed_plugins.json`）本身已损坏，`HelloLoop` 会先明确报错并停止，不会先清理现有安装再失败
 
 ### 卸载
@@ -333,7 +348,7 @@ $helloloop
 helloloop:helloloop
 ```
 
-在 `Codex` 中也可以直接执行：
+在终端里（包括 `Codex` 打开的内置终端）也可以直接执行：
 
 ```bash
 npx helloloop
@@ -412,8 +427,10 @@ npx helloloop doctor --host all --codex-home <CODEX_HOME> --claude-home <CLAUDE_
 
 ### `Codex CLI`
 
-- 插件目录：`~/.codex/plugins/helloloop/`
-- 注册文件：`~/.codex/.agents/plugins/marketplace.json`
+- 插件源码目录：`~/plugins/helloloop/`
+- 已安装缓存：`~/.codex/plugins/cache/local-plugins/helloloop/local/`
+- marketplace：`~/.agents/plugins/marketplace.json`
+- 启用配置：`~/.codex/config.toml`
 
 ### `Claude Code`
 
@@ -442,7 +459,8 @@ npx helloloop doctor --host all --codex-home <CODEX_HOME> --claude-home <CLAUDE_
 
 - 这里不保存项目 backlog、状态、运行记录
 - 安装 / 升级 / 重装时，会对 `settings.json` 做结构校准，但不会校验或篡改你已存在的已知项内容
-- 如果 `settings.json` 非法，会先备份，再重建为当前版本结构
+- 只有在 `settings.json` 被确认非法时，才会先备份，再重建为当前版本结构
+- 如果只是读取瞬时异常、重读后合法，不会误生成 `.bak`
 
 ## `.helloloop/` 状态目录
 

package/hosts/claude/marketplace/plugins/helloloop/commands/helloloop.md

@@ -12,7 +12,7 @@ argument-hint: [PATH]
 3. 如果用户在命令后提供了 `$ARGUMENTS`，必须同时保留其中的显式路径和自然语言补充要求，不要依赖固定关键词硬编码决策。
 3. 自动识别目标仓库与开发文档，并先分析“当前代码做到哪里了”“与文档目标是否存在偏差”“当前项目与文档目标是否匹配”。
 4. 当前宿主是 `Claude`；如果用户未明确指定执行引擎，必须先确认本轮引擎，`Claude` 只可作为推荐项，不允许自动选中；如果用户明确要求改用 `Codex` 或 `Gemini`，必须先确认，不允许静默切换。
-5. 如果当前目录没有明确开发文档，先展示顶层文档文件、顶层目录和疑似项目目录，再询问用户开发文档路径。
+5. 如果当前目录看起来像普通项目目录，默认直接把当前目录当作项目目录；只有明显是工作区或用户主目录时才额外询问项目目录。如果当前项目目录里没有明确开发文档，只补充询问开发文档，不展示内部扫描分类。
 6. 项目路径对外只有一个概念；如果用户输入的项目路径不存在，就把它视为准备创建的新项目目录，不要再单独追问“新项目路径”。
 7. 在目标仓库根目录创建或刷新 `.helloloop/`，至少维护 `backlog.json`、`project.json`、`status.json`、`STATE.md` 与 `runs/`。
 8. 如果用户给了开发文档但无法定位项目仓库，或者给了项目路径但无法定位开发文档，必须停下来询问用户，而不是猜测。
@@ -22,7 +22,7 @@ argument-hint: [PATH]
    - 本次命令补充输入
    - 需求语义理解
    - 项目匹配判断
-   - 目标仓库
+   - 项目目录
    - 开发文档
    - 当前进度
    - 已实现事项

package/hosts/claude/marketplace/plugins/helloloop/skills/helloloop/SKILL.md

@@ -21,7 +21,8 @@ description: 仅当用户显式调用 `/helloloop`，或明确要求使用 Hello
 
 - 未显式调用 `helloloop` 且用户也没有明确要求使用 HelloLoop 时，不允许接管普通 Claude 会话。
 - 如果缺少目标仓库或开发文档，必须停下来询问用户。
-- 如果当前目录没有明确开发文档，应先展示顶层文档文件、顶层目录和疑似项目目录，再询问文档路径。
+- 如果当前目录看起来像普通项目目录，默认直接把当前目录当作项目目录；只有明显是工作区或用户主目录时才额外询问项目目录。
+- 如果当前项目目录里没有明确开发文档，只补充询问开发文档，不展示内部扫描分类。
 - 项目路径对外只有一个概念；如果用户提供的项目路径不存在，直接按新项目路径处理，不要再追问“新项目路径”。
 - 如果当前项目与开发文档目标明显冲突，必须先确认是继续现有项目、清理后重建，还是取消。
 - 如果当前引擎在运行中遇到 400、鉴权、余额、429、5xx、网络抖动、流中断或长时间卡死，必须优先按无人值守策略做同引擎“健康探测 + 条件恢复”，不要中途停下来询问用户，也不要自动切换引擎。

package/hosts/gemini/extension/GEMINI.md

@@ -11,7 +11,7 @@
 0. 仅在用户显式调用 `/helloloop`，或明确要求使用 HelloLoop 时才介入；不要接管普通 Gemini 会话
 1. 自动识别项目仓库与开发文档
 2. 如果用户未明确指定执行引擎，先确认本轮引擎；`Gemini` 只作为推荐项，不自动选中；如果用户明确要求改用 `Codex` / `Claude`，先确认再切换
-3. 如果当前目录没有明确开发文档，先展示顶层文档文件、顶层目录和疑似项目目录，再询问文档路径
+3. 如果当前目录看起来像普通项目目录，默认直接把当前目录当作项目目录；只有明显是工作区或用户主目录时才额外询问项目目录。如果当前项目目录里没有明确开发文档，只补充询问开发文档
 4. 项目路径对外只有一个概念；若用户输入的路径不存在，直接按新项目路径处理
 5. 分析当前代码与开发文档的差距，并判断当前项目与文档目标是否匹配
 6. 在目标仓库根目录创建或刷新 `.helloloop/`

package/hosts/gemini/extension/commands/helloloop.toml

@@ -7,7 +7,7 @@ prompt = """
 1. 只有当用户显式调用 `/helloloop`，或明确要求“使用 HelloLoop / 走 HelloLoop 流程”时，才进入当前工作流；不要接管普通 Gemini 会话。
 2. 自动识别目标仓库与开发文档；如果用户在命令后提供了参数，必须同时保留其中的显式路径和自然语言补充要求，不要靠固定关键词硬编码判断。
 3. 当前宿主是 `Gemini`；如果用户未明确指定执行引擎，必须先确认本轮引擎，`Gemini` 只可作为推荐项，不允许自动选中；如果用户明确要求改用 `Codex` 或 `Claude`，必须先确认，不允许静默切换。
-3. 如果当前目录没有明确开发文档，应先展示顶层文档文件、顶层目录和疑似项目目录，再询问用户开发文档路径。
+3. 如果当前目录看起来像普通项目目录，默认直接把当前目录当作项目目录；只有明显是工作区或用户主目录时才额外询问项目目录。如果当前项目目录里没有明确开发文档，只补充询问开发文档，不展示内部扫描分类。
 4. 项目路径对外只有一个概念；如果用户给出的项目路径不存在，直接按新项目路径处理，不要再单独追问“新项目路径”。
 5. 分析当前代码与开发文档之间的真实进度和偏差，并判断当前项目目录与开发文档目标是否匹配。
 6. 在目标仓库根目录创建或刷新 `.helloloop/`，至少维护 `backlog.json`、`project.json`、`status.json`、`STATE.md` 与 `runs/`。
@@ -17,7 +17,7 @@ prompt = """
    - 执行引擎
    - 需求语义理解
    - 项目匹配判断
-   - 目标仓库
+   - 项目目录
    - 开发文档
    - 当前进度
    - 已实现事项

package/hosts/gemini/extension/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "helloloop",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "HelloLoop 的 Gemini CLI 原生扩展，用于按开发文档接续推进项目开发。",
   "contextFileName": "GEMINI.md",
   "excludeTools": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "helloloop",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "面向 Codex CLI、Claude Code、Gemini CLI 的多宿主开发工作流插件",
   "author": "HelloLoop",
   "license": "Apache-2.0",

package/skills/helloloop/SKILL.md

@@ -39,7 +39,8 @@ description: 仅当用户显式调用 `$helloloop` / `#helloloop` / `helloloop:h
 
 ## 路径发现与提问规则
 
-- 如果当前目录没有自动识别到明确开发文档，应先展示顶层文档文件、顶层目录和疑似项目目录，再要求用户补充文档路径。
+- 如果当前目录看起来像普通项目目录，默认直接把当前目录当作项目目录；只有明显是工作区或用户主目录时才额外询问项目目录。
+- 如果当前项目目录里没有自动识别到明确开发文档，只补充询问开发文档，不展示“顶层文档文件 / 顶层目录 / 疑似项目目录”之类内部扫描分类。
 - 项目路径对外只有一个概念，不要单独追问“新项目路径”。
 - 如果用户输入的项目路径不存在，应直接把它视为准备创建的新项目目录。
 - 如果自动发现同时出现多个冲突的文档路径或项目路径，不允许替用户猜测，必须停下来确认。

package/src/analyze_confirmation.mjs

@@ -83,11 +83,11 @@ function renderResolutionLines(discovery, context, docsDisplay) {
     `- 文档来源：${docsResolution?.sourceLabel || "自动判断"}`,
     `- 文档把握：${docsResolution?.confidenceLabel || "中"}`,
     `- 文档依据：${docsBasis}`,
-    `- 目标仓库：${context.repoRoot.replaceAll("\\", "/")}`,
+    `- 项目目录：${context.repoRoot.replaceAll("\\", "/")}`,
     `- 项目状态：${repoState}`,
-    `- 仓库来源：${repoResolution?.sourceLabel || "自动判断"}`,
-    `- 仓库把握：${repoResolution?.confidenceLabel || "中"}`,
-    `- 仓库依据：${repoBasis}`,
+    `- 目录来源：${repoResolution?.sourceLabel || "自动判断"}`,
+    `- 目录把握：${repoResolution?.confidenceLabel || "中"}`,
+    `- 目录依据：${repoBasis}`,
   ];
 }
 

package/src/cli_render.mjs

@@ -21,9 +21,15 @@ export function renderInstallSummary(result) {
 
   for (const item of result.installedHosts) {
     lines.push(`- ${item.displayName}：${item.targetRoot}`);
+    if (item.installedRoot) {
+      lines.push(`  installed：${item.installedRoot}`);
+    }
     if (item.marketplaceFile) {
       lines.push(`  marketplace：${item.marketplaceFile}`);
     }
+    if (item.configFile) {
+      lines.push(`  config：${item.configFile}`);
+    }
     if (item.settingsFile) {
       lines.push(`  settings：${item.settingsFile}`);
     }
@@ -47,9 +53,10 @@ export function renderInstallSummary(result) {
 
   lines.push("");
   lines.push("使用入口：");
-  lines.push("- Codex：`$helloloop` / `npx helloloop`");
-  lines.push("- Claude：`/helloloop`");
-  lines.push("- Gemini：`/helloloop`");
+  lines.push("- 终端 CLI：`npx helloloop`");
+  lines.push("- Codex 技能：`$helloloop`");
+  lines.push("- Claude 指令：`/helloloop`");
+  lines.push("- Gemini 指令：`/helloloop`");
   lines.push("");
   lines.push(renderFollowupExamples());
   return lines.join("\n");
@@ -64,6 +71,9 @@ export function renderUninstallSummary(result) {
     if (item.marketplaceFile) {
       lines.push(`  marketplace：${item.marketplaceFile}`);
     }
+    if (item.configFile) {
+      lines.push(`  config：${item.configFile}`);
+    }
     if (item.settingsFile) {
       lines.push(`  settings：${item.settingsFile}`);
     }

package/src/cli_support.mjs

@@ -2,7 +2,8 @@ import { spawnSync } from "node:child_process";
 import path from "node:path";
 
 import { analyzeExecution, summarizeBacklog } from "./backlog.mjs";
-import { fileExists, readJson } from "./common.mjs";
+import { fileExists, readJson, readTextIfExists } from "./common.mjs";
+import { resolveCodexLocalRoot } from "./install_shared.mjs";
 import { createPromptSession } from "./prompt_session.mjs";
 import { resolveCliInvocation, resolveCodexInvocation } from "./shell_invocation.mjs";
 
@@ -133,15 +134,37 @@ function normalizeDoctorHosts(hostOption) {
 function collectCodexDoctorChecks(context, options = {}) {
   const checks = collectDoctorChecks(context, options);
   if (options.codexHome) {
+    const codexLocalRoot = resolveCodexLocalRoot(options.codexHome);
+    const codexConfigFile = path.join(options.codexHome, "config.toml");
+    const codexInstalledPluginFile = path.join(
+      options.codexHome,
+      "plugins",
+      "cache",
+      "local-plugins",
+      "helloloop",
+      "local",
+      ".codex-plugin",
+      "plugin.json",
+    );
+    checks.push({
+      name: "codex plugin source",
+      ok: fileExists(path.join(codexLocalRoot, "plugins", "helloloop", ".codex-plugin", "plugin.json")),
+      detail: path.join(codexLocalRoot, "plugins", "helloloop", ".codex-plugin", "plugin.json"),
+    });
     checks.push({
       name: "codex installed plugin",
-      ok: fileExists(path.join(options.codexHome, "plugins", "helloloop", ".codex-plugin", "plugin.json")),
-      detail: path.join(options.codexHome, "plugins", "helloloop", ".codex-plugin", "plugin.json"),
+      ok: fileExists(codexInstalledPluginFile),
+      detail: codexInstalledPluginFile,
     });
     checks.push({
       name: "codex marketplace",
-      ok: fileExists(path.join(options.codexHome, ".agents", "plugins", "marketplace.json")),
-      detail: path.join(options.codexHome, ".agents", "plugins", "marketplace.json"),
+      ok: fileExists(path.join(codexLocalRoot, ".agents", "plugins", "marketplace.json")),
+      detail: path.join(codexLocalRoot, ".agents", "plugins", "marketplace.json"),
+    });
+    checks.push({
+      name: "codex plugin config",
+      ok: readTextIfExists(codexConfigFile, "").includes('[plugins."helloloop@local-plugins"]'),
+      detail: codexConfigFile,
     });
   }
   return checks;

package/src/discovery.mjs

@@ -47,7 +47,8 @@ const DOCS_SOURCE_META = {
   cwd_docs: { label: "当前目录", confidence: "medium" },
   workspace_single_doc: { label: "工作区唯一文档候选", confidence: "medium" },
   existing_state: { label: "已有 .helloloop 配置", confidence: "medium" },
-  repo_docs: { label: "仓库 docs 目录", confidence: "medium" },
+  repo_docs_dir: { label: "项目目录 docs 目录", confidence: "medium" },
+  repo_doc_file: { label: "项目目录顶层文档", confidence: "medium" },
 };
 
 function isImplicitHomeDirectory(targetPath) {
@@ -200,7 +201,12 @@ export function discoverWorkspace(options = {}) {
       repoSource = "explicit_input";
       pushBasis(repoBasis, "目标项目来自命令中传入的单一路径。");
     }
-    if (classified.kind === "workspace" || classified.kind === "directory") {
+    if (classified.kind === "directory") {
+      repoRoot = classified.absolutePath;
+      repoSource = "explicit_input";
+      pushBasis(repoBasis, "目标项目来自命令中传入的目录路径。");
+    }
+    if (classified.kind === "workspace") {
       workspaceRoot = classified.absolutePath;
     }
   }
@@ -223,8 +229,12 @@ export function discoverWorkspace(options = {}) {
         repoRoot = cwdClassified.absolutePath;
         repoSource = "cwd_repo";
         pushBasis(repoBasis, "当前终端目录本身就是项目仓库。");
-      } else if (cwdClassified.kind === "workspace" || cwdClassified.kind === "directory") {
+      } else if (cwdClassified.kind === "workspace") {
         workspaceRoot = cwdClassified.absolutePath;
+      } else if (cwdClassified.kind === "directory") {
+        repoRoot = cwdClassified.absolutePath;
+        repoSource = "cwd_repo";
+        pushBasis(repoBasis, "当前终端目录默认作为项目目录。");
       } else if (looksLikeProjectRoot(cwd)) {
         repoRoot = cwd;
         repoSource = "cwd_repo";
@@ -233,6 +243,25 @@ export function discoverWorkspace(options = {}) {
     }
   }
 
+  if (!repoRoot && docsEntries.length && !treatCwdAsHomeWorkspace) {
+    const cwdClassified = classifyExplicitPath(cwd);
+    if (cwdClassified.kind === "repo") {
+      repoRoot = cwdClassified.absolutePath;
+      repoSource = "cwd_repo";
+      pushBasis(repoBasis, "当前终端目录本身就是项目仓库。");
+    } else if (cwdClassified.kind === "directory") {
+      repoRoot = cwdClassified.absolutePath;
+      repoSource = "cwd_repo";
+      pushBasis(repoBasis, "当前终端目录默认作为项目目录。");
+    } else if (cwdClassified.kind === "workspace") {
+      workspaceRoot = workspaceRoot || cwdClassified.absolutePath;
+    } else if (looksLikeProjectRoot(cwd)) {
+      repoRoot = cwd;
+      repoSource = "cwd_repo";
+      pushBasis(repoBasis, "当前终端目录具备项目仓库特征。");
+    }
+  }
+
   if (!repoRoot && !docsEntries.length && workspaceRoot) {
     const workspace = inspectWorkspaceDirectory(workspaceRoot);
     docCandidates = workspace.docCandidates;
@@ -312,8 +341,10 @@ export function discoverWorkspace(options = {}) {
       } else if (inferred.source === "cwd") {
         docsSource = "cwd_docs";
         pushBasis(docsBasis, "当前终端目录本身就是开发文档目录或文件。");
-      } else if (inferred.source === "repo_docs") {
-        pushBasis(docsBasis, "已使用目标仓库中的 `docs/` 目录作为默认开发文档入口。");
+      } else if (inferred.source === "repo_docs_dir") {
+        pushBasis(docsBasis, "已使用项目目录中的 `docs/` 目录作为默认开发文档入口。");
+      } else if (inferred.source === "repo_doc_file") {
+        pushBasis(docsBasis, "已使用项目目录中的顶层文档文件作为默认开发文档入口。");
       }
     }
   }
@@ -384,6 +415,9 @@ export function resolveRepoRoot(options = {}) {
     }
     return { ok: false, message: renderMissingRepoMessage([classified.absolutePath], inferred.candidates) };
   }
+  if (classified.kind === "directory") {
+    return { ok: true, repoRoot: classified.absolutePath };
+  }
 
   if (!explicitRepoRoot && !explicitInputPath && isImplicitHomeDirectory(cwd)) {
     return {
@@ -401,8 +435,5 @@ export function resolveRepoRoot(options = {}) {
     return { ok: true, repoRoot: cwd };
   }
 
-  return {
-    ok: false,
-    message: "当前目录不是项目仓库。请切到项目目录，或传入一个项目路径/开发文档路径。",
-  };
+  return { ok: true, repoRoot: cwd };
 }

package/src/discovery_inference.mjs

@@ -223,40 +223,56 @@ export function inferDocsForRepo(repoRoot, cwd, configDirName) {
     };
   }
 
-  const repoDocsCandidates = uniquePaths([
+  const repoDocsDirectories = uniquePaths([
     path.join(repoRoot, "docs"),
     path.join(repoRoot, "Docs"),
+    path.join(repoRoot, "doc"),
+    path.join(repoRoot, "Doc"),
+    path.join(repoRoot, "documentation"),
+    path.join(repoRoot, "Documentation"),
   ].filter((candidate) => isDocsDirectory(candidate)));
 
-  if (repoDocsCandidates.length === 1) {
+  const repoRootDocFiles = listDocFilesInDirectory(repoRoot)
+    .filter((candidate) => path.basename(candidate).toLowerCase() !== "agents.md");
+  const candidates = uniquePaths([...repoDocsDirectories, ...repoRootDocFiles]);
+
+  if (repoDocsDirectories.length === 1) {
+    return {
+      docsEntries: [normalizeForRepo(repoRoot, repoDocsDirectories[0])],
+      source: "repo_docs_dir",
+      candidates,
+    };
+  }
+
+  if (!repoDocsDirectories.length && repoRootDocFiles.length === 1) {
     return {
-      docsEntries: [normalizeForRepo(repoRoot, repoDocsCandidates[0])],
-      source: "repo_docs",
-      candidates: repoDocsCandidates,
+      docsEntries: [normalizeForRepo(repoRoot, repoRootDocFiles[0])],
+      source: "repo_doc_file",
+      candidates,
     };
   }
 
   return {
     docsEntries: [],
     source: "",
-    candidates: repoDocsCandidates,
+    candidates,
   };
 }
 
 export function renderMissingRepoMessage(docEntries, candidates) {
   return [
-    "无法自动确定要开发的项目仓库路径。",
+    "无法自动确定要开发的项目目录。",
     docEntries.length ? `已找到开发文档：${docEntries.map((item) => item.replaceAll("\\", "/")).join("，")}` : "",
-    ...formatCandidates("候选项目：", candidates),
+    ...formatCandidates("候选项目目录：", candidates),
     "可重新运行 `npx helloloop` 后按提示选择，或显式补充项目路径，例如：",
-    "npx helloloop --repo <PROJECT_ROOT>",
+    "npx helloloop --repo <PROJECT_DIR>",
   ].filter(Boolean).join("\n");
 }
 
 export function renderMissingDocsMessage(repoRoot, candidates = []) {
   return [
-    "无法自动确定开发文档位置。",
-    `已找到项目仓库：${repoRoot.replaceAll("\\", "/")}`,
+    "未找到开发文档。",
+    `当前项目目录：${repoRoot.replaceAll("\\", "/")}`,
     ...formatCandidates("候选开发文档：", candidates),
     "可重新运行 `npx helloloop` 后按提示选择，或显式补充开发文档路径，例如：",
     "npx helloloop --docs <DOCS_PATH>",

package/src/discovery_prompt.mjs

@@ -1,12 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 
-import {
-  listDocFilesInDirectory,
-  listProjectCandidatesInDirectory,
-  pathExists,
-  resolveAbsolute,
-} from "./discovery_paths.mjs";
+import { pathExists, resolveAbsolute } from "./discovery_paths.mjs";
 import { createPromptSession } from "./prompt_session.mjs";
 
 function toDisplayPath(targetPath) {
@@ -31,63 +26,21 @@ function summarizeList(items, options = {}) {
   return lines;
 }
 
-function collectDirectoryOverview(rootPath) {
-  if (!pathExists(rootPath) || !fs.statSync(rootPath).isDirectory()) {
-    return {
-      rootPath,
-      directories: [],
-      docFiles: [],
-      repoCandidates: [],
-    };
-  }
-
-  const entries = fs.readdirSync(rootPath, { withFileTypes: true });
-  return {
-    rootPath,
-    directories: entries
-      .filter((entry) => entry.isDirectory())
-      .map((entry) => entry.name)
-      .sort((left, right) => left.localeCompare(right, "zh-CN")),
-    docFiles: listDocFilesInDirectory(rootPath)
-      .map((filePath) => path.basename(filePath))
-      .sort((left, right) => left.localeCompare(right, "zh-CN")),
-    repoCandidates: listProjectCandidatesInDirectory(rootPath)
-      .map((directoryPath) => path.basename(directoryPath))
-      .sort((left, right) => left.localeCompare(right, "zh-CN")),
-  };
-}
-
-function renderDirectoryOverview(title, overview) {
-  return [
-    title,
-    `扫描目录：${toDisplayPath(overview.rootPath)}`,
-    "",
-    "顶层文档文件：",
-    ...summarizeList(overview.docFiles),
-    "",
-    "顶层目录：",
-    ...summarizeList(overview.directories),
-    "",
-    "疑似项目目录：",
-    ...summarizeList(overview.repoCandidates),
-  ].join("\n");
-}
-
-function renderExistingChoices(title, candidates) {
+function renderExistingChoices(title, candidates, footer = "请输入编号；也可以直接输入本地路径；直接回车取消。") {
   return [
     title,
     ...candidates.map((item, index) => `${index + 1}. ${toDisplayPath(item)}`),
     "",
-    "请输入编号；也可以直接输入本地路径；直接回车取消。",
+    footer,
   ].join("\n");
 }
 
-async function promptForExistingPathSelection(readline, title, candidates, cwd, preface = "") {
-  if (preface) {
-    console.log(preface);
+async function promptForExistingPathSelection(readline, title, candidates, cwd, options = {}) {
+  if (options.preface) {
+    console.log(options.preface);
     console.log("");
   }
-  console.log(renderExistingChoices(title, candidates));
+  console.log(renderExistingChoices(title, candidates, options.footer));
   while (true) {
     const answer = String(await readline.question("> ") || "").trim();
     if (!answer) {
@@ -104,26 +57,91 @@ async function promptForExistingPathSelection(readline, title, candidates, cwd,
       return maybePath;
     }
 
-    console.log("输入无效，请输入候选编号或一个存在的本地路径。");
+    console.log(options.invalidMessage || "输入无效，请输入候选编号或一个存在的本地路径。");
+  }
+}
+
+function createCommonDocsPathHints(repoRoot) {
+  return [
+    "./docs",
+    "./doc",
+    "./documentation",
+    "./README.md",
+    "./PRD.md",
+    "./requirements.md",
+    "./spec.md",
+    "./design.md",
+    "./plan.md",
+    "./roadmap.md",
+  ].map((entry) => {
+    if (!repoRoot) {
+      return entry;
+    }
+    return toDisplayPath(path.join(repoRoot, entry.replace(/^\.\//, "")));
+  });
+}
+
+function renderDocsPromptPreface(discovery, cwd) {
+  const repoRoot = discovery.repoRoot || "";
+  const lines = [];
+
+  if (repoRoot) {
+    lines.push("未找到开发文档。");
+    lines.push(`项目目录：${toDisplayPath(repoRoot)}`);
+    return lines.join("\n");
+  }
+
+  if (discovery.workspaceRoot) {
+    lines.push("当前目录更像工作区，暂时不直接作为项目目录。");
+    lines.push(`当前目录：${toDisplayPath(discovery.workspaceRoot)}`);
+    if (Array.isArray(discovery.repoCandidates) && discovery.repoCandidates.length) {
+      lines.push(`候选项目目录：${discovery.repoCandidates.length} 个，稍后再确认。`);
+    }
+    return lines.join("\n");
+  }
+
+  lines.push("未找到开发文档。");
+  lines.push(`当前目录：${toDisplayPath(cwd)}`);
+  return lines.join("\n");
+}
+
+function renderRepoPromptPreface(discovery, cwd) {
+  const lines = [];
+  if (discovery.workspaceRoot) {
+    lines.push("当前目录更像工作区，不能直接作为项目目录。");
+    lines.push(`当前目录：${toDisplayPath(discovery.workspaceRoot)}`);
+  } else {
+    lines.push("还需要确认项目目录。");
+    lines.push(`当前目录：${toDisplayPath(cwd)}`);
   }
+
+  if (Array.isArray(discovery.docsEntries) && discovery.docsEntries.length) {
+    lines.push(`开发文档：${discovery.docsEntries.map((item) => toDisplayPath(item)).join("，")}`);
+  }
+  return lines.join("\n");
 }
 
 async function promptForDocsPath(readline, discovery, cwd) {
   const docChoices = Array.isArray(discovery.docCandidates) ? discovery.docCandidates : [];
-  const scanRoot = discovery.workspaceRoot || discovery.repoRoot || cwd;
-  const overview = collectDirectoryOverview(scanRoot);
-  const title = docChoices.length
-    ? "请选择开发文档来源："
-    : "未自动识别到明确的开发文档。请输入开发文档目录或文件路径：";
-  const preface = renderDirectoryOverview("当前目录顶层概览", overview);
+  const repoRoot = discovery.repoRoot || "";
+  const preface = renderDocsPromptPreface(discovery, cwd);
 
   if (docChoices.length) {
-    return promptForExistingPathSelection(readline, title, docChoices, cwd, preface);
+    return promptForExistingPathSelection(readline, "请选择开发文档：", docChoices, cwd, {
+      preface,
+      footer: "请输入编号；也可以直接输入已存在的本地路径；直接回车取消。",
+      invalidMessage: "输入无效，请输入候选编号或一个已存在的开发文档路径。",
+    });
   }
 
   console.log(preface);
   console.log("");
-  console.log(title);
+  if (repoRoot) {
+    console.log("已检查这些常见位置：");
+    console.log(summarizeList(createCommonDocsPathHints(repoRoot)).join("\n"));
+    console.log("");
+  }
+  console.log("请输入开发文档路径（文件或目录）：");
   console.log("可直接输入当前目录下的相对路径或绝对路径；直接回车取消。");
   while (true) {
     const answer = String(await readline.question("> ") || "").trim();
@@ -142,21 +160,19 @@ async function promptForDocsPath(readline, discovery, cwd) {
 
 async function promptForRepoPath(readline, discovery, cwd) {
   const repoChoices = Array.isArray(discovery.repoCandidates) ? discovery.repoCandidates : [];
-  const scanRoot = discovery.workspaceRoot
-    || (Array.isArray(discovery.docsEntries) && discovery.docsEntries.length
-      ? path.dirname(discovery.docsEntries[0])
-      : "")
-    || cwd;
-  const overview = collectDirectoryOverview(scanRoot);
-  const preface = renderDirectoryOverview("当前目录顶层概览", overview);
+  const preface = renderRepoPromptPreface(discovery, cwd);
   const title = repoChoices.length
-    ? "请选择目标项目仓库："
-    : "请输入要开发的项目路径：";
+    ? "请选择要开发的项目目录："
+    : "请输入要开发的项目目录：";
+
   console.log(preface);
   console.log("");
   if (repoChoices.length) {
-    console.log(renderExistingChoices(title, repoChoices));
-    console.log("也可以直接输入项目路径；如果这是新项目，可输入准备创建的新目录路径。");
+    console.log(renderExistingChoices(
+      title,
+      repoChoices,
+      "请输入编号；也可以直接输入项目路径；如果这是新项目，可输入准备创建的新目录路径；直接回车取消。",
+    ));
   } else {
     console.log(title);
     console.log("如果这是新项目，可直接输入准备创建的新目录路径；直接回车取消。");
@@ -258,9 +274,9 @@ export async function resolveDiscoveryFailureInteractively(
         : "interactive";
       changed = true;
       if (selectedRepo.allowNewRepoRoot) {
-        console.log(`已指定项目路径（当前不存在，将按新项目创建）：${toDisplayPath(selectedRepo.repoRoot)}`);
+        console.log(`已指定项目目录（当前不存在，将按新项目创建）：${toDisplayPath(selectedRepo.repoRoot)}`);
       } else {
-        console.log(`已选择项目仓库：${toDisplayPath(selectedRepo.repoRoot)}`);
+        console.log(`已选择项目目录：${toDisplayPath(selectedRepo.repoRoot)}`);
       }
       console.log("");
     }

package/src/engine_selection_settings.mjs

@@ -148,6 +148,10 @@ export function saveUserSettings(settings, options = {}) {
   });
 }
 
+function tryParseUserSettingsText(text) {
+  return JSON.parse(String(text || ""));
+}
+
 export function syncUserSettingsFile(options = {}) {
   const settingsFile = resolveUserSettingsFile(options.userSettingsFile);
   const defaults = defaultUserSettings();
@@ -161,12 +165,33 @@ export function syncUserSettingsFile(options = {}) {
     };
   }
 
-  let parsed;
+  const firstText = readText(settingsFile);
   try {
-    parsed = readJson(settingsFile);
+    const parsed = tryParseUserSettingsText(firstText);
+    writeJson(settingsFile, syncUserSettingsShape(parsed));
+    return {
+      settingsFile,
+      action: "synced",
+      backupFile: "",
+    };
   } catch (error) {
+    const retryText = readText(settingsFile);
+    if (retryText !== firstText) {
+      try {
+        const parsed = tryParseUserSettingsText(retryText);
+        writeJson(settingsFile, syncUserSettingsShape(parsed));
+        return {
+          settingsFile,
+          action: "synced",
+          backupFile: "",
+          recoveredAfterRetry: true,
+        };
+      } catch {
+      }
+    }
+
     const backupFile = `${settingsFile}.invalid-${timestampForFile()}.bak`;
-    writeText(backupFile, readText(settingsFile));
+    writeText(backupFile, retryText);
     writeJson(settingsFile, defaults);
     return {
       settingsFile,
@@ -175,11 +200,4 @@ export function syncUserSettingsFile(options = {}) {
       error: String(error?.message || error || ""),
     };
   }
-
-  writeJson(settingsFile, syncUserSettingsShape(parsed));
-  return {
-    settingsFile,
-    action: "synced",
-    backupFile: "",
-  };
 }

package/src/install_codex.mjs

@@ -1,6 +1,6 @@
 import path from "node:path";
 
-import { ensureDir, fileExists, readJson, writeJson } from "./common.mjs";
+import { ensureDir, fileExists, readJson, readTextIfExists, writeJson, writeText } from "./common.mjs";
 import {
   assertPathInside,
   codexBundleEntries,
@@ -8,15 +8,75 @@ import {
   readExistingJsonOrThrow,
   removePathIfExists,
   removeTargetIfNeeded,
+  resolveCodexLocalRoot,
   resolveHomeDir,
 } from "./install_shared.mjs";
 
+const CODEX_MARKETPLACE_NAME = "local-plugins";
+const CODEX_PLUGIN_NAME = "helloloop";
+const CODEX_PLUGIN_KEY = `${CODEX_PLUGIN_NAME}@${CODEX_MARKETPLACE_NAME}`;
+const CODEX_PLUGIN_CONFIG_HEADER = `[plugins."${CODEX_PLUGIN_KEY}"]`;
+const CODEX_PLUGIN_CONFIG_BLOCK = `${CODEX_PLUGIN_CONFIG_HEADER}\nenabled = true`;
+
+function isTomlTableHeader(line) {
+  const trimmed = String(line || "").trim();
+  return trimmed.startsWith("[") && trimmed.endsWith("]");
+}
+
+function stripTomlSection(text, headerLine) {
+  const lines = String(text || "").replaceAll("\r\n", "\n").split("\n");
+  const kept = [];
+  let removed = false;
+
+  for (let index = 0; index < lines.length;) {
+    if (lines[index].trim() === headerLine) {
+      removed = true;
+      index += 1;
+      while (index < lines.length && !isTomlTableHeader(lines[index])) {
+        index += 1;
+      }
+      continue;
+    }
+
+    kept.push(lines[index]);
+    index += 1;
+  }
+
+  const nextText = kept.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd();
+  return {
+    removed,
+    text: nextText ? `${nextText}\n` : "",
+  };
+}
+
+function upsertCodexPluginConfig(configFile) {
+  const existingText = readTextIfExists(configFile, "");
+  const stripped = stripTomlSection(existingText, CODEX_PLUGIN_CONFIG_HEADER).text.trimEnd();
+  const nextText = stripped
+    ? `${stripped}\n\n${CODEX_PLUGIN_CONFIG_BLOCK}\n`
+    : `${CODEX_PLUGIN_CONFIG_BLOCK}\n`;
+  writeText(configFile, nextText);
+}
+
+function removeCodexPluginConfig(configFile) {
+  if (!fileExists(configFile)) {
+    return false;
+  }
+
+  const existingText = readTextIfExists(configFile, "");
+  const result = stripTomlSection(existingText, CODEX_PLUGIN_CONFIG_HEADER);
+  if (result.removed) {
+    writeText(configFile, result.text);
+  }
+  return result.removed;
+}
+
 function updateCodexMarketplace(marketplaceFile, existingMarketplace = null) {
   const marketplace = existingMarketplace
     || (fileExists(marketplaceFile)
       ? readJson(marketplaceFile)
       : {
-        name: "local-plugins",
+        name: CODEX_MARKETPLACE_NAME,
         interface: {
           displayName: "Local Plugins",
         },
@@ -29,10 +89,10 @@ function updateCodexMarketplace(marketplaceFile, existingMarketplace = null) {
   marketplace.plugins = Array.isArray(marketplace.plugins) ? marketplace.plugins : [];
 
   const nextEntry = {
-    name: "helloloop",
+    name: CODEX_PLUGIN_NAME,
     source: {
       source: "local",
-      path: "./plugins/helloloop",
+      path: `./plugins/${CODEX_PLUGIN_NAME}`,
     },
     policy: {
       installation: "AVAILABLE",
@@ -41,7 +101,7 @@ function updateCodexMarketplace(marketplaceFile, existingMarketplace = null) {
     category: "Coding",
   };
 
-  const existingIndex = marketplace.plugins.findIndex((plugin) => plugin?.name === "helloloop");
+  const existingIndex = marketplace.plugins.findIndex((plugin) => plugin?.name === CODEX_PLUGIN_NAME);
   if (existingIndex >= 0) {
     marketplace.plugins.splice(existingIndex, 1, nextEntry);
   } else {
@@ -58,7 +118,7 @@ function removeCodexMarketplaceEntry(marketplaceFile, existingMarketplace = null
 
   const marketplace = existingMarketplace || readJson(marketplaceFile);
   const plugins = Array.isArray(marketplace.plugins) ? marketplace.plugins : [];
-  const nextPlugins = plugins.filter((plugin) => plugin?.name !== "helloloop");
+  const nextPlugins = plugins.filter((plugin) => plugin?.name !== CODEX_PLUGIN_NAME);
   if (nextPlugins.length === plugins.length) {
     return false;
   }
@@ -70,49 +130,101 @@ function removeCodexMarketplaceEntry(marketplaceFile, existingMarketplace = null
 
 export function installCodexHost(bundleRoot, options = {}) {
   const resolvedCodexHome = resolveHomeDir(options.codexHome, ".codex");
-  const targetPluginsRoot = path.join(resolvedCodexHome, "plugins");
-  const targetPluginRoot = path.join(targetPluginsRoot, "helloloop");
-  const marketplaceFile = path.join(resolvedCodexHome, ".agents", "plugins", "marketplace.json");
+  const resolvedLocalRoot = resolveCodexLocalRoot(options.codexHome);
+  const targetPluginsRoot = path.join(resolvedLocalRoot, "plugins");
+  const targetPluginRoot = path.join(targetPluginsRoot, CODEX_PLUGIN_NAME);
+  const legacyTargetPluginRoot = path.join(resolvedCodexHome, "plugins", CODEX_PLUGIN_NAME);
+  const targetPluginCacheRoot = path.join(
+    resolvedCodexHome,
+    "plugins",
+    "cache",
+    CODEX_MARKETPLACE_NAME,
+    CODEX_PLUGIN_NAME,
+  );
+  const targetInstalledPluginRoot = path.join(targetPluginCacheRoot, "local");
+  const marketplaceFile = path.join(resolvedLocalRoot, ".agents", "plugins", "marketplace.json");
+  const legacyMarketplaceFile = path.join(resolvedCodexHome, ".agents", "plugins", "marketplace.json");
+  const configFile = path.join(resolvedCodexHome, "config.toml");
   const manifestFile = path.join(bundleRoot, ".codex-plugin", "plugin.json");
   const existingMarketplace = readExistingJsonOrThrow(marketplaceFile, "Codex marketplace 配置");
+  const existingLegacyMarketplace = legacyMarketplaceFile === marketplaceFile
+    ? existingMarketplace
+    : readExistingJsonOrThrow(legacyMarketplaceFile, "Codex legacy marketplace 配置");
 
   if (!fileExists(manifestFile)) {
     throw new Error(`未找到 Codex 插件 manifest：${manifestFile}`);
   }
 
-  assertPathInside(resolvedCodexHome, targetPluginRoot, "Codex 目标插件目录");
+  assertPathInside(resolvedLocalRoot, targetPluginRoot, "Codex 本地插件目录");
+  assertPathInside(resolvedCodexHome, targetPluginCacheRoot, "Codex 插件缓存目录");
   removeTargetIfNeeded(targetPluginRoot, options.force);
+  removeTargetIfNeeded(targetPluginCacheRoot, options.force);
+  if (legacyTargetPluginRoot !== targetPluginRoot) {
+    removePathIfExists(legacyTargetPluginRoot);
+  }
 
   ensureDir(targetPluginsRoot);
   ensureDir(targetPluginRoot);
+  ensureDir(targetInstalledPluginRoot);
   copyBundleEntries(bundleRoot, targetPluginRoot, codexBundleEntries);
+  copyBundleEntries(bundleRoot, targetInstalledPluginRoot, codexBundleEntries);
   removePathIfExists(path.join(targetPluginRoot, ".git"));
+  removePathIfExists(path.join(targetInstalledPluginRoot, ".git"));
 
   ensureDir(path.dirname(marketplaceFile));
   updateCodexMarketplace(marketplaceFile, existingMarketplace);
+  if (legacyMarketplaceFile !== marketplaceFile) {
+    removeCodexMarketplaceEntry(legacyMarketplaceFile, existingLegacyMarketplace);
+  }
+  upsertCodexPluginConfig(configFile);
 
   return {
     host: "codex",
     displayName: "Codex",
     targetRoot: targetPluginRoot,
+    installedRoot: targetInstalledPluginRoot,
     marketplaceFile,
+    configFile,
   };
 }
 
 export function uninstallCodexHost(options = {}) {
   const resolvedCodexHome = resolveHomeDir(options.codexHome, ".codex");
-  const targetPluginRoot = path.join(resolvedCodexHome, "plugins", "helloloop");
-  const marketplaceFile = path.join(resolvedCodexHome, ".agents", "plugins", "marketplace.json");
+  const resolvedLocalRoot = resolveCodexLocalRoot(options.codexHome);
+  const targetPluginRoot = path.join(resolvedLocalRoot, "plugins", CODEX_PLUGIN_NAME);
+  const legacyTargetPluginRoot = path.join(resolvedCodexHome, "plugins", CODEX_PLUGIN_NAME);
+  const targetPluginCacheRoot = path.join(
+    resolvedCodexHome,
+    "plugins",
+    "cache",
+    CODEX_MARKETPLACE_NAME,
+    CODEX_PLUGIN_NAME,
+  );
+  const marketplaceFile = path.join(resolvedLocalRoot, ".agents", "plugins", "marketplace.json");
+  const legacyMarketplaceFile = path.join(resolvedCodexHome, ".agents", "plugins", "marketplace.json");
+  const configFile = path.join(resolvedCodexHome, "config.toml");
   const existingMarketplace = readExistingJsonOrThrow(marketplaceFile, "Codex marketplace 配置");
+  const existingLegacyMarketplace = legacyMarketplaceFile === marketplaceFile
+    ? existingMarketplace
+    : readExistingJsonOrThrow(legacyMarketplaceFile, "Codex legacy marketplace 配置");
 
   const removedPlugin = removePathIfExists(targetPluginRoot);
+  const removedLegacyPlugin = legacyTargetPluginRoot === targetPluginRoot
+    ? false
+    : removePathIfExists(legacyTargetPluginRoot);
+  const removedCache = removePathIfExists(targetPluginCacheRoot);
   const removedMarketplace = removeCodexMarketplaceEntry(marketplaceFile, existingMarketplace);
+  const removedLegacyMarketplace = legacyMarketplaceFile === marketplaceFile
+    ? false
+    : removeCodexMarketplaceEntry(legacyMarketplaceFile, existingLegacyMarketplace);
+  const removedConfig = removeCodexPluginConfig(configFile);
 
   return {
     host: "codex",
     displayName: "Codex",
     targetRoot: targetPluginRoot,
-    removed: removedPlugin || removedMarketplace,
+    removed: removedPlugin || removedLegacyPlugin || removedCache || removedMarketplace || removedLegacyMarketplace || removedConfig,
     marketplaceFile,
+    configFile,
   };
 }

package/src/install_shared.mjs

@@ -31,6 +31,14 @@ export function resolveHomeDir(homeDir, defaultDirName) {
   return path.resolve(homeDir || path.join(os.homedir(), defaultDirName));
 }
 
+export function resolveCodexLocalRoot(codexHome) {
+  const resolvedCodexHome = resolveHomeDir(codexHome, ".codex");
+  if (path.basename(resolvedCodexHome).toLowerCase() === ".codex") {
+    return path.dirname(resolvedCodexHome);
+  }
+  return resolvedCodexHome;
+}
+
 export function assertPathInside(parentDir, targetDir, label) {
   const relative = path.relative(parentDir, targetDir);
   if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {