fix(codex): migrate skill to documented user path

README.md

@@ -491,7 +491,7 @@ overwrite user-modified agents.
 | Agent | Activation | MCP config | Durable context / augmentation |
 |-------|------------|------------|--------------------------------|
 | Claude Code | Detected | `~/.claude.json` | Skill + three exact-tool graph agents; `SessionStart`, `SubagentStart`, non-blocking `PreToolUse` for `Grep`/`Glob`/`Bash`, and post-`Read` coverage |
-| Codex CLI | Detected | `$CODEX_HOME/config.toml` | Managed `AGENTS.md` activation pointer, skill, three read-only agents; `SessionStart` + `SubagentStart` |
+| Codex CLI | Detected | `$CODEX_HOME/config.toml` | Managed `AGENTS.md` activation pointer, `~/.agents/skills/codebase-memory/SKILL.md`, three read-only agents; `SessionStart` + `SubagentStart` |
 | Gemini CLI | Detected | `.gemini/settings.json` | `GEMINI.md`, three explicit read/graph-tool subagents; `BeforeTool`, `AfterTool` `read_file` coverage, and `SessionStart` |
 | Zed | Detected | platform `settings.json` (JSONC) | `AGENTS.md` + shared skill |
 | OpenCode | Detected | `$OPENCODE_CONFIG` or resolved global config | `AGENTS.md`, skill, three deny-by-default read-only agents; plugin adds grep/glob graph lookup, post-`read` coverage, first-tool-result session context, and post-compaction reinjection |
@@ -540,6 +540,11 @@ For Codex, install keeps only a tiny managed activation pointer in global
 `$CODEX_HOME/AGENTS.md`; all detailed behavior lives in the installed `codebase-memory` skill.
 Fresh installs create the pointer, upgrades replace the legacy full managed block while preserving
 all user-owned bytes, and uninstall removes only the managed pointer.
+Skill placement follows the cross-client user skill root and does not follow
+`CODEX_HOME`. On upgrade, the installer migrates an installer-owned legacy
+`$CODEX_HOME/skills/codebase-memory/SKILL.md` only after verifying the canonical
+copy. Modified or foreign files are preserved; `--force` explicitly authorizes
+replacement before migration.
 
 ### Sessions, compaction, and subagents
 

scripts/smoke-test.sh

@@ -1313,6 +1313,118 @@ fi
 echo ""
 echo "=== Phase 8: agent config install E2E ==="
 
+# Keep Codex skill placement independent from the broad multi-client fixture:
+# Warp and OpenHands share the canonical root and could otherwise mask a Codex
+# regression by creating the expected file themselves.
+CODEX_ONLY_HOME=$(smoke_mktemp_dir)
+CODEX_ONLY_CONFIG="$CODEX_ONLY_HOME/vendor-codex"
+CODEX_ONLY_INSTALL="$CODEX_ONLY_HOME/bin"
+CODEX_ONLY_SKILL="$CODEX_ONLY_HOME/.agents/skills/codebase-memory/SKILL.md"
+CODEX_ONLY_LEGACY="$CODEX_ONLY_CONFIG/skills/codebase-memory/SKILL.md"
+mkdir -p "$CODEX_ONLY_CONFIG" "$CODEX_ONLY_INSTALL"
+if [[ "$BINARY" == *.exe ]]; then
+  CODEX_ONLY_BIN="$CODEX_ONLY_INSTALL/codebase-memory-mcp.exe"
+else
+  CODEX_ONLY_BIN="$CODEX_ONLY_INSTALL/codebase-memory-mcp"
+fi
+CODEX_ONLY_LOG=$(smoke_mktemp_file)
+run_codex_only() {
+  local executable="$1"
+  shift
+  HOME="$CODEX_ONLY_HOME" \
+    XDG_CONFIG_HOME="$CODEX_ONLY_HOME/.config" \
+    APPDATA="$CODEX_ONLY_HOME/AppData/Roaming" \
+    LOCALAPPDATA="$CODEX_ONLY_HOME/AppData/Local" \
+    CODEX_HOME="$CODEX_ONLY_CONFIG" \
+    "$executable" "$@" > "$CODEX_ONLY_LOG" 2>&1
+}
+if ! run_codex_only "$BINARY" install -y --clients=codex --dir="$CODEX_ONLY_INSTALL"; then
+  echo "FAIL 8-codex-1: isolated Codex install failed"
+  cat "$CODEX_ONLY_LOG"
+  exit 1
+fi
+if ! grep -q '^name: codebase-memory$' "$CODEX_ONLY_SKILL" 2>/dev/null ||
+   ! grep -q 'trace_path' "$CODEX_ONLY_SKILL" 2>/dev/null ||
+   [ -e "$CODEX_ONLY_LEGACY" ]; then
+  echo "FAIL 8-codex-1: Codex skill was not installed exclusively at the canonical path"
+  cat "$CODEX_ONLY_LOG"
+  exit 1
+fi
+
+CODEX_ONLY_HASH=$(smoke_file_sha256 "$CODEX_ONLY_SKILL")
+if ! run_codex_only "$CODEX_ONLY_BIN" install --plan --clients=codex \
+     --dir="$CODEX_ONLY_INSTALL" ||
+   [ "$(smoke_file_sha256 "$CODEX_ONLY_SKILL")" != "$CODEX_ONLY_HASH" ]; then
+  echo "FAIL 8-codex-2: Codex install plan mutated the canonical skill"
+  cat "$CODEX_ONLY_LOG"
+  exit 1
+fi
+if ! run_codex_only "$CODEX_ONLY_BIN" install --dry-run -y --clients=codex \
+     --dir="$CODEX_ONLY_INSTALL" ||
+   [ "$(smoke_file_sha256 "$CODEX_ONLY_SKILL")" != "$CODEX_ONLY_HASH" ]; then
+  echo "FAIL 8-codex-2: Codex dry-run mutated the canonical skill"
+  cat "$CODEX_ONLY_LOG"
+  exit 1
+fi
+
+mkdir -p "$(dirname "$CODEX_ONLY_LEGACY")"
+mv "$CODEX_ONLY_SKILL" "$CODEX_ONLY_LEGACY"
+if ! run_codex_only "$CODEX_ONLY_BIN" install -y --clients=codex \
+     --dir="$CODEX_ONLY_INSTALL"; then
+  echo "FAIL 8-codex-3: isolated Codex legacy migration failed"
+  cat "$CODEX_ONLY_LOG"
+  exit 1
+fi
+if ! grep -q '^name: codebase-memory$' "$CODEX_ONLY_SKILL" 2>/dev/null ||
+   [ -e "$CODEX_ONLY_LEGACY" ]; then
+  echo "FAIL 8-codex-3: Codex legacy skill was not migrated to the canonical path"
+  cat "$CODEX_ONLY_LOG"
+  exit 1
+fi
+
+rm -f "$CODEX_ONLY_SKILL"
+mkdir -p "$(dirname "$CODEX_ONLY_LEGACY")"
+printf '%s\n' '---' 'name: codebase-memory' '---' 'User-owned legacy skill.' \
+  > "$CODEX_ONLY_LEGACY"
+CODEX_ONLY_FOREIGN_HASH=$(smoke_file_sha256 "$CODEX_ONLY_LEGACY")
+if ! run_codex_only "$CODEX_ONLY_BIN" install -y --clients=codex \
+     --dir="$CODEX_ONLY_INSTALL" ||
+   [ -e "$CODEX_ONLY_SKILL" ] ||
+   [ "$(smoke_file_sha256 "$CODEX_ONLY_LEGACY")" != "$CODEX_ONLY_FOREIGN_HASH" ]; then
+  echo "FAIL 8-codex-4: non-force install did not preserve a foreign legacy skill"
+  cat "$CODEX_ONLY_LOG"
+  exit 1
+fi
+mkdir -p "$CODEX_ONLY_HOME/.openhands"
+if ! run_codex_only "$CODEX_ONLY_BIN" install -y --clients=codex,openhands \
+     --dir="$CODEX_ONLY_INSTALL" ||
+   ! grep -q '^name: codebase-memory$' "$CODEX_ONLY_SKILL" 2>/dev/null ||
+   [ "$(smoke_file_sha256 "$CODEX_ONLY_LEGACY")" != "$CODEX_ONLY_FOREIGN_HASH" ]; then
+  echo "FAIL 8-codex-5: a foreign Codex legacy skill blocked a shared-client install"
+  cat "$CODEX_ONLY_LOG"
+  exit 1
+fi
+rm -f "$CODEX_ONLY_SKILL"
+if ! run_codex_only "$CODEX_ONLY_BIN" install --force -y --clients=codex \
+     --dir="$CODEX_ONLY_INSTALL" ||
+   ! grep -q '^name: codebase-memory$' "$CODEX_ONLY_SKILL" 2>/dev/null ||
+   [ -e "$CODEX_ONLY_LEGACY" ]; then
+  echo "FAIL 8-codex-6: force did not converge a foreign legacy skill"
+  cat "$CODEX_ONLY_LOG"
+  exit 1
+fi
+CODEX_ONLY_HASH=$(smoke_file_sha256 "$CODEX_ONLY_SKILL")
+if ! run_codex_only "$CODEX_ONLY_BIN" install -y --clients=codex \
+     --dir="$CODEX_ONLY_INSTALL" ||
+   [ "$(smoke_file_sha256 "$CODEX_ONLY_SKILL")" != "$CODEX_ONLY_HASH" ]; then
+  echo "FAIL 8-codex-7: repeated Codex install was not idempotent"
+  cat "$CODEX_ONLY_LOG"
+  exit 1
+fi
+echo "OK: Codex skill placement, previews, migration, force, and idempotence"
+smoke_rmtree "$CODEX_ONLY_HOME"
+rm -f "$CODEX_ONLY_LOG"
+
 # Set up an isolated HOME. Directory-only agents get only the root required for
 # detection; CLI-detected agents use stubs below so install must create their
 # config parents from scratch.
@@ -1724,6 +1836,8 @@ fi
 CODEX_LIFECYCLE_HOME=$(smoke_mktemp_dir)
 CODEX_LIFECYCLE_ROOT="$CODEX_LIFECYCLE_HOME/.codex"
 CODEX_INSTRUCTIONS="$CODEX_LIFECYCLE_ROOT/AGENTS.md"
+CODEX_LIFECYCLE_SKILL="$CODEX_LIFECYCLE_HOME/.agents/skills/codebase-memory/SKILL.md"
+CODEX_LIFECYCLE_LEGACY_SKILL="$CODEX_LIFECYCLE_ROOT/skills/codebase-memory/SKILL.md"
 mkdir -p "$CODEX_LIFECYCLE_ROOT"
 
 CODEX_FRESH_LOG=$(smoke_mktemp_file)
@@ -1737,7 +1851,8 @@ if [ ! -f "$CODEX_INSTRUCTIONS" ] ||
    [ "$(smoke_file_sha256 "$CODEX_INSTRUCTIONS")" != \
      "$(smoke_file_sha256 "$CODEX_POINTER_EXPECTED")" ] ||
    ! grep -q '\[mcp_servers.codebase-memory-mcp\]' "$CODEX_LIFECYCLE_ROOT/config.toml" ||
-   ! grep -q 'search_graph' "$CODEX_LIFECYCLE_ROOT/skills/codebase-memory/SKILL.md" ||
+   ! grep -q 'search_graph' "$CODEX_LIFECYCLE_SKILL" ||
+   [ -e "$CODEX_LIFECYCLE_LEGACY_SKILL" ] ||
    [ ! -s "$CODEX_LIFECYCLE_ROOT/agents/codebase-memory-scout.toml" ] ||
    [ ! -s "$CODEX_LIFECYCLE_ROOT/agents/codebase-memory.toml" ] ||
    [ ! -s "$CODEX_LIFECYCLE_ROOT/agents/codebase-memory-auditor.toml" ] ||
@@ -1834,8 +1949,10 @@ if ! HOME="$CODEX_LIFECYCLE_HOME" \
 fi
 if [ ! -f "$CODEX_INSTRUCTIONS" ] ||
    [ "$(smoke_file_sha256 "$CODEX_INSTRUCTIONS")" != \
-     "$(smoke_file_sha256 "$CODEX_EXPECTED_USER")" ]; then
-  echo "FAIL 8i: Codex uninstall did not remove only the activation pointer"
+     "$(smoke_file_sha256 "$CODEX_EXPECTED_USER")" ] ||
+   [ -e "$CODEX_LIFECYCLE_SKILL" ] ||
+   [ -e "$CODEX_LIFECYCLE_LEGACY_SKILL" ]; then
+  echo "FAIL 8i: Codex uninstall did not remove only installer-owned surfaces"
   exit 1
 fi
 echo "OK 8i: isolated Codex activation-pointer lifecycle"